Configuración

Esta página describe las clases que se pueden utilizar para crear una vista de configuración de widget con campos de configuración personalizados. La vista de configuración del widget es la parte del widget que permite al usuario configurar los parámetros del widget para la presentación.

Widget

Clase principal del widget, extiende la clase base de todos los widgets del panel - CWidget. Requerido para sobrescribir el comportamiento predeterminado del widget.

La clase Widget debe ubicarse en el directorio raíz del widget (por ejemplo, zabbix/ui/modules/my_custom_widget).

Ejemplo de 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

La clase WidgetForm extiende la clase por defecto CWidgetForm y contiene un conjunto de campos CWidgetField que son necesarios para definir la estructura de almacenamiento de la configuración del widget en la base de datos y gestionar la validación de entrada.

La clase WidgetForm debe ubicarse en el directorio includes. Si la clase tiene un nombre diferente, el nombre debe especificarse en el parámetro widget/form_class en el archivo manifest.json.

Ejemplo de 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 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', _('Métrica')))
                    ->setFlags(CWidgetField::FLAG_NOT_EMPTY | CWidgetField::FLAG_LABEL_ASTERISK)
                    ->setMultiple(false)
            )
            ->addField(
                new CWidgetFieldTextBox('description', _('Descripción'))
            )
            ->addField(
                (new CWidgetFieldColor('chart_color', _('Color')))->setDefault('FF0000')
            );
    }
}

CWidgetFormView

La clase CWidgetFormView es necesaria para especificar la lógica de presentación de los campos definidos en la clase WidgetForm y determinar su apariencia y comportamiento al renderizarse en la vista de configuración.

La clase CWidgetFormView admite los siguientes métodos:

• addField(): recibe como parámetro una instancia de la clase CWidgetField; cada clase CWidgetField tiene una clase CWidgetFieldView correspondiente para utilizarla en la vista de configuración del widget.
• addFieldset(): recibe una instancia de la clase CWidgetFieldsGroupView, que combina los campos en un contenedor contraíble.
• addFieldsGroup(): recibe una instancia de CWidgetFormFieldsetCollapsibleView, que combina visualmente los campos en un grupo (con un borde).
• includeJsFile(): permite añadir un archivo JavaScript a la vista de configuración del widget.
• addJavaScript(): permite añadir JavaScript en línea que se ejecutará en cuanto se cargue la vista de configuración del widget.

La clase CWidgetFormView debe ubicarse en el directorio views.

Ejemplo de 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

Se puede utilizar una clase JavaScript para añadir comportamiento dinámico e interactividad a la vista de configuración del widget. Por ejemplo, puede inicializar un selector de color, definido en la clase CWidgetFormView.

La clase JavaScript debe cargarse con el formulario, por lo tanto, debe ser referenciada en la clase CWidgetFormView utilizando los métodos includeJsFile() y addJavaScript().

En el siguiente ejemplo, se crea inmediatamente una instancia de clase singleton y se almacena bajo el nombre window.my_custom_widget_form. Así, al abrir el formulario por segunda vez, se volverá a crear la instancia.

La clase JavaScript debe ubicarse en el directorio views.

Ejemplo de views/widget.edit.js.php

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

La clase CWidgetField es una clase base de la que heredan todas las clases de campos de formulario (CWidgetFieldCheckBox, CWidgetFieldTextArea, CWidgetFieldRadioButtonList, etc.). Las clases que extienden CWidgetField son responsables de recibir, guardar y validar los valores de configuración de los widgets.

Están disponibles las siguientes clases CWidgetField.