Widgets

Widgets are panels can be placed in pre-defined sections within a blog template. Widgets can list posts, users, contain hard-coded text or just about any content you could think of. The position of widgets are controlled through the settings UI, the list of widgets available to insert into the page are dynamic and can be turned on and off.

Currently the widget data is saved in a JSON file under each blog directory (widgets.json). This is an array with elements keyed by section with nested each widget underneath keyed by type. This currently is a very simple data storage method!

Example widget JSON:

"custom-html": {
    "heading": "Hello world",
    "content": "Test content"
}

Here the widget is of type custom-html and has variables heading and content.

Note this process is likely to change as widgets are now being reviewed!

Creating custom widgets

1. Definition

Similar to routes, menu items and permissions, widgets are defined from a JSON file within each module.

Example widget definition for the custom HTML widget (/app/modules/Widgets/widgets.json):

{
    "key": "customHTML",
    "name": "Custom HTML",
    "description": "Static HTML code",
    "version": 1.0,
    "form": "rbwebdesigns\\blogcms\\Widgets\\forms\\ConfigureCustomHTML",
    "class": "rbwebdesigns\\blogcms\\Widgets\\widgets\\CustomHTML"
}

2. Widget configuration

As you can gather from the above example, there are two further classes that make up a widget. A form class and a main class. The form class defines the data that can be configured by the user for the widget, these fields are shown on the edit widget screen.

The class should extend rbwebdesigns\core\Form. Note in this case the validate and submit functions do need to be present in the class but do not need to be implemented, as all form data is kept client side until and saved in bulk.

See: Form class documentation

3. Getting data

The main class acts as a controller, gathering the required data and then passing it on to a template file. This class should extend the AbstractWidget class which has a constructor that sets up the request, response and blog objects.

The data should be found by using a model class

BlogCMS::model('full\class\Name');

This function should result in a template being rendered by calling:

$this->response->write('template.tpl', 'ModuleName');

4. Creating the template

The template should live under the modules template directory, any configuration variables set in #2 will be accessible in the template.