Презентација

Ова страница описује компоненте које се могу користити за креирање приказа презентације виџета. Приказ презентације виџета је део виџета који прима податке према својој configuration и приказује их на контролној табли у контејнеру.

Приказ презентације се састоји од три дела:

• Widget action
• Widget view
• JavaScript

Акција виџета

Класа радње виџета (WidgetView) садржи методе за операције са виџетима у режиму приказа презентације. Већина радњи виџета користи и/или проширује подразумевану класу контролера CControllerDashboardWidgetView.

Класа радње виџета треба да се налази у директоријуму actions и наведе у параметру actions (actions/widget.{id}.view/class) у датотеци manifest.json.

actions/WidgetView.php пример (примењен у Zabbix-native Информације о систему 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()
           ]
           ]));
           }
       }

Приказ виџета

Класа приказа виџета (CWidgetView) је одговорна за изградњу приказа презентације виџета.

Класа приказа виџета треба да се налази у директоријуму views. Ако датотека која садржи класу приказа виџета има другачије име од подразумеваног (widget.view.php), онда се мора навести у датотеци manifest.json actions параметар (actions/widget.{id}.view/view).

пример views/widget.view.php

<?php
       
       /**
        * Мој прилагођени приказ виџета.
        *
        * @var CView $this
        * @var array $data
        */
       
       (new CWidgetView($data))
           ->addItem(
               new CTag('h1', true, $data['name'])
           )
           ->show();

JavaScript

JavaScript класа је одговорна за одређивање понашања виџета, као што је ажурирање података виџета, промена величине виџета, приказивање елемената виџета итд.

Све JavaScript операције користе и/или проширују основну JavaScript класу свих виџета контролне табле - CWidget. Класа CWidget садржи скуп метода са подразумеваном имплементацијом за понашање виџета. У зависности од сложености виџета, ове методе се могу користити непромењене или проширене.

Класа CWidget садржи следеће методе:

• Методе које дефинишу животни циклус виџета: onInitialize(), onStart(), onActivate(), onDeactivate(), onDestroy(), onEdit().
• Методе које рукују ажурирањем и приказивањем података виџета: promiseUpdate(), getUpdateRequestData(), processUpdateResponse(response), processUpdateErrorResponse(error), setContents(response).
• Методе које мењају изглед виџета: onResize(), hasPadding().

JavaScript класа би требала да се налази у директоријуму assets/js и наведена у параметру assets (assets/js) у manifest.json датотеци.

Методе животног циклуса

Методе животног циклуса виџета се позивају од стране контролне табле, и то у различитим фазама животног циклуса виџета током његовог унутар контролне табле.

Метода onInitialize() дефинише иницијално стање и/или вредности виџета, без извршавања било какве манипулације HTML-ом или подацима. Овај метод се позива када се креира виџет (инстанцира се објекат виџета), обично додавањем виџета на страницу контролне табле или учитавањем странице контролне табле.

Пример:

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

Метода onStart() дефинише HTML структуру виџета, без извршавања било какве манипулације подацима. Овај метод се позива пре прве активације странице контролне табле, односно пре него што се контролна табла и њени виџети у потпуности прикажу кориснику.

Пример:

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

Метода onActivate() чини виџет активним и интерактивним омогућавањем прилагођених слушалаца догађаја (за реаговање на акције корисника) и покретањем циклуса ажурирања виџета (да би његов садржај био актуелан). Овај метод се позива када се активира страница контролне табле, односно када постане у потпуности приказана у корисничком интерфејсу.

Имајте на уму да пре него што се позове метода onActivate(), виџет је у неактивном стању (WIDGET_STATE_INACTIVE). Након успешног позива, виџет прелази у активно стање (WIDGET_STATE_ACTIVE). У активном стању, виџет реагује, слуша догађаје, периодично ажурира свој садржај и може да комуницира са другим виџетима.

Пример:

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

Метода onDeactivate() зауставља сваку активност и интерактивност виџета тако што деактивира прилагођене слушаоце догађаја и зауставља циклус ажурирања виџета. Овај метод се позива када је страница контролне табле деактивирана, односно искључена или обрисана, или када се виџет избрише са странице контролне табле.

Имајте на уму да пре него што се позове метода onDeactivate(), виџет је у активном стању (WIDGET_STATE_ACTIVE). Након успешног позива, виџет прелази у неактивно стање (WIDGET_STATE_INACTIVE).

Пример:

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

Метод onDestroy() обавља задатке чишћења пре него што се виџет избрише са контролне табле, што може укључивати затварање везе са базом података која је успостављена током иницијализације виџета, чишћење привремених података да би се ослободила системска меморија и избегло цурење ресурса, поништавање регистрације слушалаца догађаја који се односе на догађаје промене величине или кликове на дугмад како би се спречило непотребно руковање догађајима и цурење меморије итд. Овај метод се позива када се избрише виџет или страница на контролној табли која га садржи.

Имајте на уму да се пре него што се позове метода onDestroy(), виџет у активном стању (WIDGET_STATE_ACTIVE) увек деактивира са позивањем методе onDeactivate().

Пример:

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

Mетода onEdit() дефинише изглед и понашање виџета када контролна табла пређе у режим за уређивање. Овај метод се позива када контролна табла пређе у режим за уређивање, обично када корисник ступи у интеракцију са виџетовим дугметом Измени или дугметом Измени контролну таблу на контролној табли.

Пример:

onEdit() {
           this._deactivateGraph();
       }

Методе процеса ажурирања

Методе процеса ажурирања виџета су одговорне за преузимање ажурираних података са Zabbix сервера или било ког другог извора података и њихово приказивање у виџету.

Mетода promiseUpdate() покреће процес ажурирања података преузимањем података, обично користећи веб захтеве или API позиве. Овај метод се позива када се прикаже страница контролне табле и периодично након тога, све док се страница контролне табле не пребаци на другу страницу контролне табле.

Следи пример подразумеване имплементације promiseUpdate() методе коју користи већина Zabbix-native виџета. У подразумеваној имплементацији, метода promiseUpdate() прати општи образац за преузимање података са сервера. Прави нови објекат Curl са одговарајућом URL адресом и параметрима захтева, шаље POST захтев користећи метод fetch() са објектом података који је конструисао метод getUpdateRequestData(), и обрађује одговор (или одговор на грешку) са processUpdateResponse(response) или processUpdateErrorResponse(error) у складу са тим. Ова имплементација је погодна за већину виџета јер они обично преузимају податке у JSON формату и рукују њима на доследан начин.

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

Метод getUpdateRequestData() припрема податке захтева сервера за ажурирање виџета прикупљањем различитих својстава и њихових одговарајућих вредности (идентификатора виџета, подешавања филтера, временских опсега, итд.) из стања и конфигурације виџета, и конструисање објекта података који представља неопходне информације које треба послати серверу у захтеву за ажурирање. Овај метод се позива само као део подразумеване методе promiseUpdate(), односно током процеса ажурирања виџета.

Подразумевана примена:

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

Метод processUpdateResponse(response) обрађује одговор примљен од сервера након захтева за ажурирање, и, ако је процес ажурирања био успешан и без грешака, брише податке виџета и приказује нови садржај методом setContents(). Овај метод се позива само као део подразумеване методе promiseUpdate(), односно током процеса ажурирања виџета.

Подразумевана примена:

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

Метода processUpdateErrorResponse(error) обрађује одговор примљен од сервера након захтева за ажурирање ако је одговор грешка и приказује поруку/поруке о грешци. Овај метод се позива само као део подразумеване методе promiseUpdate(), односно током процеса ажурирања виџета.

Подразумевана примена:

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

Методa setContents(response) приказује садржај виџета ако је процес ажурирања виџета био успешан и без грешака, што може укључивати манипулисање DOM елементима, ажурирање компоненти корисничког интерфејса, примену стилова или форматирања итд. Овај метод се позива само као део подразумеване методе processUpdateResponse(response), односно током процеса руковања одговором примљеним од сервера након захтева за ажурирање.

Подразумевана примена:

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

Методе модификације презентације

Методе модификације презентације виџета су одговорне за модификацију изгледа виџета.

Метод onResize() је одговоран за прилагођавање визуелних елемената виџета да би се прилагодили новој величини виџета, што може укључивати преуређивање елемената, прилагођавање димензија елемента, скраћивање текста, имплементацију одложеног учитавања ради побољшања одзива током промене величине итд. Овај метод се позива када се промени величина виџета, на пример, када корисник ручно промени величину виџета или када се промени величина прозора претраживача.

Пример:

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

Метода hasPadding() је одговорна за примену вертикалне допуне од 8 пиксела на дну виџета када је конфигурисан да show its header. Овај метод се позива када се активира страница контролне табле, односно када постане приказана страница у корисничком интерфејсу.

Подразумевана примена:

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

За неке виџете потребно је користити сав расположиви простор за виџете да бисте конфигурисали, на пример, прилагођену боју позадине. Следи пример имплементације методе hasPadding() која се користи у Zabbix-native Item value виџету.

hasPadding() {
           return false;
       }