Presentació

La presentació del giny forma part del mòdul del giny que rep les dades segons la configuració i les mostra al tauler en un contenidor. El contenidor de presentació de ginys es pot col·locar i canviar la mida.

La vista del giny consta de dues parts opcionals:

• Acció
• Vista

Accions de giny

La majoria de les accions del giny empren i/o amplien la classe de controlador predeterminada CControllerDashboardWidgetView. Aquesta classe conté mètodes per a operacions amb ginys en el mode de visualització.

El fitxer font de la classe s'ha de posar al directori actions i s'ha d'especificar com a classe d'acció al manifest.json a la secció actions/widget.{id}.view/class.

Per exemple, s'implementa així l'ampliació de la classe per defecte al giny natiu de Zabbix Informació del sistema:

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

Vista de giny

La vista de presentació del giny es construeix amb la classe CWidgetView.

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

El fitxer de visualització del giny s'ha d'ubicar al directori vistes. Si el fitxer té un nom predeterminat widget.view.php, no cal registrar-lo al manifest.json. Si el fitxer té un nom diferent, especifiqueu-lo a actions/widget.{id}.view/view secció de manifest.json.

JavaScript

La classe JavaScript s'encarrega de determinar el comportament del giny, com ara actualitzar les dades del giny, canviar la mida del giny, mostrar elements del giny, etc.

Totes les operacions de JavaScript empren i/o amplien la classe bàsica de JavaScript de tots els ginys del tauler - CWidget. La classe CWidget conté un conjunt de mètodes amb la implementació predeterminada per al comportament del giny. Depenent de la complexitat del giny, aquests mètodes es poden utilitzar tal qual o ampliar.

La classe CWidget conté els mètodes següents:

• Mètodes que defineixen el cicle de vida del giny: onInitialize(), onStart(), onActivate(), onDeactivate(), onDestroy(), onEdit().
• Mètodes que gestionen l'actualització i la visualització de dades del giny: promiseUpdate(), getUpdateRequestData(), processUpdateResponse(response), processUpdateErrorResponse(error), setContents(response).
• Mètodes que modifiquen l'aparença del giny: onResize(), hasPadding().

La classe JavaScript s'ha d'ubicar al directori assets/js i s'ha d'especificar al paràmetre assets (assets/js) al dossier manifest.json.

Mètodes de cicle de vida

Els mètodes de cicle de vida del giny són cridats pel tauler de control i en diferents etapes del cicle de vida del giny durant la seva existència dins del tauler.

El mètode onInitialize() defineix l'estat inicial i/o els valors del giny, sense fer cap HTML ni manipulació de dades. Aquest mètode es crida quan es crea un giny, normalment afegint-lo a una pàgina del tauler o carregant la pàgina del tauler.

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;
       }

El mètode onStart() defineix l'estructura HTML del giny, sense fer cap manipulació de dades. Aquest mètode es crida abans de la primera activació de la pàgina del tauler, és a dir, abans que el tauler i els seus ginys es mostrin completament a l'usuari.

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`
               );
           }
       }

El mètode () fa que el giny sigui actiu i interactiu activant les escoltes d'esdeveniments personalitzats (per respondre a les accions de l'usuari) i iniciar el cicle d'actualització del giny (per mantindre el seu contingut actualitzat). Aquest mètode es crida quan s'activa la pàgina del tauler, és a dir, quan es mostra completament a la interfície d'usuari.

Tingueu en compte que abans que es cridi el mètode (), el giny es troba en estat inactiu (WIDGET_STATE_INACTIVE). Després de la crida correcta, el giny passa a estat actiu (WIDGET_STATE_ACTIVE). En estat actiu, el giny respon, escolta els esdeveniments, actualitza el seu contingut periòdicament i pot interactuar amb altres ginys.

Exemple:

onActivate() {
            this._startClock();
       
            this._resize_observer = new ResizeObserver(this._events.resize);
            this._resize_observer.observe(this._target);
       }

El mètode onDeactivate() atura qualsevol activitat i interactivitat del giny desactivant les escoltes d'esdeveniments personalitzats i aturant el cicle d'actualització del giny. Aquest mètode es crida quan es desactiva la pàgina del tauler de control, és a dir, es desactiva o s'esborra, o quan s'esborra el giny de la pàgina del tauler.

Tingueu en compte que abans que es cridi el mètode _doDeactivate(), el giny es troba en l'estat actiu (WIDGET_STATE_ACTIVE). Després de la invocació correcta, el giny passa a l'estat inactiu (WIDGET_STATE_INACTIVE).

Exemple:

onDeactivate() {
           this._stopClock();
           this._resize_observer.disconnect();
       }

El mètode onDestroy() fa tasques de neteja abans que el giny s'esborri del tauler, que pot incloure el tancament d'una connexió de base de dades que es va establir durant la inicialització del giny, netejar dades temporals per alliberar memòria del sistema i evitar fuites de recursos, anul·lar el registre dels oients d'esdeveniments relacionats amb el canvi de mida dels esdeveniments o els clics de botons per evitar la gestió d'esdeveniments innecessaris i les fuites de memòria, etc. Aquest mètode es crida quan s'esborra el giny o la pàgina del tauler que el conté.

Tingueu en compte que abans que s'invoqui el mètode onDestroy(), un giny en estat actiu (WIDGET_STATE_ACTIVE) sempre es desactiva amb la invocació del mètode 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);
           }
       }

El mètode onEdit() defineix l'aparença i el comportament del giny quan el tauler de control passa al mode d'edició. Aquest mètode s'invoca quan el tauler de control passa al mode d'edició, normalment quan un usuari interacciona amb el botó Editar del giny o el botó Editar el tauler del tauler.

Exemple:

onEdit() {
               this._deactivateGraph();
       }

Mètodes d'actualització

Els mètodes del procés d'actualització del giny són els responsables de recuperar les dades actualitzades del servidor Zabbix o qualsevol altra font de dades i mostrar-les al giny.

El mètode promiseUpdate() inicia el procés d'actualització de dades recuperant dades, normalment mitjançant peticions web o crides a l'API. Aquest mètode es crida quan es mostra una pàgina del tauler i periòdicament després, fins que la pàgina del tauler es canvia a una altra pàgina del tauler.

El següent és un exemple de la implementació predeterminada del mètode promiseUpdate() emprat per la majoria dels ginys nadius de Zabbix. A la implementació per defecte, el mètode promiseUpdate() segueix un patró general per recuperar dades del servidor. Crea un nou objecte Curl amb l'URL adequat i els paràmetres de sol·licitud, envia una petició POST mitjançant el mètode fetch() amb l'objecte de dades construït pel mètode getUpdateRequestData(), i processa la resposta (o una resposta d'error) amb processUpdateResponse(response) o processUpdateErrorResponse(error). Aquesta implementació és adequada per a la majoria dels ginys, ja que normalment recuperen dades en format JSON i les gestionen de manera coherent.

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

El mètode getUpdateRequestData() prepara les dades de petició del servidor per actualitzar el giny recopilant diverses propietats i els seus valors corresponents (identificadors de giny, paràmetres de filtre, intervals de temps, etc.) a partir de l'estat i la configuració del giny, i construir un objecte de dades que representi la informació necessària per ser enviada al servidor en la petició d'actualització. Aquest mètode només s'invoca com a part del mètode predeterminat promiseUpdate(), és a dir, durant el procés d'actualització del giny.

Implementació per defecte:

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
           };
       }

El mètode processUpdateResponse(response) gestiona la resposta rebuda del servidor després de la petició d'actualització i, si el procés d'actualització ha tingut èxit i sense errors, esborra les dades del giny i mostra continguts nous amb el mètode setContents(). Aquest mètode només s'invoca com a part del mètode predeterminat promiseUpdate(), és a dir, durant el procés d'actualització del giny.

Implementació per defecte:

processUpdateResponse(response) {
           this._setHeaderName(response.name);
       
           this._updateMessages(response.messages);
           this._updateInfo(response.info);
           this._updateDebug(response.debug);
       
           this.setContents(response);
       }

El mètode processUpdateErrorResponse(error) gestiona la resposta rebuda del servidor després de la petició d'actualització si la resposta és un error i mostra el missatge d'error. Aquest mètode només s'invoca com a part del mètode predeterminat promiseUpdate(), és a dir, durant el procés d'actualització del giny.

Implementació per defecte:

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

El mètode setContents(response) mostra el contingut del giny si el procés d'actualització del giny ha estat satisfactori i sense errors, que pot incloure la manipulació d'elements DOM, l'actualització de components de la interfície d'usuari, l'aplicació d'estils o format, etc. Aquest mètode només es crida com a part del mètode predeterminat processUpdateResponse(response), és a dir, durant el procés de gestió de la resposta rebuda del servidor després de la petició d'actualització.

Implementació per defecte:

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

Mètodes de modificació de la presentació

Els mètodes de modificació de la presentació del giny són els responsables de modificar l'aparença del giny.

El mètode onResize() és responsable d'ajustar els elements visuals del giny per adaptar-se a la nova mida del giny, que pot incloure reordenar elements, ajustar les dimensions dels elements, truncar el text, implementar càrrega lenta per millorar la capacitat de resposta durant el canvi de mida, etc. Aquest mètode es crida quan es canvia la mida del giny, per exemple, quan l'usuari canvia la mida manualment del giny o quan es canvia la mida de la finestra del navegador.

Exemple:

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

El mètode hasPadding() és responsable d'aplicar un farcit vertical de 8 píxels a la part inferior del giny quan és configurat per mostrar la seva capçalera. Aquest mètode es crida quan s'activa la pàgina del tauler, és a dir, quan es converteix en la pàgina que es mostra a la interfície d'usuari.

Implementació per defecte:

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

Per a alguns ginys, és necessari emprar tot l'espai de ginys disponible per configurar, per exemple, un color de fons personalitzat. El següent és un exemple de la implementació del mètode hasPadding() emprat al giny Item_value nadiu de Zabbix.

hasPadding() {
           return false;
       }