Configuration

This page describes classes that can be used to create a widget configuration view with custom configuration fields. The widget configuration view is the part of the widget that allows the user to configure widget parameters for presentation.

Widget

Primary widget class, extends the base class of all dashboard widgets - CWidget. Required for overriding the default widget behavior.

The Widget class should be located in the root directory of the widget (for example, zabbix/ui/modules/my_custom_widget).

Widget.php example

<?php

namespace Modules\MyCustomWidget;

use Zabbix\Core\CWidget;

class Widget extends CWidget {

    public const MY_CONSTANT = 0;

    public function getTranslationStrings(): array {
        return [
            'class.widget.js' => [
                'No data' => _('No data')
            ]
        ];
    }
}

WidgetForm

The WidgetForm class extends the default class CWidgetForm and contains a set of CWidgetField fields that are required for defining widget configuration storage structure in the database and handling input validation.

The WidgetForm class should be located in the includes directory. If the class has a different name, the name should be specified in the widget/form_class parameter in the manifest.json file.

includes/WidgetForm.php example

<?php

namespace Modules\MyCustomWidget\Includes;

use Modules\MyCustomWidget\Widget;

use Zabbix\Widgets\{
    CWidgetField,
    CWidgetForm
};

use Zabbix\Widgets\Fields\{
    CWidgetFieldMultiSelectItem,
    CWidgetFieldTextBox,
    CWidgetFieldColor
};

class WidgetForm extends CWidgetForm {

    public const DEFAULT_COLOR_PALETTE = [
        'FF465C', 'B0AF07', '0EC9AC', '524BBC', 'ED1248', 'D1E754', '2AB5FF', '385CC7', 'EC1594', 'BAE37D',
        '6AC8FF', 'EE2B29', '3CA20D', '6F4BBC', '00A1FF', 'F3601B', '1CAE59', '45CFDB', '894BBC', '6D6D6D'
    ];

    public function addFields(): self {
        return $this
            ->addField(
                (new CWidgetFieldMultiSelectItem('itemid', _('Item')))
                    ->setFlags(CWidgetField::FLAG_NOT_EMPTY | CWidgetField::FLAG_LABEL_ASTERISK)
                    ->setMultiple(false)
            )
            ->addField(
                new CWidgetFieldTextBox('description', _('Description'))
            )
            ->addField(
                (new CWidgetFieldColor('chart_color', _('Color')))->setDefault('FF0000')
            );
    }
}

CWidgetFormView

The CWidgetFormView class is required for specifying the presentation logic of the fields defined in the WidgetForm class, determining their appearance and behavior when rendered in the configuration view.

The CWidgetFormView class supports the following methods:

• addField() - receives an instance of the CWidgetFieldView class as a parameter; each CWidgetField class, has a respective CWidgetFieldView class for using in the widget configuration view.
• addFieldset() - receives an instance of the CWidgetFieldsGroupView class that combines fields into a collapsible container.
• addFieldsGroup() - receives an instance of CWidgetFormFieldsetCollapsibleView that visually (with a border) combines fields into a group.
• includeJsFile() - allows to add a JavaScript file to the widget configuration view.
• addJavaScript() - allows to add inline JavaScript that will be executed as soon as the widget configuration view is loaded.

The CWidgetFormView class should be located in the views directory.

views/widget.edit.php example

<?php

/**
 * My custom widget form view.
 *
 * @var CView $this
 * @var array $data
 */

use Modules\MyCustomWidget\Includes\WidgetForm;

(new CWidgetFormView($data))
    ->addField(
        (new CWidgetFieldMultiSelectItemView($data['fields']['itemid']))->setPopupParameter('numeric', true)
    )
    ->addFieldset(
        (new CWidgetFormFieldsetCollapsibleView(_('Advanced configuration')))
            ->addField(
                new CWidgetFieldTextBoxView($data['fields']['description'])
            )
            ->addField(
                new CWidgetFieldColorView($data['fields']['chart_color'])
            )
    )
    ->includeJsFile('widget.edit.js.php')
    ->addJavaScript('my_custom_widget_form.init('.json_encode([
        'color_palette' => WidgetForm::DEFAULT_COLOR_PALETTE
    ]).');')
    ->show();

JavaScript

A JavaScript class can be used to add dynamic behavior and interactivity to the widget configuration view. For example, you can initialize a color picker, defined in the CWidgetFormView class.

The JavaScript class should be loaded with the form, therefore it should be referenced in the CWidgetFormView class by using the methods includeJsFile() and addJavaScript().

In the example below, a singleton class instance is immediately created and stored under the window.my_custom_widget_form name. Thus, opening the form for the second time will re-create the instance.

The JavaScript class should be located in the views directory.

views/widget.edit.js.php example

<?php

use Modules\MyCustomWidget\Widget;

?>

window.my_custom_widget_form = new class {

    init({color_palette}) {
        colorPalette.setThemeColors(color_palette);

        for (const colorpicker of jQuery('.<?= ZBX_STYLE_COLOR_PICKER ?> input')) {
            jQuery(colorpicker).colorpicker();
        }

        const overlay = overlays_stack.getById('widget_properties');

        for (const event of ['overlay.reload', 'overlay.close']) {
            overlay.$dialogue[0].addEventListener(event, () => { jQuery.colorpicker('hide'); });
        }
    }
};

CWidgetField

The CWidgetField class is a base class from which all form field classes (CWidgetFieldCheckBox, CWidgetFieldTextArea, CWidgetFieldRadioButtonList, etc.) are inherited. Classes extending CWidgetField are responsible for receiving, saving, and validating widget configuration values.

The following CWidgetField classes are available.