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

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 du widget.

Les classes CWidgetField suivantes sont disponibles.