Documentation
Table of Contents
Présentation
Cette page décrit les composants pouvant ê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 selon 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
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 _init() 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:
_init() {
super._init();
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 _registerEvents() 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:
_registerEvents() {
super._registerEvents();
this._events.resize = () => {
const padding = 25;
const header_height = this._view_mode == ZBX_WIDGET_VIEW_MODE_HIDDEN_HEADER
? 0
: this._content_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:
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:
La méthode _doDestroy() effectue des tâches de nettoyage avant que le widget ne soit supprimé du tableau de bord, qui peut inclure la fermeture d'une connexion à la base de données établie lors de l'initialisation du widget, nettoyer les données temporaires pour libérer la mémoire système et éviter les fuites de ressources, désenregistrer les écouteurs d'événements liés au redimensionnement des événements ou aux clics sur les boutons pour éviter la gestion inutile des événements et les fuites de mémoire, etc. Cette méthode est invoquée lorsque le widget ou la page du tableau de bord qui le contient est supprimé.
Notez qu'avant l'invocation de la méthode _doDestroy(), un widget dans un état actif (WIDGET_STATE_ACTIVE) est toujours désactivé avec l'invocation de la méthode _doDeactivate().
Exemple:
_doDestroy() {
super._doDestroy();
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 setEditMode() définit l'apparence et le comportement du widget lorsque le tableau de bord passe en mode édition. Cette méthode est invoquée lorsque le tableau de bord passe en mode édition, généralement lorsqu'un utilisateur interagit avec le bouton Edition du widget ou le bouton Editer le tableau de bord du tableau de bord.
Example:
setEditMode() {
if (this._has_contents) {
this._deactivateContentsEvents();
this._removeTree();
}
super.setEditMode();
if (this._has_contents && this._state === WIDGET_STATE_ACTIVE) {
this._makeTree();
this._activateTree();
this._activateContentsEvents();
}
}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() lance 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 invoquée lorsqu'une page de tableau de bord est affichée et périodiquement par la suite, jusqu'à ce que la page du 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. Il crée un nouvel objet Curl avec l'URL et les paramètres de requête appropriés,envoie une requête POST en utilisant 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);
});
}The _getUpdateRequestData() method prepares the server request data for updating the widget by gathering various properties and their corresponding values (widget identifiers, filter settings, time ranges, etc.) from the widget's state and configuration, and constructing a data object that represents the necessary information to be sent to the server in the update request. This method is invoked only as part of the default [_promiseUpdate()] method, that is, during the widget update process.
Default implementation:
_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._content_size
};
}La méthode _processUpdateResponse(response) gère la réponse reçue du serveur après la demande de mise à jour, et si le processus de mise à jour est un succès et sans erreurs, efface les données du widget et affiche le nouveau contenu avec la méthode _setContents(). 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:
_processUpdateResponse(response) {
this._setContents({
name: response.name,
body: response.body,
messages: response.messages,
info: response.info,
debug: response.debug
});
}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(s) message(s) 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._setErrorContents({error});
}
_setErrorContents({error}) {
const message_box = makeMessageBox('bad', error.messages, error.title)[0];
this._content_body.innerHTML = '';
this._content_body.appendChild(message_box);
this._removeInfoButtons();
}La méthode _setContents() affiche le contenu du widget si le processus de mise à jour du widget est un succès et sans erreur, qui peut inclure la manipulation d'éléments DOM, la mise à jour des composants de l'interface utilisateur, l'application de styles ou de formatage, etc. Cette méthode est invoquée uniquement dans le cadre de la méthode _processUpdateResponse(response) par défaut, c'est-à-dire pendant le processus de traitement de la réponse reçue du serveur après la demande de mise à jour.
Implémentation par défaut:
_setContents({name, body, messages, info, debug}) {
this._setHeaderName(name);
this._content_body.innerHTML = '';
if (messages !== undefined) {
const message_box = makeMessageBox('bad', messages)[0];
this._content_body.appendChild(message_box);
}
if (body !== undefined) {
this._content_body.insertAdjacentHTML('beforeend', body);
}
if (debug !== undefined) {
this._content_body.insertAdjacentHTML('beforeend', debug);
}
this._removeInfoButtons();
if (info !== undefined) {
this._addInfoButtons(info);
}
}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 resize() est chargée d'ajuster les éléments visuels du widget pour s'adapter à la nouvelle taille du widget, qui peut inclure la réorganisation des éléments, l'ajustement des dimensions des éléments, la troncature du texte, la mise en œuvre d'un chargement paresseux pour améliorer la réactivité lors du redimensionnement, etc. Cette méthode est invoqué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:
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 invoqué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:
For some widgets it is necessary to use all of the available widget space to configure, for example, a custom background color. The following is an example of the implementation of the _hasPadding() method used in the Zabbix-native Item value widget.