Backend views for plugins

blaze's plugin architecture allows you to easily create backend views. Again, it is recommended to take a look at the plugin tutorial in which we do so.

If you want to use backend views, you should read the following conventions that will allow you to do so.

Defining a view

Plugins need a definition file named 'plugin.json'. This file is described in the basics section. In order to define a view in the definition file, you should use the 'sidebar' element with the 'admin' and 'customer' section.

    "sidebar" : {
        "admin" : [
            {
                "path":"coolpage",
                "label":"coolpage.navlabel",
                "icon":"life-saver"
            }
        ],
        "customer" : [
            {
                "path":"coolpage",
                "label":"coolpage.navlabel",
                "icon":"life-saver"
            }
        ],
    }

You can add as many views as you want for both customers and admins. Each view should be represented as object with three parameters:

"path" holding the views filename (without the file extension .twig)

"label" holding the labels description as string or as a translation id (like in the example above)

"icon" holding an icon name coming from Font Awesome, without the leading 'fa-'

Using the example above, you would have added the view 'coolpage', which must reside as a view file within a folder named 'views'. This folder has to be located within your plugin's location.

It's highly recommended to use TWIG for your views, so this view file should be named 'coolpage.twig'.

If you don't know TWIG, it is recommended to take a look at the documentation.

Your backend views should extend a blaze template and provide the block 'maincontent'. Like this:

    {% extends 'backend/apppage.twig' %}

    {% block maincontent %}
        My view content would go here.
    {% endblock %}

Accessing blaze's core

Although plugins do not have access to blaze itself, you may access blaze in the backend views. Just use it like this:

    {% extends 'backend/apppage.twig' %}

    {% block maincontent %}
        {{ blaze.component.dosomething() }}
    {% endblock %}

You may access all components blaze gives you.

Backend UI framework

blaze's backend is completely built with UIkit. To perfectly integrate your view with blaze's look and feel, you should build your interface using the components that UIkit provides.

Take a look at the guides that are available at the UIkit website.

Sending data to your view

If you need to show data in your backend views (you probably will), your plugin class shold use the data providing feature.

Create a method that returns the needed data for your view as array, and register this method as data provider for your view. That might sound complex, but is really easy to do. Here is an example:

    <?php
        namespace blaze\plugins\mycoolplugin;

        class mycoolplugin extends \blaze\src\prototype\Plugin
        {
            function __construct()
            {
                $this->setDataProvider('myview','myviewDataProvider');
            }

            public function myviewDataProvider()
            {
                $data = array('somedata'=>'mydata');
                return $data;
            }
        }
    ?>

Using this example, you could access your data in your view 'myview.twig' like this:

    {% extends 'backend/apppage.twig' %}

    {% block maincontent %}
        The provided data would hold this: {{ mycoolplugin.somedata }}
    {% endblock %}

Backend UI functionality

If you want to process user input in your plugin view, or to execute actions, you might register plugin functions to events you trigger yourself. But there is a much easier way to do so.

blaze's plugin classes are protected and are not accessible from the backend. But don't worry, you will be able to trigger actions via an addiotional php class that will act as a UI action handler. It should reside at the top level of your plugin folder, and the classname must match the filename.

You will need to name this class in the definition file. Methods that you want to use in the UI action handler can use some special functions to trigger basic UI feedbacks like the little checkmark that shows up if an action is successfully executed.

To trigger an action, it is recommended to use a simple jQuery ajax call the .post() function that comes with jQuery. Just create a javascript file for your backend to execute UI actions.

The best possible way to easily use the features blaze provides, your UI action handler class should extend \blaze\src\prototype\UIActionHandler. Here is an example with some explanations underneath.

    <?php
        namespace blaze\plugins\mycoolplugin;

        class uiactions extends \blaze\src\prototype\UIActionHandler
        {
            function __construct()
            {
                // Works if your plugin is named 'mycoolplugin' and properly setup
                $this->mycoolplugin = new mycoolplugin();
            }

            // This is an action you could call via ajax or jQuery's post function
            public function doSomeAction()
            {
                $success = $this->mycoolplugin->actionsToExecute();
                if($success)
                {
                    return true;
                }
                else
                {
                    return 'An error occured';
                }
            }
        }
    ?>

You might wonder why the function just returns true, and does not return false if an error occurs. There are three cases that you might need for such ui actions:

In case of success, you will want to return true. This will automatically cause the UI action handler to send a json encoded success response, which will trigger the little checkmark in the backend.

If you need your backend view to reload after your changes in order to reflect the newly changed data and contents, you should return 'reload'. This will automatically make your backend view reload.

In case of an error you may return any string. Anything that does not match true or 'reload' will be displayed as an error message.

To let blaze know about a UI action handler class, you need to add it to the plugin.json. See the basics guide to find out how.

In order to call the function from the example above in your backend view, you should create a JavaScript like this:

    $(function(){
        $('button.mytrigger').bind('click',function(){
            $.post('/pluginuiaction/mycoolplugin/doSomeAction', function(){ /* callback */ });
        });
    });

You could of course also use Coffeescript.

Again: take a look at the tutorial where you will find an in-depth coding example of all those basic features.

Accessing blaze in the UI action handler

Although the plugin itself does not have access to blaze's core, the UI action handler has. It hold's an instance of blaze which you can access like this:

    $this->blazeinstance->component->doSomething();