Áú»¢¶Ä²©

°ä´Ç²Ô´Ú¾±²µ³Ü°ù²¹³¦¾±¨®²Ô

Esta p¨¢gina describe las clases que se pueden usar para crear una vista de configuraci¨®n de widgets 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 presentation.

Widget

Clase de widget principal, extiende la clase base de todos los widgets del tablero: CWidget. Necesario para anular el comportamiento predeterminado del widget.

La clase Widget debe estar ubicada en el directorio ra¨ªz del widget (por ejemplo, zabbix/ui/modules/my_custom_widget).

Ejemplo de Widget.php

<?php
       
       namespace Modules\MyCustomWidget;
       
       use Áú»¢¶Ä²©\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 predeterminada CWidgetForm y contiene un conjunto de campos CWidgetField que son necesarios para definir la estructura de almacenamiento de configuraci¨®n del widget en la base de datos y manejar la validaci¨®n de las entradas.

La clase WidgetForm debe estar ubicada 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 Áú»¢¶Ä²©\Widgets\{
           CWidgetField,
           CWidgetForm
       };
       
       use Áú»¢¶Ä²©\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

La clase CWidgetFormView es necesaria para especificar la l¨®gica de presentaci¨®n de los campos definidos en la clase WidgetForm, determinando su apariencia y comportamiento cuando se representan en la vista de configuraci¨®n.

La clase CWidgetFormView admite los siguientes m¨¦todos:

• addField() - recibe una instancia de la clase CWidgetFieldView como par¨¢metro; cada clase CWidgetField tiene una clase CWidgetFieldView respectiva para usar en la vista de configuraci¨®n del widget.
• addFieldset(): recibe una instancia de la clase CWidgetFieldsGroupView que combina campos en un contenedor plegable.
• addFieldsGroup() - recibe una instancia de CWidgetFormFieldsetCollapsibleView que visualmente (con un borde) combina campos en un grupo.
• includeJsFile() - permite agregar un archivo JavaScript a la vista de configuraci¨®n del widget.
• addJavaScript() - permite agregar JavaScript en l¨ªnea que se ejecutar¨¢ tan pronto como se cargue la vista de configuraci¨®n del widget.

La clase CWidgetFormView debe estar ubicada en el directorio views.

ejemplo de vistas/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 de JavaScript para agregar 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, se debe hacer referencia a ella 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 con el nombre window.my_custom_widget_form. Por lo tanto, al abrir el formulario por segunda vez se volver¨¢ a crear la instancia.

La clase JavaScript debe estar ubicada en el directorio views.

ejemplo de vistas/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 cual se 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 del widget.

Las siguientes clases CWidgetField est¨¢n disponibles.

Se han creado las siguientes clases CWidgetField para widgets particulares. Estas clases tienen casos de uso muy espec¨ªficos, pero tambi¨¦n se pueden reutilizar si es necesario.