Configuration

Cette page décrit les classes qui peuvent être utilisées pour créer une vue de configuration de widget avec des champs de configuration personnalisés. La vue de configuration du widget est la partie du widget qui permet à l'utilisateur de configurer les paramètres du widget pour présentation.

Widget

La classe de widget principale, étend la classe de base de tous les widgets du tableau de bord - CWidget. Requis pour remplacer le comportement par défaut du widget.

La classe Widget doit être située dans le répertoire racine du widget (par exemple, ui/modules/my_custom_widget).

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

Formulaire de widget

La classe WidgetForm étend la classe par défaut CWidgetForm et contient un ensemble de champs CWidgetField qui sont nécessaires pour définir la structure de stockage de la configuration des widgets dans la base de données et gérer la validation des entrées.

La classe WidgetForm doit être située dans le répertoire includes. Si la classe a un nom différent, le nom doit être spécifié dans le paramètre widget/form_class du fichier manifest.json.

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

CWidgetFormView

La classe CWidgetFormView est requise pour spécifier la logique de présentation des champs définis dans la classe WidgetForm,déterminer leur apparence et leur comportement lors du rendu dans la vue de configuration.

La classe CWidgetFormView prend en charge les méthodes suivantes:

  • addField() - reçoit une instance de la classe CWidgetFieldView en paramètre ; chaques classes CWidgetField , possède une classe CWidgetFieldView à utiliser dans la vue de configuration du widget.
  • includeJsFile() - permet d'ajouter un fichier JavaScript à la vue de configuration du widget.
  • addJavaScript() - permet d'ajouter du JavaScript en ligne qui sera exécuté dès que la vue de configuration du widget sera chargée.

La classe CWidgetFormView doit être située dans le répertoire views.

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();

JavaScript

Une classe JavaScript peut être utilisée pour ajouter un comportement dynamique et une interactivité à la vue de configuration du widget.Par exemple, vous pouvez initialiser un sélecteur de couleurs, défini dans la classe CWidgetFormView.

La classe JavaScript doit être chargée avec le formulaire, elle doit donc être référencée dans la classe CWidgetFormView en utilisant les méthodes includeJsFile() et addJavaScript().

Dans l'exemple ci-dessous, une instance de classe singleton est immédiatement créée et stockée sous le nom window.my_custom_widget_form. Ainsi, ouvrir le formulaire pour la deuxième fois recréera l'instance.

La classe JavaScript doit être située dans le répertoire views.

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

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.

Classe CWidgetField Type de champ de la base de données Description
CWidgetFieldCheckBox int32 Case à cocher.
CWidgetFieldCheckBoxList tableau de int32 Plusieurs cases à cocher sous un seul champ de configuration.
CWidgetFieldColor string Champ de sélection de couleur.
CWidgetFieldDatePicker string Champ de sélection de la date.
CWidgetFieldHostPatternSelect string Champ de multisélection qui permet de sélectionner un ou plusieurs hôtes. Prend en charge la définition de modèles de nom d'hôte (tous les hôtes correspondants seront sélectionnés).
CWidgetFieldIntegerBox int32 Champ pour saisir un entier. Peut être utilisé pour configurer les valeurs minimales et maximales.
CWidgetFieldLatLng string Zone de texte permettant de saisir la latitude, la longitude et le niveau de zoom de la carte, séparés par des virgules.
CWidgetFieldMultiSelectAction ID Champ de multisélection de sélection d'actions (dans la liste des actions définies dans Alertes → Actions).
CWidgetFieldMultiSelectGraph ID Champ de multisélection pour sélectionner des graphiques personnalisés.
CWidgetFieldMultiSelectGraphPrototype ID Champ de multisélection pour sélectionner des prototypes de graphiques personnalisés.
CWidgetFieldMultiSelectGroup ID Champ de multisélection pour la sélection des groupes d'hôtes.
CWidgetFieldMultiSelectHost ID Champ de multisélection pour la sélection des hôtes.
CWidgetFieldMultiSelectItem ID Champ de multisélection pour la sélection d'éléments.
CWidgetFieldMultiSelectItemPrototype ID Champ de multisélection pour la sélection des prototypes d'éléments.
CWidgetFieldMultiSelectMediaType ID Champ de multisélection pour sélectionner les types de médias..
CWidgetFieldMultiSelectService ID Champ de multisélection pour la sélection des services.
CWidgetFieldMultiSelectSla ID Champ de multisélection pour la sélection des SLA.
CWidgetFieldMultiSelectUser ID Champ de multisélection pour la sélection des utilisateurs.
CWidgetFieldNumericBox string Champ pour saisir un nombre flottant.
CWidgetFieldRadioButtonList int32 Groupe de Radio box composé d'un ou plusieurs Radio box.
CWidgetFieldRangeControl int32 Curseur pour sélectionner une valeur de type entier.
CWidgetFieldSelect int32 Boîte de sélection déroulante.
CWidgetFieldSeverities tableau de int32 CWidgetFieldCheckBoxList presets avec sévérités de déclenchement.
CWidgetFieldTags tableau de (string, int32, string) Permet de configurer une ou plusieurs lignes de filtre de balises.
CWidgetFieldTextArea string Zone de texte pour saisir du texte multiligne.
CWidgetFieldTextBox string Text box for entering single-line text.
CWidgetFieldTimeZone string boite de sélection déroulante avec les fuseaux horaires.
CWidgetFieldUrl string Zone de texte permettant de saisir des URL.

Les classes CWidgetField suivantes ont été créées pour des widgets particuliers.Ces classes ont des cas d’utilisation très spécifiques, mais elles peuvent également être réutilisées si nécessaire:

Classe CWidgetField Type de champ de la base de données Description
CWidgetFieldColumnsList tableau de (multiple mixed) Pour le widget Top des hôtes. Créez un tableau avec des colonnes personnalisées de types autorisés.
CWidgetFieldGraphDataSet tableau de (multiple mixed) Pour le widget Graphique. Configurer la configuration de l'ensemble de données et toutes les options associées.
CWidgetFieldGraphOverride tableau de (multiple mixed) Pour le widget Graphique. Remplacements de configuration pour des hôtes/éléments spécifiques. Toute configuration d'ensemble de données peut être remplacée.
CWidgetFieldNavTree string Pour le widget Arborescence des cartes. Remplace la vue widget en mode édition par l'arborescence de sélection de carte.
CWidgetFieldReference string Pour le widget Arborescence des cartes. Crée un identifiant unique pour ce widget sur le tableau de bord. Il est utilisé pour référencer ce widget à partir d'autres widgets.
CWidgetFieldSelectResource ID Pour le widget Carte. Permet de sélectionner la carte du réseau Zabbix.
CWidgetFieldThresholds tableau de (string, string) Pour le widget Top des hôtes. Permet de configurer des paires de couleurs et de chiffres.
CWidgetFieldWidgetSelect string Pour le widget Carte. Permet de sélectionner une arborescence de navigation des cartes à partir du tableau de bord actuel. Doit être utilisé en combinaison avec CWidgetFieldReference dans le widget Arborescence des cartes.