Présentation

Cette page décrit les composants qui peuvent être utilisés pour créer une vue de présentation de widget. La vue de présentation du widget est la partie du widget qui reçoit les données conformément à sa configuration et les affiche sur le tableau de bord dans un conteneur.

La vue de présentation se compose de trois parties :

• Action du widget
• Vue du widget
• JavaScript

Action du widget

La classe d'action de widget (WidgetView) contient des méthodes pour les opérations avec les widgets en mode d'affichage de présentation. La majorité des actions de widget utilisent et/ou étendent la classe de contrôleur par défaut CControllerDashboardWidgetView.

La classe d'action du widget doit être située dans le répertoire actions et spécifiée dans le paramètre actions (actions/widget.{id}.view/class) dans le fichier manifest.json.

Exemple actions/WidgetView.php (implémenté dans le widget natif Zabbix Informations système)

class WidgetView extends CControllerDashboardWidgetView {

    protected function doAction(): void {
        $this->setResponse(new CControllerResponseData([
            'name' => $this->getInput('name', $this->widget->getDefaultName()),
            'system_info' => CSystemInfoHelper::getData(),
            'info_type' => $this->fields_values['info_type'],
            'user_type' => CWebUser::getType(),
            'user' => [
                'debug_mode' => $this->getDebugMode()
            ]
        ]));
    }
}

Vue des widgets

La classe de vue du widget (CWidgetView) est responsable de la création de la vue de présentation du widget.

La classe de vue du widget doit être située dans le répertoire views. Si le fichier contenant la classe de vue du widget a un nom différent de celui par défaut (widget.view.php), alors il doit être spécifié dans le fichier manifest.jsonsous le parametre actions (actions/widget.{id}.view/view).

exemple de vues/widget.view.php

<?php

/**
 * My custom widget view.
 *
 * @var CView $this
 * @var array $data
 */

(new CWidgetView($data))
    ->addItem(
        new CTag('h1', true, $data['name'])
    )
    ->show();

JavaScript

La classe JavaScript est chargée de déterminer le comportement du widget, tel que la mise à jour des données du widget, le redimensionnement du widget, l'affichage des éléments du widget, etc.

Toutes les opérations JavaScript utilisent et/ou étendent la classe JavaScript de base de tous les widgets du tableau de bord - CWidget. La classe CWidget contient un ensemble de méthodes avec l'implémentation par défaut du comportement des widgets. En fonction de la complexité du widget, ces méthodes peuvent être utilisées telles quelles ou étendues.

La classe CWidget contient les méthodes suivantes :

• Méthodes qui définissent le cycle de vie du widget : _init(), _registerEvents(), _doActivate(), _doDeactivate(), _doDestroy(), setEditMode().
• Méthodes qui gèrent la mise à jour et l'affichage des données du widget: _promiseUpdate(), _getUpdateRequestData(), _processUpdateResponse(response), _processUpdateErrorResponse(error), _setContents().
• Méthodes qui modifient l'apparence du widget: resize(), _hasPadding().

La classe JavaScript doit être située dans le répertoire assets/js et spécifiée dans le paramètre assets (assets/js) dans le fichier manifest.json.

Méthodes de cycle de vie

Les méthodes de cycle de vie du widget sont invoquées par le tableau de bord et à différentes étapes du cycle de vie du widget au cours de son existence au sein du tableau de bord.

La méthode onInitialize() définit l'état initial et/ou les valeurs du widget, sans effectuer de manipulation HTML ou de données. Cette méthode est invoquée lorsqu'un widget est créé (un objet widget est instancié), généralement en ajoutant le widget à une page de tableau de bord ou en chargeant la page du tableau de bord.

Exemple:

onInitialize() {
    this._time_offset = 0;
    this._interval_id = null;
    this._clock_type = CWidgetClock.TYPE_ANALOG;
    this._time_zone = null;
    this._show_seconds = true;
    this._time_format = 0;
    this._tzone_format = 0;
    this._show = [];
    this._has_contents = false;
    this._is_enabled = true;
}

La méthode onStart() définit la structure HTML du widget, sans effectuer aucune manipulation de données. Cette méthode est invoquée avant la première activation de la page du tableau de bord, c'est-à-dire avant que le tableau de bord et ses widgets ne soient entièrement affichés à l'utilisateur.

Exemple:

onStart() {
    this._events.resize = () => {
        const padding = 25;
        const header_height = this._view_mode === ZBX_WIDGET_VIEW_MODE_HIDDEN_HEADER
            ? 0
            : this._header.offsetHeight;

        this._target.style.setProperty(
            '--content-height',
            `${this._cell_height * this._pos.height - padding * 2 - header_height}px`
        );
    }
}

La méthode _doActivate() rend le widget actif et interactif en activant des écouteurs d'événements personnalisés (pour répondre aux actions de l'utilisateur) et en initiant le cycle de mise à jour du widget (pour maintenir son contenu à jour). Cette méthode est invoquée lorsque la page du tableau de bord est activée, c'est-à-dire lorsqu'elle s'affiche entièrement dans l'interface utilisateur.

Notez qu'avant que la méthode _doActivate() ne soit invoquée, le widget est dans l'état inactif (WIDGET_STATE_INACTIVE). Après un appel réussi, le widget passe à l'état actif (WIDGET_STATE_ACTIVE). À l'état actif, le widget est réactif, écoute les événements, met régulièrement à jour son contenu et peut interagir avec d'autres widgets.

Exemple :

_doActivate() {
    super._doActivate();

    if (this._has_contents) {
        this._activateContentsEvents();
    }
}

La méthode _doDeactivate() arrête toute activité et interactivité du widget en désactivant les écouteurs d'événements personnalisés et en arrêtant le cycle de mise à jour du widget. Cette méthode est invoquée lorsque la page du tableau de bord est désactivée, c'est-à-dire désactivée ou supprimée, ou lorsque le widget est supprimé de la page du tableau de bord.

Notez qu'avant que la méthode _doDeactivate() ne soit invoquée, le widget est dans l'état actif (WIDGET_STATE_ACTIVE). Après un appel réussi, le widget passe à l'état inactif (WIDGET_STATE_INACTIVE).

Exemple :

_doDeactivate() {
    super._doDeactivate();

    this._deactivateContentsEvents();
}

La méthode onDestroy() effectue les tâches de nettoyage avant que le widget ne soit supprimé du tableau de bord. Cela peut inclure la fermeture d’une connexion à une base de données établie lors de l’initialisation du widget, le nettoyage des données temporaires afin de libérer de la mémoire système et d’éviter les fuites de ressources, la désinscription des écouteurs d’événements liés aux événements de redimensionnement ou aux clics sur les boutons afin d’éviter le traitement inutile d’événements et les fuites de mémoire, etc. Cette méthode est appelée lorsque le widget ou la page du tableau de bord qui le contient est supprimé.

Notez qu’avant l’appel de la méthode onDestroy(), un widget à l’état actif (WIDGET_STATE_ACTIVE) est toujours désactivé par l’appel de la méthode onDeactivate().

Exemple :

onDestroy() {
    if (this._filter_widget) {
        this._filter_widget.off(CWidgetMap.WIDGET_NAVTREE_EVENT_MARK, this._events.mark);
        this._filter_widget.off(CWidgetMap.WIDGET_NAVTREE_EVENT_SELECT, this._events.select);
    }
}

La méthode onEdit() définit l'apparence et le comportement du widget lorsque le tableau de bord passe en mode édition. Cette méthode est appelée lorsque le tableau de bord passe en mode édition, généralement lorsqu'un utilisateur interagit avec le bouton Edit du widget ou avec le bouton Edit dashboard du tableau de bord.

Exemple :

onEdit() {
    this._deactivateGraph();
}

Méthodes de processus de mise à jour

Les méthodes du processus de mise à jour du widget sont chargées de récupérer les données mises à jour à partir du serveur Zabbix ou de toute autre source de données et de les afficher dans le widget.

La méthode promiseUpdate() initie le processus de mise à jour des données en récupérant les données, généralement à l'aide de requêtes Web ou d'appels API. Cette méthode est appelée lorsqu'une page de tableau de bord est affichée et périodiquement après, jusqu'à ce que la page de tableau de bord soit basculée vers une autre page de tableau de bord.

Ce qui suit est un exemple de l'implémentation par défaut de la méthode promiseUpdate() utilisée par la plupart des widgets natifs de Zabbix. Dans l'implémentation par défaut, la méthode promiseUpdate() suit un modèle général pour récupérer les données du serveur. Elle crée un nouvel objet Curl avec l'URL et les paramètres de requête appropriés, envoie une requête POST à l'aide de la méthode fetch() avec l'objet de données construit par la méthode getUpdateRequestData(), et traite la réponse (ou une réponse d'erreur) avec processUpdateResponse(response) ou processUpdateErrorResponse(error) en conséquence. Cette implémentation convient à la plupart des widgets car ils récupèrent généralement les données au format JSON et les gèrent de manière cohérente.

promiseUpdate() {
const curl = new Curl('zabbix.php');

curl.setArgument('action', `widget.${this._type}.view`);

return fetch(curl.getUrl(), {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify(this.getUpdateRequestData()),
signal: this._update_abort_controller.signal
})
.then((response) => response.json())
.then((response) => {
if ('error' in response) {
this.processUpdateErrorResponse(response.error);

return;
}

this.processUpdateResponse(response);
});
}

La méthode getUpdateRequestData() prépare les données de la requête envoyée au serveur pour mettre à jour le widget en rassemblant diverses propriétés et leurs valeurs correspondantes (identifiants du widget, paramètres de filtre, plages temporelles, etc.) à partir de l’état et de la configuration du widget, puis en construisant un objet de données représentant les informations nécessaires à envoyer au serveur dans la requête de mise à jour.

Cette méthode est appelée uniquement dans le cadre de la méthode promiseUpdate() par défaut, c’est-à-dire pendant le processus de mise à jour du widget.

Implémentation par défaut :

getUpdateRequestData() {
    return {
        templateid: this._dashboard.templateid ?? undefined,
        dashboardid: this._dashboard.dashboardid ?? undefined,
        widgetid: this._widgetid ?? undefined,
        name: this._name !== '' ? this._name : undefined,
        fields: Object.keys(this._fields).length > 0 ? this._fields : undefined,
        view_mode: this._view_mode,
        edit_mode: this._is_edit_mode ? 1 : 0,
        dynamic_hostid: this._dashboard.templateid !== null || this.supportsDynamicHosts()
            ? (this._dynamic_hostid ?? undefined)
            : undefined,
        ...this._contents_size
    };
}

La méthode processUpdateResponse(response) traite la réponse reçue du serveur après la demande de mise à jour et, si le processus de mise à jour s'est déroulé correctement et sans erreur, efface les données du widget et affiche le nouveau contenu avec la méthode setContents().

Cette méthode est appelée uniquement dans le cadre de la méthode promiseUpdate() par défaut, c'est-à-dire pendant le processus de mise à jour du widget.

Implémentation par défaut :

processUpdateResponse(response) {
    this._setHeaderName(response.name);

    this._updateMessages(response.messages);
    this._updateInfo(response.info);
    this._updateDebug(response.debug);

    this.setContents(response);
}

La méthode processUpdateErrorResponse(error) gère la réponse reçue du serveur après la demande de mise à jour si la réponse est une erreur et affiche le ou les messages d'erreur. Cette méthode est invoquée uniquement dans le cadre de la méthode promiseUpdate() par défaut, c'est-à-dire pendant le processus de mise à jour du widget.

Implémentation par défaut :

processUpdateErrorResponse(error) {
this._updateMessages(error.messages, error.title);
}

La méthode setContents(response) affiche le contenu du widget si le processus de mise à jour du widget s'est déroulé correctement et sans erreur. Cela peut inclure la manipulation d'éléments DOM, la mise à jour de composants d'interface utilisateur, l'application de styles ou de formats, etc. Cette méthode est appelée uniquement dans le cadre de la méthode par défaut processUpdateResponse(response), c'est-à-dire lors du traitement de la réponse reçue du serveur après la demande de mise à jour.

Implémentation par défaut :

setContents(response) {
    this._body.innerHTML = response.body ?? '';
}

Méthodes de modification de la présentation

Les méthodes de modification de la présentation du widget sont chargées de modifier l'apparence du widget.

La méthode onResize() est chargée d'ajuster les éléments visuels du widget afin de s'adapter à sa nouvelle taille, ce qui peut inclure la réorganisation des éléments, l'ajustement de leurs dimensions, la troncature du texte, la mise en œuvre du chargement différé pour améliorer la réactivité pendant le redimensionnement, etc. Cette méthode est appelée lorsque le widget est redimensionné, par exemple lorsque l'utilisateur redimensionne manuellement le widget ou lorsque la fenêtre du navigateur est redimensionnée.

Exemple :

onResize() {
    if (this.getState() === WIDGET_STATE_ACTIVE) {
        this._startUpdating();
    }
}

La méthode hasPadding() est chargée d'appliquer un remplissage vertical de 8 pixels au bas du widget lorsqu'elle est configurée pour afficher son en-tête. Cette méthode est appelée lorsque la page du tableau de bord est activée, c'est-à-dire lorsqu'elle devient la page affichée dans l'interface utilisateur.

Implémentation par défaut :

hasPadding() {
    renvoie this.getViewMode() !== ZBX_WIDGET_VIEW_MODE_HIDDEN_HEADER;
}

Pour certains widgets, il est nécessaire d'utiliser tout l'espace disponible pour configurer, par exemple, une couleur d'arrière-plan personnalisée. Ce qui suit est un exemple d'implémentation de la méthode hasPadding() utilisée dans le widget Zabbix-native Valeur de l'élément.

hasPadding() {
    renvoie faux ;
}