So you’ve decided to develop Crisp plugins? It’s easy as cake and this post will guide you through the process.
Docs: https://beta.tosdr.org/docs/index.html
Whats the deal with plugins? Why are they better than editing Crisp yourself?
Modifying the core of crisp is a bad idea as with each update, there is a chance Crisp breaks. with plugins we give you the functionality to extend crisp without modifying the core and making updates easy as cake.
The Plugin
First we have to decide what our awesome plugin name is, for this post I’ll go with Hello World (Creative ain’t it?)
Directory structure
Crisp follows a certain directory structure to work.
.
└── plugins/
└── helloworld/ - This is your plugin folder name, all lowercase, no spaces
├── includes/ - Here lies the PHP code for templates
│ └── views/ - This code gets executed by the template
├── templates/ - This is the template directory to store the twig tpls in
│ └── views/ - These pages get rendered on call
├── hook.php - The hook file gets called regardless which page is opened (Can be renamed)
└── plugin.json - Metadata, the heart of your plugin
We’ll explain in the steps below what the deal with those is.
Create a folder
First off, create a folder. It has to be all lowercase, no special characters except dash and underscore and no spaces
Our folder will be called helloworld and goes into the plugins/ folder.
Your folder should look like this now:
.
└── plugins/
└── helloworld/ - This is your plugin folder name, all lowercase, no spaces
Plugin Metadata
The important part of our plugin is how crisp parses it, thats what the plugin.json is for, it is the heart of your plugin and can do powerful stuff if configured correctly such as: creating translations, database configs and activate dependencies!
A basic skeleton is in the Github repository or down below:
{
"name": "Hello World Plugin",
"description": "Tutorial plugin plugin for CrispCMS",
"hookFile": "hook.php",
"author": "Justin René Back <jback@pixelcatproductions.net>",
"onInstall": {
"createTranslationKeys": {
"en": {
"hello_world": "Hello World"
},
"de": {
"hello_world": "Hallo Welt"
}
},
"createKVStorageItems": {
"display_hello_world": true
},
"activateDependencies": []
},
"onUninstall": {
"deleteData": true,
"deactivateDependencies": [],
"purgeDependencies": []
}
}
So… what are those objects for?
| Property | Description | Tutorial default |
|---|---|---|
| name | The full name of your plugin | Hello World Plugin |
| description | What does your plugin do? | Tutorial plugin plugin for CrispCMS |
| hookFile | A hook file is called regardless which page is visited, its a global script if you may say so and is required! | hook.php |
| author | Thats you! | Justin René Back jback@pixelcatproductions.net |
| onInstall | This object contains more objects which get called during installation | createTranslationKeys, createKVStorageItems, activateDependencies |
| createTranslationKeys | This awesome property will create translations automatically for you | JSON object |
| createKVStorageItems | This property creates default configuration values in the database for you | JSON object |
| activateDependencies | This property will enable all plugins which are listed there first | Empty object |
| onUninstall | This object contains more objects as well which get called during uninstallation | deleteData, deactivateDependencies, purgeDependencies |
| deleteData | If set to true, all database configs will be deleted as well as translation strings the plugin created | true |
| deactivateDependencies | Same as activateDependencies, now its just the other way around | Empty object |
| purgeDependencies | WARNING DANGEROUS! This will purge all plugins defined in the list, meaning deleteData will be forced to true and you will lose all data of that plugin | Empty object |
By now your directory should look like this
.
└── plugins/
└── helloworld/ - This is your plugin folder name, all lowercase, no spaces
└── plugin.json - Metadata, the heart of your plugin
Hook files
Don’t get me hooked on those files. Jokes aside, these files are called regardless of the current page, they are global scripts and should not contain any template renders or echos as they will be displayed everywhere.
Hookfiles have to exist but they can be empty.
The name of the hookfile has to be the same as defined in plugin.json > hookFile and in this case its hook.php
Your directory should look like this by now:
.
└── plugins/
└── helloworld/ - This is your plugin folder name, all lowercase, no spaces
├── plugin.json - Metadata, the heart of your plugin
└── hook.php - The hook file gets called regardless which page is opened
Templates
Now we get to the more important stuff, we want to display a page!
This requires 4 new directories to be created
templates - This is where you store template files
templates/views - These templates will be rendered when called by the same name
includes - The PHP code for your plugin
includes/views - The PHP code of the template/s
Your directory should look like this by now:
.
└── plugins/
└── helloworld/ - This is your plugin folder name, all lowercase, no spaces
├── includes/ - Here lies the PHP code for templates
│ └── views/ - This code gets executed by the template
├── templates/ - This is the template directory to store the twig tpls in
│ └── views/ - These pages get rendered on call
├── hook.php - The hook file gets called regardless which page is opened (Can be renamed)
└── plugin.json - Metadata, the heart of your plugin
Now we will create a page where text will be displayed by calling the page domain.tld/en/helloworld
this requires 2 new files to be created!
templates/views/helloworld.twig - This contains your html code, we fill it with some text!
File contents
<b>My first plugin works, hello world!</b>
includes/views/helloworld.php - This has the php code for the helloworld.twig file; variables, logic code, etc.
File contents
<?php
// We will leave this empty for now!
Your folder should look like this by now:
.
└── plugins/
└── helloworld/ - This is your plugin folder name, all lowercase, no spaces
├── includes/ - Here lies the PHP code for templates
│ └── views/ - This has the php code for the helloworld.twig file; variables, logic code, etc.
│ └── helloworld.php - This has the php code for the helloworld.twig file; variables, logic code, etc.
├── templates/ - This is the template directory to store the twig tpls in
│ └── views/ - These pages get rendered on call
│ └── helloworld.twig - This contains your html code, we fill it with some text!
├── hook.php - The hook file gets called regardless which page is opened
└── plugin.json - Metadata, the heart of your plugin
and will display My first plugin works, hello world! when you visit domain.tld/en/helloworld
Congrats, your first plugin is done!