Конфигурация

На этой странице описаны классы, которые можно использовать для создания представления конфигурации виджета с настраиваемыми полями конфигурации. Представление конфигурации виджета - это часть виджета, которая позволяет пользователю настраивать параметры виджета для презентации.

Виджет

Основной класс виджетов, расширяет базовый класс всех виджетов информационной панели - CWidget. Требуется для переопределения поведения виджета по умолчанию.

Класс Widget должен находиться в корневом каталоге виджета (например, zabbix/ui/modules/my_custom_widget).

Пример Widget.php

<?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

Класс WidgetForm расширяет класс по умолчанию CWidgetForm и содержит набор полей CWidgetField, которые необходимы для определения структуры хранения конфигурации виджета в базе данных и обработки ввода.

Класс WidgetForm должен находиться в каталоге includes. Если класс имеет другое имя, это имя должно быть указано в параметре widget/form_class в файле manifest.json.

пример includes/WidgetForm.php

<?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')
            );
    }
}

CWidgetFormView

Класс CWidgetFormView необходим для задания логики представления полей, определённых в классе WidgetForm, а также для определения их внешнего вида и поведения при отображении в представлении конфигурации.

Класс CWidgetFormView поддерживает следующие методы:

• addField() - принимает в качестве параметра экземпляр класса CWidgetFieldView; для каждого класса CWidgetField существует соответствующий класс CWidgetFieldView, используемый в представлении конфигурации виджета.
• addFieldset() - принимает экземпляр класса CWidgetFieldsGroupView, который объединяет поля в сворачиваемый контейнер.
• addFieldsGroup() - принимает экземпляр класса CWidgetFormFieldsetCollapsibleView, который визуально (с помощью границы) объединяет поля в группу.
• includeJsFile() - позволяет добавить файл JavaScript в представление конфигурации виджета.
• addJavaScript() - позволяет добавить встроенный JavaScript-код, который будет выполнен сразу после загрузки представления конфигурации виджета.

Класс CWidgetFormView должен находиться в каталоге views.

Пример views/widget.edit.php

<?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

Класс JavaScript можно использовать для добавления динамического поведения и интерактивности в представление конфигурации виджета. Например, вы можете инициализировать палитру цветов, определенную в классе CWidgetFormView.

Класс JavaScript должен быть загружен вместе с формой, поэтому на него следует ссылаться в классе CWidgetFormView с помощью методов includeJsFile() и addJavaScript().

В приведенном ниже примере экземпляр одноэлементного класса сразу создается и сохраняется под именем window.my_custom_widget_form. Таким образом, открытие формы во второй раз приведет к воссозданию экземпляра.

Класс JavaScript должен находиться в каталоге views.

пример views/widget.edit.js.php

<?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';
        }
    }
};

CWidgetField

Класс CWidgetField является базовым классом, от которого наследуются все классы полей формы (CWidgetFieldCheckBox, CWidgetFieldTextArea, CWidgetFieldRadioButtonList и т. д.). Классы, расширяющие CWidgetField, отвечают за получение, сохранение и проверку значений конфигурации виджета.

Доступны следующие классы CWidgetField.