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

WidgetForm

La classe WidgetForm étend la classe par défaut CWidgetForm et contient un ensemble de champs CWidgetField nécessaires pour définir la structure de stockage de la configuration du widget 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 porte un nom différent, ce nom doit être spécifié dans le paramètre widget/form_class du fichier manifest.json.

Exemple 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', _('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 classe CWidgetFormView est requise pour définir la logique de présentation des champs définis dans la classe WidgetForm, en déterminant leur apparence et leur comportement lors de leur affichage dans la vue de configuration.

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

• addField() - reçoit une instance de la classe CWidgetField en tant que paramètre ; chaque classe CWidgetField possède une classe CWidgetFieldView correspondante à utiliser dans la vue de configuration du widget.
• addFieldset() - reçoit une instance de la classe CWidgetFieldsGroupView, qui regroupe les champs dans un conteneur rétractable.
• addFieldsGroup() - reçoit une instance de CWidgetFormFieldsetCollapsibleView, qui regroupe visuellement les champs (avec une bordure).
• includeJsFile() - permet d'ajouter un fichier JavaScript à la vue de configuration du widget.
• addJavaScript() - permet d'ajouter du code JavaScript intégré qui sera exécuté dès le chargement de la vue de configuration du widget.

La classe CWidgetFormView doit se trouver dans le répertoire views.

Exemple 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

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.

exemple de vues/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 classe CWidgetField est une classe de base dont héritent toutes les classes de champs de formulaire (CWidgetFieldCheckBox, CWidgetFieldTextArea, CWidgetFieldRadioButtonList, etc.). Les classes qui étendent CWidgetField sont responsables de la réception, de l'enregistrement et de la validation des valeurs de configuration des widgets.

Les classes CWidgetField suivantes sont disponibles.