Documentation
Table of Contents
Presentatie
Deze pagina beschrijft de componenten die kunnen worden gebruikt om een widgetpresentatieweergave te maken. De presentatieweergave van de widget is het deel van de widget dat de gegevens volgens zijn configuratie ontvangt en in een container op het dashboard weergeeft.
De presentatieweergave bestaat uit drie delen:
Widgetactie
De widgetactieklasse (WidgetView) bevat methoden voor bewerkingen met widgets in de presentatieweergavemodus. De meerderheid van de widgetacties gebruikt en/of breidt de standaard controllerklasse CControllerDashboardWidgetView uit.
De widgetactieklasse moet zich bevinden in de actions map en worden gespecificeerd in de actions parameter (actions/widget.{id}.view/class) in het manifest.json bestand.
Voorbeeld van actions/WidgetView.php (geïmplementeerd in de Zabbix-native System information widget)
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()
]
]));
}
}Widgetweergave
De widgetweergaveklasse (CWidgetView) is verantwoordelijk voor het opbouwen van de weergave van de widget.
De widgetweergaveklasse moet zich bevinden in de views map. Als het bestand met de widgetweergaveklasse een andere naam heeft dan de standaard (widget.view.php), moet dit worden gespecificeerd in het manifest.json bestand bij de actions parameter (actions/widget.{id}.view/view).
views/widget.view.php voorbeeld
<?php
/**
* Mijn aangepaste widgetweergave.
*
* @var CView $this
* @var array $data
*/
(new CWidgetView($data))
->addItem(
new CTag('h1', true, $data['name'])
)
->show();JavaScript
De JavaScript-klasse is verantwoordelijk voor het bepalen van het gedrag van de widget, zoals het bijwerken van widgetgegevens, het wijzigen van de grootte van de widget, het weergeven van widget-elementen, enzovoort.
Alle JavaScript-operaties gebruiken en/of breiden de basis JavaScript-klasse uit van alle dashboardwidgets - CWidget. De CWidget-klasse bevat een reeks methoden met de standaardimplementatie voor het gedrag van de widget. Afhankelijk van de complexiteit van de widget kunnen deze methoden zoals ze zijn worden gebruikt of worden uitgebreid.
De CWidget-klasse bevat de volgende methoden:
- Methoden die de levenscyclus van de widget definiëren: _init(), _registerEvents(), _doActivate(), _doDeactivate(), _doDestroy(), setEditMode().
- Methoden die het bijwerken en weergeven van widgetgegevens behandelen: _promiseUpdate(), _getUpdateRequestData(), _processUpdateResponse(response), _processUpdateErrorResponse(error), _setContents().
- Methoden die de weergave van de widget wijzigen: resize(), _hasPadding().
De JavaScript-klasse moet zich bevinden in de assets/js map en moet worden gespecificeerd in de assets (assets/js) parameter in het manifest.json bestand.
Levenscyclusmethoden
De levenscyclusmethoden van de widget worden aangeroepen door het dashboard, en in verschillende stadia van de levenscyclus van de widget gedurende zijn bestaan binnen het dashboard.
De methode _init() definieert de initiële status en/of waarden van de widget, zonder enige HTML- of datamanipulatie uit te voeren. Deze methode wordt aangeroepen wanneer een widget wordt gemaakt (een widget-object wordt geïnstantieerd), doorgaans door de widget aan een dashboardpagina toe te voegen of de dashboardpagina te laden.
Voorbeeld:
_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;
}De methode _registerEvents() definieert de HTML-structuur van de widget, zonder enige datamanipulatie uit te voeren. Deze methode wordt aangeroepen vóór de eerste activatie van de dashboardpagina, dat wil zeggen voordat het dashboard en de bijbehorende widgets volledig aan de gebruiker worden weergegeven.
Voorbeeld:
_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`
);
}
}De methode _doActivate() maakt de widget actief en interactief door aangepaste gebeurtenisluisteraars in te schakelen (om te reageren op gebruikersacties) en de widget-updatecyclus te starten (om de inhoud up-to-date te houden). Deze methode wordt aangeroepen wanneer de dashboardpagina wordt geactiveerd, dat wil zeggen wanneer deze volledig wordt weergegeven in de gebruikersinterface.
Merk op dat voordat de methode _doActivate() wordt aangeroepen, de widget zich in de inactieve toestand bevindt (WIDGET_STATE_INACTIVE). Na een succesvolle oproep gaat de widget over naar de actieve toestand (WIDGET_STATE_ACTIVE). In de actieve toestand reageert de widget, luistert naar gebeurtenissen, werkt periodiek de inhoud bij en kan communiceren met andere widgets.
Voorbeeld:
De methode _doDeactivate() stopt alle activiteit en interactiviteit van de widget door aangepaste gebeurtenisluisteraars uit te schakelen en de widget-updatecyclus te stoppen. Deze methode wordt aangeroepen wanneer de dashboardpagina wordt gedeactiveerd, dat wil zeggen wanneer deze wordt gewijzigd, verwijderd of wanneer de widget uit de dashboardpagina wordt verwijderd.
Merk op dat voordat de methode _doDeactivate() wordt aangeroepen, de widget zich in de actieve toestand bevindt (WIDGET_STATE_ACTIVE). Na een succesvolle oproep gaat de widget over naar de inactieve toestand (WIDGET_STATE_INACTIVE).
Voorbeeld:
De methode _doDestroy() voert opruimtaken uit voordat de widget uit het dashboard wordt verwijderd, dit kan het afsluiten van een databaseverbinding omvatten die tijdens de initialisatie van de widget is opgezet, het opruimen van tijdelijke gegevens om systeemgeheugen vrij te maken en resourcelekken te voorkomen, het afmelden van gebeurtenisluisteraars die verband houden met formaatwijzigingen of knopklikken om onnodige gebeurtenisverwerking en geheugenlekken te voorkomen, enzovoort. Deze methode wordt aangeroepen wanneer de widget of de dashboardpagina die de widget bevat wordt verwijderd.
Merk op dat voordat de methode _doDestroy() wordt aangeroepen, een widget in de actieve toestand (WIDGET_STATE_ACTIVE) altijd wordt gedeactiveerd met de aanroeping van de methode _doDeactivate().
Voorbeeld:
_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);
}
}De setEditMode()-methode definieert het uiterlijk en gedrag van de widget wanneer het dashboard overgaat naar de bewerkingsmodus. Deze methode wordt aangeroepen wanneer het dashboard overgaat naar de bewerkingsmodus, meestal wanneer een gebruiker interactie heeft met de knop Bewerken van de widget of de knop Dashboard bewerken van het dashboard.
Voorbeeld:
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();
}
}Procesmethoden bijwerken
De methoden voor het updateproces van de widget zijn verantwoordelijk voor het ophalen van bijgewerkte gegevens van de Zabbix-server of een andere gegevensbron en het weergeven ervan in het widget.
De _promiseUpdate()-methode start het proces voor het bijwerken van gegevens door gegevens op te halen, meestal via webverzoeken of API-aanroepen. Deze methode wordt aangeroepen wanneer een dashboardpagina wordt weergegeven en periodiek daarna, totdat de dashboardpagina wordt overgeschakeld naar een andere dashboardpagina.
Het volgende is een voorbeeld van de standaardimplementatie van de _promiseUpdate()-methode die wordt gebruikt door de meeste Zabbix-native widgets. In de standaardimplementatie volgt de _promiseUpdate()-methode een algemeen patroon voor het ophalen van gegevens van de server. Er wordt een nieuwe Curl-object gemaakt met de juiste URL en verzoekparameters, vervolgens wordt een POST-verzoek verzonden met behulp van de fetch()-methode met het gegevensobject dat is geconstrueerd door de _getUpdateRequestData()-methode, en de respons (of een foutrespons) wordt verwerkt met respectievelijk de _processUpdateResponse(response)- of _processUpdateErrorResponse(error)-methode. Deze implementatie is geschikt voor de meeste widgets, omdat ze meestal gegevens ophalen in een JSON-indeling en deze op een consistente manier verwerken.
_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);
});
}De _getUpdateRequestData()-methode bereidt de verzoekgegevens voor de server voor om de widget bij te werken door verschillende eigenschappen en hun overeenkomstige waarden (widget-identificatoren, filterinstellingen, tijdsbereiken, enz.) te verzamelen uit de status en configuratie van de widget, en construeert een gegevensobject dat de noodzakelijke informatie vertegenwoordigt die naar de server moet worden verzonden in het updateverzoek. Deze methode wordt alleen aangeroepen als onderdeel van de standaard [_promiseUpdate()] methode, dat wil zeggen tijdens het bijwerkproces van de widget.
Standaardimplementatie:
_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
};
}De _processUpdateResponse(response)-methode verwerkt het antwoord dat van de server is ontvangen na het updateverzoek, en, als het updateproces succesvol en zonder fouten is verlopen, wist het widgetgegevens en toont nieuwe inhoud met de _setContents()-methode. Deze methode wordt alleen aangeroepen als onderdeel van de standaard _promiseUpdate()-methode, dat wil zeggen tijdens het bijwerkproces van de widget.
Standaardimplementatie:
_processUpdateResponse(response) {
this._setContents({
name: response.name,
body: response.body,
messages: response.messages,
info: response.info,
debug: response.debug
});
}De _processUpdateErrorResponse(error)-methode verwerkt het antwoord dat van de server is ontvangen na het updateverzoek als het antwoord een fout is, en toont de foutmelding/-en. Deze methode wordt alleen aangeroepen als onderdeel van de standaard _promiseUpdate()-methode, dat wil zeggen tijdens het bijwerkproces van de widget.
Standaardimplementatie:
_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();
}De _setContents()-methode toont de inhoud van de widget als het bijwerkproces van de widget succesvol en zonder fouten is verlopen, wat onder meer het manipuleren van DOM-elementen, het bijwerken van UI-componenten, het toepassen van stijlen of opmaak, enzovoort kan omvatten. Deze methode wordt alleen aangeroepen als onderdeel van de standaard _processUpdateResponse(response)-methode, dat wil zeggen tijdens het verwerken van het antwoord dat van de server is ontvangen na het updateverzoek.
Standaardimplementatie:
_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);
}
}Methoden voor het wijzigen van presentaties
De methoden voor het wijzigen van de widgetpresentatie zijn verantwoordelijk voor het wijzigen van het uiterlijk van de widget.
De resize()-methode is verantwoordelijk voor het aanpassen van de visuele elementen van de widget om de nieuwe grootte van de widget aan te passen, wat het herschikken van elementen, het aanpassen van de afmetingen van elementen, tekstinkorting, het implementeren van lazy loading om de responsiviteit tijdens het formaataanpassen te verbeteren, enzovoort kan omvatten. Deze methode wordt aangeroepen wanneer de widget wordt aangepast in grootte, bijvoorbeeld wanneer de gebruiker handmatig de grootte van de widget aanpast of wanneer het browservenster wordt aangepast.
Voorbeeld:
De methode _hasPadding() is verantwoordelijk voor het toepassen van een verticale vulling van 8px aan de onderkant van de widget wanneer deze is geconfigureerd om zijn koptekst weer te geven. Deze methode wordt aangeroepen wanneer de dashboardpagina wordt geactiveerd, dat wil zeggen wanneer deze de weergegeven pagina wordt in de gebruikersinterface.
Standaardimplementatie:
Voor sommige widgets is het noodzakelijk om alle beschikbare widgetruimte te gebruiken om bijvoorbeeld een aangepaste achtergrondkleur te configureren. Het volgende is een voorbeeld van de implementatie van de methode _hasPadding() die wordt gebruikt in de Zabbix-native Itemwaarde widget.