Developing Crisp Plugins

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!

2 Likes

Repository

2 Likes