Widgets

Widgets are reusable controls that have a user interface and a backend controller (the widget class) that prepares the widget data and handles AJAX requests generated by the widget user interface.

# Generic Widgets

Widgets are the backend equivalent of CMS Components. They are similar because they are modular bundles of functionality, supply partials and are named using aliases. The key difference is that backend widgets use YAML markup for their configuration and bind themselves to backend controllers manually.

Widget classes reside inside the widgets directory of the plugin directory. The inner directory name matches the name of the widget class written in lowercase. Widgets can supply assets and partials. An example widget directory structure looks like this:

├── widgets
|   ├── form
|   |   ├── partials
|   |   |   └── _form.php  ← Partial File
|   |   └── assets
|   |       ├── js
|   |       |   └── form.js  ← JavaScript File
|   |       └── css
|   |           └── form.css  ← StyleSheet File
|   └── Form.php  ← Widget Class

# Class Definition

The generic widget classes must extend the Backend\Classes\WidgetBase class. As any other plugin class, generic widget controllers should belong to the plugin namespace. The following is an example of a widget class definition.

namespace Backend\Widgets;

use Backend\Classes\WidgetBase;

class Lists extends WidgetBase
{
    /**
     * @var string defaultAlias to identify this widget.
     */
    protected $defaultAlias = 'list';

    // ...
}

The widget class must contain a render() method for producing the widget markup by rendering a widget partial. Example:

public function render()
{
    return $this->makePartial('list');
}

To pass variables to partials you can either add them to the $vars property.

public function render()
{
    $this->vars['var'] = 'value';

    return $this->makePartial('list');
}

Alternatively you may pass the variables to the second parameter of the makePartial() method:

public function render()
{
    return $this->makePartial('list', ['var' => 'value']);
}

# Binding Widgets to Controllers

A widget should be bound to a backend controller before you can start using it in a backend page or partial. Use the widget's bindToController method for binding it to a controller. The best place to initialize a widget is the controller's beforeDisplay method, which is called from the constructor.

For example, creating a new widget instance and binding it to the controller. Note the constructor takes the controller as the first argument.

public function beforeDisplay()
{
    $myWidget = new MyWidgetClass($this);
    $myWidget->alias = 'myWidget';
    $myWidget->bindToController();
}

After binding the widget you can access it in the controller's view or partial by its alias using the $this->widget property.

<?= $this->widget->myWidget->render() ?>

# Running Code Before AJAX Handlers

Sometimes you may want code to execute before an AJAX handler executes. Defining an init method in the widget allows code to run before every AJAX handler.

function init()
{
    // From a widget class
}

# See Also