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.
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')
]
];
}
}
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 function addFields(): self {
return $this
->addField(
(new CWidgetFieldMultiSelectItem('itemid', _('Item')))
->setFlags(CWidgetField::FLAG_NOT_EMPTY | CWidgetField::FLAG_LABEL_ASTERISK)
->setMultiple(false)
->setFilterParameter('numeric', true)
)
->addField(
new CWidgetFieldTextBox('description', _('Description'))
)
->addField(
(new CWidgetFieldColor('chart_color', _('Color')))->setDefault('FF0000')
);
}
}
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:
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 Zabbix\Widgets\Fields\CWidgetFieldGraphDataSet;
(new CWidgetFormView($data))
->addField(
new CWidgetFieldMultiSelectItemView($data['fields']['itemid'], $data['captions']['items']['itemid'])
)
->addField(
new CWidgetFieldTextBoxView($data['fields']['description']),
'js-advanced-configuration'
)
->addField(
new CWidgetFieldColorView($data['fields']['chart_color']),
'js-advanced-configuration'
)
->includeJsFile('widget.edit.js.php')
->addJavaScript('my_widget_form.init('.json_encode([
'color_palette' => CWidgetFieldGraphDataSet::DEFAULT_COLOR_PALETTE
], JSON_THROW_ON_ERROR).');')
->show();
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\LessonGaugeChart\Widget;
?>
window.widget_lesson_gauge_chart_form = new class {
init({color_palette}) {
this._advanced_configuration = document.getElementById('adv_conf');
this._advanced_configuration.addEventListener('change', () => this.updateForm());
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'); });
}
this.updateForm();
}
updateForm() {
const show_advanced_configuration = this._advanced_configuration.checked;
for (const element of this._form.querySelectorAll('.js-advanced-configuration')) {
element.style.display = show_advanced_configuration ? '' : 'none';
}
}
};
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.
CWidgetField class | Database field type | Description |
---|---|---|
CWidgetFieldCheckBox | int32 | Single checkbox. |
CWidgetFieldCheckBoxList | array of int32 | Multiple checkboxes under a single configuration field. |
CWidgetFieldColor | string | Color selection field. |
CWidgetFieldDatePicker | string | Date selection field. |
CWidgetFieldHostPatternSelect | string | Multiselect field that allows to select one or multiple hosts. Supports defining host name patterns (all matching hosts will be selected). |
CWidgetFieldIntegerBox | int32 | Field to enter an integer. Can be used to configure minimum and maximum values. |
CWidgetFieldLatLng | string | Text box that allows to enter comma-separated latitude, longitude, and map zoom level. |
CWidgetFieldMultiSelectAction | ID | Multiselect field for selecting actions (from the list of actions defined in the Alerts → Actions). |
CWidgetFieldMultiSelectGraph | ID | Multiselect field for selecting custom graphs. |
CWidgetFieldMultiSelectGraphPrototype | ID | Multiselect field for selecting custom graph prototypes. |
CWidgetFieldMultiSelectGroup | ID | Multiselect field for selecting host groups. |
CWidgetFieldMultiSelectHost | ID | Multiselect field for selecting hosts. |
CWidgetFieldMultiSelectItem | ID | Multiselect field for selecting items. |
CWidgetFieldMultiSelectItemPrototype | ID | Multiselect field for selecting item prototypes. |
CWidgetFieldMultiSelectMediaType | ID | Multiselect field for selecting media types. |
CWidgetFieldMultiSelectService | ID | Multiselect field for selecting services. |
CWidgetFieldMultiSelectSla | ID | Multiselect field for selecting SLAs. |
CWidgetFieldMultiSelectUser | ID | Multiselect field for selecting users. |
CWidgetFieldNumericBox | string | Field to enter a float number. |
CWidgetFieldRadioButtonList | int32 | Radio box group that consists of one or more radio boxes. |
CWidgetFieldRangeControl | int32 | Slider to select an integer type value. |
CWidgetFieldSelect | int32 | Dropdown select box. |
CWidgetFieldSeverities | array of int32 | CWidgetFieldCheckBoxList preset with trigger severities. |
CWidgetFieldTags | array of (string, int32, string) | Allows to configure one or more tag filter rows. |
CWidgetFieldTextArea | string | Text area for entering multi-line text. |
CWidgetFieldTextBox | string | Text box for entering single-line text. |
CWidgetFieldTimeZone | string | Dropdown with timezones. |
CWidgetFieldUrl | string | Text box that allows to enter URLs. |
The following CWidgetField classes have been created for particular widgets. These classes have very specific use cases, but they can also be reused if needed.
CWidgetField class | Database field type | Description |
---|---|---|
CWidgetFieldColumnsList | array of (multiple mixed) | For Top hosts widget. Create a table with custom columns of allowed types. |
CWidgetFieldGraphDataSet | array of (multiple mixed) | For Graph widget. Setup dataset configuration and all related options. |
CWidgetFieldGraphOverride | array of (multiple mixed) | For Graph widget. Setup overrides for specific hosts/items. Any dataset configuration can be overridden. |
CWidgetFieldNavTree | string | For Map navigation tree widget. Replaces widget view in edit mode with the map selection tree. |
CWidgetFieldReference | string | For Map navigation tree widget. Creates a unique identifier for this widget on dashboard. It is used to reference this widget from other widgets. |
CWidgetFieldSelectResource | ID | For Map widget. Allows to select Zabbix network map. |
CWidgetFieldThresholds | array of (string, string) | For Top hosts widget. Allows to configure color and number pairs. |
CWidgetFieldWidgetSelect | string | For Map widget. Allows to select a map navigation tree from the current dashboard. Must be used in combination with CWidgetFieldReference in the Map navigation tree widget. |