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.
The _promiseUpdate() method initiates the data update process by retrieving data, typically using web requests or API calls. This method is invoked when a dashboard page is displayed and periodically after, until the dashboard page is switched to another dashboard page.
The following is an example of the default implementation of the _promiseUpdate() method used by most Zabbix-native widgets. In the default implementation, the _promiseUpdate() method follows a general pattern for retrieving data from the server. It creates a new Curl object with the appropriate URL and request parameters, sends a POST request using the fetch() method with the data object constructed by the _getUpdateRequestData() method, and processes the response (or an error response) with the _processUpdateResponse(response) or _processUpdateErrorResponse(error) accordingly. This implementation is suitable for most widgets as they typically retrieve data in a JSON format and handle it in a consistent manner.
_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
};
}The _processUpdateResponse(response) method handles the response received from the server after the update request, and, if the update process has been successful and without errors, clears widget data and displays new contents with the _setContents() method. This method is invoked only as part of the default _promiseUpdate() method, that is, during the widget update process.
Default implementation:
_processUpdateResponse(response) {
this._setContents({
name: response.name,
body: response.body,
messages: response.messages,
info: response.info,
debug: response.debug
});
}The _processUpdateErrorResponse(error) method handles the response received from the server after the update request if the response is an error, and displays the error message/-s. This method is invoked only as part of the default _promiseUpdate() method, that is, during the widget update process.
Default implementation:
_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();
}The _setContents() method displays widget contents if the widget update process has been successful and without errors, which can include manipulating DOM elements, updating UI components, applying styles or formatting, etc. This method is invoked only as part of the default _processUpdateResponse(response) method, that is, during the process of handling the response received from the server after the update request.
Default implementation:
_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.
The resize() method is responsible for adjusting widget's visual elements to accommodate the new widget size, which can include rearranging elements, adjusting element dimensions, text truncation, implementing lazy loading to improve responsiveness during resizing, etc. This method is invoked when the widget is resized, for example, when the user manually resizes the widget or when the browser window is resized.
Example:
The _hasPadding() method is responsible for applying an 8px vertical padding at the bottom of the widget when it is configured to show its header. This method is invoked when the dashboard page is activated, that is, when it becomes the displayed page in the user interface.
Default implementation:
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.