A simple plugin

A plugin in blaze consists of at least two files. There is one php file holding the plugin class. It must extend \blaze\src\prototype\Plugin and could look like this:

    <?php

    namespace blaze\plugins\coolplugin;

    class coolplugin extends \blaze\src\prototype\Plugin{

        public function helloWorld(){
            echo 'Hello World';
        }

    }

    ?>

As you see, this is just a very simple php class with a little "hello world" function. In order to have blaze recognizing this plugin, you must provide a file called plugin.json. This is the basic info file which any blaze plugin needs to have. The minimum requirements are some information about the name of the plugin, and whether it uses a database or not. So, for our coolplugin it would be:

    {
        "info" :{
            "name": "coolplugin",
            "usedb": false
        }
    }

After having created those two files, you would create a folder within /webroot/blaze/plugins and copy both files there. The classname and the filename of the class have to be the same. Make sure there is no other activated plugin that uses the name of your plugin. Else there might be a strange behaviour.

You would then head over to the plugin section in the backend and install and activate our newly created plugin. Our hello world would now be available via blaze liko so:

    $blaze->coolplugin->helloWorld();

More advanced plugins

We don't see any real world use case for a plugin as simple as the above example, so let's look at a more complex example.

blaze does provide some more options and possibilities. Here is how a fully fledged plugin.json for our coolplugin could look:

    {
        "info": {
            "name": "coolplugin",
            "description" : "A short description of my cool plugin.",
            "author" : "My Self",
            "documentation" : "http://linkto.mydocs.com",
            "usedb" : true,
            "uiactionprovider" : "myclass.php"
        },
        "sidebar" : {
            "admin" : [
                {
                    "path":"coolpage",
                    "label":"coolpage.navlabel",
                    "icon":"life-saver"
                },
                {
                    "path":"secondcoolpage",
                    "label":"coolpage.secondnavlabel",
                    "icon":"life-saver"
                }
            ],
            "customer" : [
                {
                    "path":"coolpage",
                    "label":"coolpage.navlabel",
                    "icon":"life-saver"
                }
            ],
        },
        "assets" : {
            "coolpage" : [
                "assets/cooljavascriptfile.js",
                "assets/orcoffeescript.coffee",
                "assets/stylus_or_scss_or.less",
                "assets/or.css"
            ],
            "global" : [
                "assets/mycoolassettoincludeoneverybackendpage.css"
            ]
        },
        "specialmethods" : {
            "install" : ["initialize", "databaseSetup"],
            "uninstall" : ["initialize", "deleteTablesFromDatabase"]
        }
    }

We already know the first two options. The usedb option ensures that the plugin will not be loaded or installed when there is no database. If it did, the system could crash or worse, so this is an important parameter.

The other three options in the first section should be self explanatory, and are optional. If you do provide a documentation link, make sure to provide a fully qualilfied url including 'http://' or 'https://'.

The sidebar options

You can add backend views to your plugin. They could be accessible to admins only, to customers only, or to both user roles. In the example above, both userroles will be presented with the same page, they could of course be different. Additionally, admins get a second view in the above example.

  • The path sets the path to the view file relative to your plugins view folder. It has to reside within myplugin/views. In our example, this would be coolplugin/views/coolpage.twig.
  • The label sets the label of the backend page in the sidenav. In case you use localization features, you can provide multiple language versions of this. You can as well just name a string like "My plugins backend page". Read more about blaze's localization in the translation guide and see the tutorial.
  • The icon option sets the icon which should be used in the navigation. blaze uses Font-Awesome, so you have a large range of available icons. Just remove the fa- in front of the icon's name. There is an overview of available icons at Font Awesome.
  • The uiactionprovider makes one class of your plugin directly available to your plugin views. This enables your backend views to communicate with your plugin directly, f.i. to handle buttons or form inputs. There are good explanations of this feature in the plugin tutorial.

Remember to put the views into arrays, even if you only have one of them. You will get an error if you forget that.

The assets options

If your backend pages need extra assets like Javascript or CSS, you can make blaze load them. Just place them anywhere in your plugin folder (We like having an assets folder). Just make sure that you have the correct view name in the assets section of the plugin.json.

blaze supports native Javascript or CSS as well as Stylus, LESS, SCSS and CoffeeScript. Compiling and minifying will be done automatically.

You may want to include an asset on all backend pages, not just one single view. This is possible, too. Use the global as view name, like we did in the example above. The global assets will be shown on all backend pages, even if they don't belong to your plugin.

The specialmethods options

When your plugin is installed or uninstalled from blaze, you may want to do some things, like preparing some database tables or removing them. You may place your functionality within your main plugin class, and specify the method names in the specialmethods section of the plugin.json. Both 'install' and 'uninstall' will take a json array containing strings or a single string.

blaze also offers the possibility to bind methods to events which will be triggered. You may even create and trigger your own events to create really advanced functionality. Read more in the events section.

Debugging the backend

When you are creating a plugin, you may want blaze to stop compiling assets in order to be able to properly debug them. This is possible, however there is no setting switch for this in the backend. You will find a hidden debug flag in the sourcecode. Open the file blaze/src/BackendHandler.php and set the $backenddebug variable at line 28 to true.


Using blaze's components within your plugin

The plugins do not have direct access to the blaze core due to technical limits. But you may of course make use of blaze components within your plugin. Take a look at the webstat plugin: It uses several components from the blaze 'src' folder, like f.i. the database connector to handle database connections.

We will do so as well in the plugin tutorial, so just take a look at it.