Utwórz widżet (samouczek)

To jest samouczek pokazujący krok po kroku, jak utworzyć prosty widget pulpitu nawigacyjnego. Możesz pobrać wszystkie pliki tego widgetu w postaci archiwum ZIP: lesson_gauge_chart.zip.

Co zbudujesz

Podczas tego samouczka najpierw utworzysz podstawowy widget „Hello, world!”, a następnie przekształcisz go w bardziej zaawansowany widget, który wyświetla wartość pozycji jako wykres wskaźnikowy. Tak będzie wyglądać gotowy widget:

Część I - "Witaj, świecie!"

W tej sekcji dowiesz się, jak utworzyć minimalną wymaganą liczbę elementów widgetu i dodać nowy widget do frontendu Zabbix.

Dodawanie pustego widżetu do frontend Zabbix

1. Utwórz katalog lesson_gauge_chart w katalogu modules instalacji frontend Zabbix (na przykład zabbix/ui/modules).

2. Utwórz plik manifest.json z podstawowymi metadanymi widżetu (zobacz opis obsługiwanych parametrów).

ui/modules/lesson_gauge_chart/manifest.json

{
    "manifest_version": 2.0,
    "id": "lesson_gauge_chart",
    "type": "widget",
    "name": "Gauge chart",
    "namespace": "LessonGaugeChart",
    "version": "1.1",
    "author": "Zabbix"
}

3. W frontend Zabbix przejdź do sekcji Administration > General > Modules i kliknij przycisk Scan directory.

4. Znajdź nowy moduł Gauge chart na liście i kliknij hiperłącze "Disabled", aby zmienić status modułu z "Disabled" na "Enabled" (jeśli moduł nie jest widoczny na liście, zobacz sekcję troubleshooting).

5. Otwórz dashboard, przełącz go w tryb edycji i dodaj nowy widżet. W polu Type wybierz "Gauge chart".

6. W tym momencie konfiguracja widżetu Gauge chart zawiera tylko ogólne pola widżetu Name i Refresh interval. Kliknij Add, aby dodać widżet do dashboardu.

7. Na dashboardzie powinien pojawić się pusty widżet. Kliknij Save changes w prawym górnym rogu, aby zapisać dashboard.

Dodaj widok widgetu

1. Utwórz katalog views w katalogu lesson_gauge_chart.

2. Utwórz plik widget.view.php w katalogu views.

ui/modules/lesson_gauge_chart/views/widget.view.php

<?php

/**
 * Widok widgetu wykresu Gauge.
 *
 * @var CView $this
 * @var array $data
 */

(new CWidgetView($data))
    ->addItem(
        new CTag('h1', true, 'Hello, world!')
    )
    ->show();

3. Odśwież pulpit. Widget Gauge chart wyświetla teraz tekst "Hello, world!".

Część II - Wykres wskaźnikowy

Dodawanie ustawień do widoku konfiguracji i używanie ich w widoku widżetu

W tej sekcji dowiesz się, jak dodać pole konfiguracji widżetu i wyświetlić wprowadzoną wartość w widoku widżetu jako tekst.

Konfiguracja widżetu składa się z formularza (Zabbix\Widgets\CWidgetForm) oraz widoku formularza widżetu (widget.edit.php). Aby dodać pola (Zabbix\Widgets\CWidgetField), musisz utworzyć klasę WidgetForm, która będzie dziedziczyć po Zabbix\Widgets\CWidgetForm.

Formularz zawiera zestaw pól (Zabbix\Widgets\CWidgetField) różnych typów, które służą do walidacji wartości wprowadzonych przez użytkownika. Pole formularza (Zabbix\Widgets\CWidgetField) dla każdego typu elementu wejściowego konwertuje wartość do pojedynczego formatu, aby zapisać ją w bazie danych.

1. Utwórz nowy katalog includes w katalogu lesson_gauge_chart.

2. Utwórz plik WidgetForm.php w katalogu includes.

ui/modules/lesson_gauge_chart/includes/WidgetForm.php

<?php

namespace Modules\LessonGaugeChart\Includes;

use Zabbix\Widgets\CWidgetForm;

class WidgetForm extends CWidgetForm {
}

3. Dodaj pole Description do formularza konfiguracji widżetu. Jest to zwykłe pole tekstowe, w którym użytkownik może wprowadzić dowolny zestaw znaków. Możesz użyć do tego klasy CWidgetFieldTextBox.

ui/modules/lesson_gauge_chart/includes/WidgetForm.php

<?php

namespace Modules\LessonGaugeChart\Includes;

use Zabbix\Widgets\CWidgetForm;

use Zabbix\Widgets\Fields\CWidgetFieldTextBox;

class WidgetForm extends CWidgetForm {

    public function addFields(): self {
        return $this
            ->addField(
               new CWidgetFieldTextBox('description', _('Description'))
            );
   }
}

4. W katalogu views utwórz plik widoku konfiguracji widżetu widget.edit.php i dodaj widok dla nowego pola Description. Dla klasy pola CWidgetFieldTextBox widokiem jest CWidgetFieldTextBoxView.

ui/modules/lesson_gauge_chart/views/widget.edit.php

<?php

/**
 * Gauge chart widget form view.
 *
 * @var CView $this
 * @var array $data
 */

(new CWidgetFormView($data))
    ->addField(
        new CWidgetFieldTextBoxView($data['fields']['description'])
    )
    ->show();

5. Przejdź do dashboardu i kliknij ikonę koła zębatego w widżecie, aby otworzyć formularz konfiguracji widżetu.

6. Formularz konfiguracji widżetu zawiera teraz nowe pole tekstowe Description. Wpisz dowolną wartość, na przykład Gauge chart description.

7. Kliknij Apply w formularzu konfiguracji widżetu. Następnie kliknij Save changes w prawym górnym rogu, aby zapisać dashboard. Zwróć uwagę, że nowy opis nie jest widoczny nigdzie, a widżet nadal wyświetla "Hello, world!".

Aby nowy opis pojawił się w widżecie, wartość pola Description musi zostać pobrana z bazy danych i przekazana do widoku widżetu. W tym celu musisz utworzyć klasę akcji.

8. Utwórz nowy katalog actions w katalogu lesson_gauge_chart.

9. Utwórz plik WidgetView.php w katalogu actions. Klasa akcji WidgetView będzie dziedziczyć po klasie CControllerDashboardWidgetView.

Wartości pól konfiguracji widżetu są przechowywane we właściwości $fields_values klasy akcji.

ui/modules/lesson_gauge_chart/actions/WidgetView.php

<?php

namespace Modules\LessonGaugeChart\Actions;

use CControllerDashboardWidgetView,
    CControllerResponseData;

class WidgetView extends CControllerDashboardWidgetView {

    protected function doAction(): void {
        $this->setResponse(new CControllerResponseData([
            'name' => $this->getInput('name', $this->widget->getName()),
            'description' => $this->fields_values['description'],
            'user' => [
                'debug_mode' => $this->getDebugMode()
            ]
        ]));
    }
}

10. Otwórz manifest.json i zarejestruj WidgetView jako klasę akcji w sekcji actions/widget.lesson_gauge_chart.view.

ui/modules/lesson_gauge_chart/manifest.json

{
    "manifest_version": 2.0,
    "id": "lesson_gauge_chart",
    "type": "widget",
    "name": "Gauge chart",
    "namespace": "LessonGaugeChart",
    "version": "1.0",
    "author": "Zabbix",
    "actions": {
        "widget.lesson_gauge_chart.view": {
            "class": "WidgetView"
        }
    }
}

11. Teraz możesz użyć wartości pola opisu, zawartej w $data['description'], w widoku widżetu. Otwórz views/widget.view.php i zastąp statyczny tekst "Hello, world!" wartością $data['description'].

ui/modules/lesson_gauge_chart/views/widget.view.php

<?php

/**
 * Gauge chart widget view.
 *
 * @var CView $this
 * @var array $data
 */

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

12. Odśwież stronę dashboardu. Powinieneś teraz zobaczyć tekst opisu widżetu zamiast "Hello, world!".

Pobieranie wartości pozycji przez API

Widget powinien wyświetlać ostatnią wartość pozycji wybranej przez użytkownika. W tym celu należy dodać możliwość wyboru pozycji w konfiguracji widgetu.

W tej sekcji dowiesz się, jak dodać pole wyboru pozycji do formularza widgetu oraz jak dodać wizualną część tego pola do widoku konfiguracji. Następnie kontroler widgetu będzie mógł pobierać dane pozycji i jej wartość za pomocą żądania API. Po otrzymaniu wartości można ją wyświetlić w widoku widgetu.

1. Otwórz includes/WidgetForm.php i dodaj pole CWidgetFieldMultiSelectItem. Umożliwi to wybór pozycji w formularzu konfiguracji.

ui/modules/lesson_gauge_chart/includes/WidgetForm.php

<?php

namespace Modules\LessonGaugeChart\Includes;

use Zabbix\Widgets\{
    CWidgetField,
    CWidgetForm
};

use Zabbix\Widgets\Fields\{
    CWidgetFieldMultiSelectItem,
    CWidgetFieldTextBox
};

/**
 * Gauge chart widget form.
 */
class WidgetForm extends CWidgetForm {

    public function addFields(): self {
        return $this
            ->addField(
                (new CWidgetFieldMultiSelectItem('itemid', _('Item')))
                    ->setFlags(CWidgetField::FLAG_NOT_EMPTY | CWidgetField::FLAG_LABEL_ASTERISK)
                    ->setMultiple(false)
            )
            ->addField(
                new CWidgetFieldTextBox('description', _('Description'))
            );
    }
}

2. Otwórz views/widget.edit.php i dodaj wizualny komponent pola do widoku konfiguracji.

ui/modules/lesson_gauge_chart/views/widget.edit.php

<?php

/**
 * Gauge chart widget form view.
 *
 * @var CView $this
 * @var array $data
 */

(new CWidgetFormView($data))
    ->addField(
        new CWidgetFieldMultiSelectItemView($data['fields']['itemid'])
    )
    ->addField(
        new CWidgetFieldTextBoxView($data['fields']['description'])
    )
    ->show();

3. Wróć do dashboardu i kliknij ikonę koła zębatego w widgetcie, aby otworzyć formularz konfiguracji widgetu.

4. Formularz konfiguracji widgetu zawiera teraz nowe pole wejściowe Item. Wybierz hosta "Zabbix server" oraz pozycję "Load average (1m avg)".

5. Kliknij Apply w formularzu konfiguracji widgetu. Następnie kliknij Save changes w prawym górnym rogu, aby zapisać dashboard.

6. Otwórz i zmodyfikuj actions/WidgetView.php.

Od tego momentu identyfikator pozycji będzie dostępny w kontrolerze widgetu w $this->fields_values['itemid']. Metoda kontrolera doAction() pobiera dane pozycji (nazwę, typ wartości, jednostki) za pomocą metody API item.get oraz ostatnią wartość pozycji za pomocą metody API history.get.

ui/modules/lesson_gauge_chart/actions/WidgetView.php

<?php

namespace Modules\LessonGaugeChart\Actions;

use API,
    CControllerDashboardWidgetView,
    CControllerResponseData;

class WidgetView extends CControllerDashboardWidgetView {

    protected function doAction(): void {
        $db_items = API::Item()->get([
            'output' => ['itemid', 'value_type', 'name', 'units'],
            'itemids' => $this->fields_values['itemid'],
            'webitems' => true,
            'filter' => [
                'value_type' => [ITEM_VALUE_TYPE_UINT64, ITEM_VALUE_TYPE_FLOAT]
            ]
        ]);

        $value = null;

        if ($db_items) {
            $item = $db_items[0];

            $history = API::History()->get([
                'output' => API_OUTPUT_EXTEND,
                'itemids' => $item['itemid'],
                'history' => $item['value_type'],
                'sortfield' => 'clock',
                'sortorder' => ZBX_SORT_DOWN,
                'limit' => 1
            ]);

            if ($history) {
                $value = convertUnitsRaw([
                    'value' => $history[0]['value'],
                    'units' => $item['units']
                ]);
            }
        }

        $this->setResponse(new CControllerResponseData([
            'name' => $this->getInput('name', $this->widget->getName()),
            'value' => $value,
            'description' => $this->fields_values['description'],
            'user' => [
                'debug_mode' => $this->getDebugMode()
            ]
        ]));
    }
}

7. Otwórz views/widget.view.php i dodaj wartość pozycji do widoku widgetu.

ui/modules/lesson_gauge_chart/views/widget.view.php

<?php

/**
 * Gauge chart widget view.
 *
 * @var CView $this
 * @var array $data
 */

(new CWidgetView($data))
    ->addItem([
        new CTag('h1', true, $data['description']),
        new CDiv($data['value'] !== null ? $data['value']['value'] : _('No data'))
    ])
    ->show();

8. Odśwież stronę dashboardu. Widget wyświetli najnowszą wartość pozycji.

Dodawanie zaawansowanych ustawień konfiguracji do widoku konfiguracji

W tej sekcji dowiesz się, jak dodać rozwijaną/zwijaną sekcję Advanced configuration z opcjonalnymi parametrami, takimi jak kolor, wartości minimalna i maksymalna, jednostki oraz pole Description utworzone wcześniej.

1. Utwórz plik Widget.php w głównym katalogu widgetu lesson_gauge_chart, aby utworzyć nową klasę Widget.

Klasa Widget będzie dziedziczyć po klasie bazowej CWidget, aby dodać/nadpisać domyślne ustawienia widgetu (w tym przypadku - tłumaczenia). Poniższy kod JavaScript wyświetla ciąg "No data" w przypadku braku danych. Ciąg "No data" znajduje się w plikach tłumaczeń interfejsu Zabbix.

Jeśli istnieją jakiekolwiek stałe widgetu, zaleca się również określić je w klasie Widget.

ui/modules/lesson_gauge_chart/Widget.php

<?php

namespace Modules\LessonGaugeChart;

use Zabbix\Core\CWidget;

class Widget extends CWidget {

    public const UNIT_AUTO = 0;
    public const UNIT_STATIC = 1;

    public function getTranslationStrings(): array {
        return [
            'class.widget.js' => [
                'No data' => _('No data')
            ]
        ];
    }
}

2. Otwórz includes/WidgetForm.php i dodaj nowe pola Color (selektor koloru), Min (pole numeryczne), Max (pole numeryczne) oraz Units (lista wyboru), a także zdefiniuj domyślną paletę kolorów dla selektora koloru, aby można było z niej skorzystać w kolejnych krokach.

ui/modules/lesson_gauge_chart/includes/WidgetForm.php

<?php

namespace Modules\LessonGaugeChart\Includes;

use Modules\LessonGaugeChart\Widget;

use Zabbix\Widgets\{
    CWidgetField,
    CWidgetForm
};

use Zabbix\Widgets\Fields\{
    CWidgetFieldColor,
    CWidgetFieldMultiSelectItem,
    CWidgetFieldNumericBox,
    CWidgetFieldSelect,
    CWidgetFieldTextBox
};

/**
 * Gauge chart widget form.
 */
class WidgetForm extends CWidgetForm {

    public const DEFAULT_COLOR_PALETTE = [
        'FF465C', 'B0AF07', '0EC9AC', '524BBC', 'ED1248', 'D1E754', '2AB5FF', '385CC7', 'EC1594', 'BAE37D',
        '6AC8FF', 'EE2B29', '3CA20D', '6F4BBC', '00A1FF', 'F3601B', '1CAE59', '45CFDB', '894BBC', '6D6D6D'
    ];

    public function addFields(): self {
        return $this
            ->addField(
                (new CWidgetFieldMultiSelectItem('itemid', _('Item')))
                    ->setFlags(CWidgetField::FLAG_NOT_EMPTY | CWidgetField::FLAG_LABEL_ASTERISK)
                    ->setMultiple(false)
            )
            ->addField(
                (new CWidgetFieldColor('chart_color', _('Color')))->setDefault('FF0000')
            )
            ->addField(
                (new CWidgetFieldNumericBox('value_min', _('Min')))
                    ->setDefault(0)
                    ->setFlags(CWidgetField::FLAG_NOT_EMPTY | CWidgetField::FLAG_LABEL_ASTERISK)
            )
            ->addField(
                (new CWidgetFieldNumericBox('value_max', _('Max')))
                    ->setDefault(100)
                    ->setFlags(CWidgetField::FLAG_NOT_EMPTY | CWidgetField::FLAG_LABEL_ASTERISK)
            )
            ->addField(
                (new CWidgetFieldSelect('value_units', _('Units'), [
                    Widget::UNIT_AUTO => _x('Auto', 'history source selection method'),
                    Widget::UNIT_STATIC => _x('Static', 'history source selection method')
                ]))->setDefault(Widget::UNIT_AUTO)
            )
            ->addField(
                (new CWidgetFieldTextBox('value_static_units'))
            )
            ->addField(
                new CWidgetFieldTextBox('description', _('Description'))
            );
    }
}

3. Otwórz views/widget.edit.php i dodaj wizualne komponenty pól do widoku konfiguracji.

ui/modules/lesson_gauge_chart/views/widget.edit.php

<?php

/**
 * Gauge chart widget form view.
 *
 * @var CView $this
 * @var array $data
 */

$lefty_units = new CWidgetFieldSelectView($data['fields']['value_units']);
$lefty_static_units = (new CWidgetFieldTextBoxView($data['fields']['value_static_units']))
    ->setPlaceholder(_('value'))
    ->setWidth(ZBX_TEXTAREA_TINY_WIDTH);

(new CWidgetFormView($data))
    ->addField(
        (new CWidgetFieldMultiSelectItemView($data['fields']['itemid']))
            ->setPopupParameter('numeric', true)
    )
    ->addFieldset(
        (new CWidgetFormFieldsetCollapsibleView(_('Advanced configuration')))
            ->addField(
                new CWidgetFieldColorView($data['fields']['chart_color'])
            )
            ->addField(
                new CWidgetFieldNumericBoxView($data['fields']['value_min'])
            )
            ->addField(
                new CWidgetFieldNumericBoxView($data['fields']['value_max'])
            )
            ->addItem([
                $lefty_units->getLabel(),
                (new CFormField([
                    $lefty_units->getView()->addClass(ZBX_STYLE_FORM_INPUT_MARGIN),
                    $lefty_static_units->getView()
                ]))
            ])
            ->addField(
                new CWidgetFieldTextBoxView($data['fields']['description'])
            )
    )
    ->show();

4. Wróć do dashboardu, przełącz się w tryb edycji i kliknij ikonę koła zębatego w widgetcie, aby otworzyć formularz konfiguracji widgetu. Formularz konfiguracji widgetu zawiera teraz nową rozwijaną/zwijaną sekcję Advanced configuration.

5. Rozwiń sekcję Advanced configuration, aby zobaczyć dodatkowe pola konfiguracji widgetu. Zwróć uwagę, że pole Color nie ma jeszcze selektora koloru. Dzieje się tak, ponieważ selektor koloru musi zostać zainicjalizowany za pomocą JavaScript, który zostanie dodany w następnej sekcji - Add JavaScript to the widget.

Dodawanie JavaScript do widgetu

W tej sekcji dowiesz się, jak dodać wykres wskaźnikowy - utworzony przy użyciu JavaScript - który pokazuje, czy najnowsza wartość jest prawidłowa, czy też zbyt wysoka/zbyt niska.

1. Utwórz plik widget.edit.js.php w katalogu views.

JavaScript będzie odpowiedzialny za inicjalizację selektora kolorów w widoku konfiguracji.

ui/modules/lesson_gauge_chart/views/widget.edit.js.php

<?php

use Modules\LessonGaugeChart\Widget;

?>

window.widget_lesson_gauge_chart_form = new class {

    init({color_palette}) {
        this._unit_select = document.getElementById('value_units');
        this._unit_value = document.getElementById('value_static_units');

        this._unit_select.addEventListener('change', () => this.updateForm());

        colorPalette.setThemeColors(color_palette);

        for (const colorpicker of jQuery('.<?= ZBX_STYLE_COLOR_PICKER ?> input')) {
            jQuery(colorpicker).colorpicker();
        }

        const overlay = overlays_stack.getById('widget_properties');

        for (const event of ['overlay.reload', 'overlay.close']) {
            overlay.$dialogue[0].addEventListener(event, () => { jQuery.colorpicker('hide'); });
        }

        this.updateForm();
    }

    updateForm() {
        this._unit_value.disabled = this._unit_select.value == <?= Widget::UNIT_AUTO ?>;
    }
};

2. Otwórz views/widget.edit.php i dodaj plik widget.edit.js.php z JavaScript do widoku konfiguracji. Aby to zrobić, użyj metody includeJsFile(). Aby dodać JavaScript wbudowany, użyj metody addJavaScript().

ui/modules/lesson_gauge_chart/views/widget.edit.php

<?php

/**
 * Widok formularza widgetu wykresu wskaźnikowego.
 *
 * @var CView $this
 * @var array $data
 */

use Modules\LessonGaugeChart\Includes\WidgetForm;

$lefty_units = new CWidgetFieldSelectView($data['fields']['value_units']);
$lefty_static_units = (new CWidgetFieldTextBoxView($data['fields']['value_static_units']))
    ->setPlaceholder(_('value'))
    ->setWidth(ZBX_TEXTAREA_TINY_WIDTH);

(new CWidgetFormView($data))
    ->addField(
        (new CWidgetFieldMultiSelectItemView($data['fields']['itemid']))
            ->setPopupParameter('numeric', true)
    )
    ->addFieldset(
        (new CWidgetFormFieldsetCollapsibleView(_('Advanced configuration')))
            ->addField(
                new CWidgetFieldColorView($data['fields']['chart_color'])
            )
            ->addField(
                new CWidgetFieldNumericBoxView($data['fields']['value_min'])
            )
            ->addField(
                new CWidgetFieldNumericBoxView($data['fields']['value_max'])
            )
            ->addItem([
                $lefty_units->getLabel(),
                (new CFormField([
                    $lefty_units->getView()->addClass(ZBX_STYLE_FORM_INPUT_MARGIN),
                    $lefty_static_units->getView()
                ]))
            ])
            ->addField(
                new CWidgetFieldTextBoxView($data['fields']['description'])
            )
    )
    ->includeJsFile('widget.edit.js.php')
    ->addJavaScript('widget_lesson_gauge_chart_form.init('.json_encode([
        'color_palette' => WidgetForm::DEFAULT_COLOR_PALETTE
    ], JSON_THROW_ON_ERROR).');')
    ->show();

3. Wróć do dashboardu, kliknij ikonę koła zębatego w widgetcie, aby otworzyć formularz konfiguracji widgetu. Następnie rozwiń sekcję Advanced configuration, aby zobaczyć zainicjalizowany selektor kolorów. Wypełnij pola wartościami i wybierz kolor dla wykresu wskaźnikowego.

4. Kliknij Apply w formularzu konfiguracji widgetu. Następnie kliknij Save changes w prawym górnym rogu, aby zapisać dashboard.

5. Otwórz actions/WidgetView.php i zaktualizuj kontroler.

Właściwość $this->fields_values zawiera teraz wartości wszystkich pól Advanced configuration. Dokończ kontroler, aby umożliwić przekazanie konfiguracji i wybranej wartości elementu do widoku widgetu.

ui/modules/lesson_gauge_chart/actions/WidgetView.php

<?php

namespace Modules\LessonGaugeChart\Actions;

use API,
    CControllerDashboardWidgetView,
    CControllerResponseData;

class WidgetView extends CControllerDashboardWidgetView {

    protected function doAction(): void {
        $db_items = API::Item()->get([
            'output' => ['itemid', 'value_type', 'name', 'units'],
            'itemids' => $this->fields_values['itemid'],
            'webitems' => true,
            'filter' => [
                'value_type' => [ITEM_VALUE_TYPE_UINT64, ITEM_VALUE_TYPE_FLOAT]
            ]
        ]);

        $history_value = null;

        if ($db_items) {
            $item = $db_items[0];

            $history = API::History()->get([
                'output' => API_OUTPUT_EXTEND,
                'itemids' => $item['itemid'],
                'history' => $item['value_type'],
                'sortfield' => 'clock',
                'sortorder' => ZBX_SORT_DOWN,
                'limit' => 1
            ]);

            if ($history) {
                $history_value = convertUnitsRaw([
                    'value' => $history[0]['value'],
                    'units' => $item['units']
                ]);
            }
        }

        $this->setResponse(new CControllerResponseData([
            'name' => $this->getInput('name', $this->widget->getName()),
            'history' => $history_value,
            'fields_values' => $this->fields_values,
            'user' => [
                'debug_mode' => $this->getDebugMode()
            ]
        ]));
    }
}

6. Otwórz i zmodyfikuj views/widget.view.php.

Musisz utworzyć kontener dla wykresu wskaźnikowego, który narysujesz w kolejnych krokach, oraz kontener dla opisu.

Aby przekazać wartości do JavaScript jako obiekt JSON, użyj metody setVar().

ui/modules/lesson_gauge_chart/views/widget.view.php

<?php

/**
 * Widok widgetu wykresu wskaźnikowego.
 *
 * @var CView $this
 * @var array $data
 */

(new CWidgetView($data))
    ->addItem([
        (new CDiv())->addClass('chart'),
        $data['fields_values']['description']
            ? (new CDiv($data['fields_values']['description']))->addClass('description')
            : null
    ])
    ->setVar('history', $data['history'])
    ->setVar('fields_values', $data['fields_values'])
    ->show();

7. Utwórz nowy katalog assets w katalogu lesson_gauge_chart. Ten katalog będzie używany do przechowywania JavaScript, CSS oraz potencjalnie innych zasobów, takich jak czcionki lub obrazy.

8. Dla JavaScript widoku widgetu utwórz katalog js w katalogu assets.

9. Utwórz plik class.widget.js w katalogu assets/js.

Ta klasa JavaScript widgetu będzie rozszerzać podstawową klasę JavaScript wszystkich widgetów dashboardu - CWidget.

Dashboard opiera się na poprawnej implementacji widgetu i przekazuje wszelkie istotne informacje do widgetu poprzez wywoływanie odpowiednich metod JavaScript. Dashboard oczekuje również, że widget będzie generował zdarzenia, gdy wystąpi jakaś interakcja. Dlatego klasa CWidget zawiera zestaw metod z domyślną implementacją zachowania widgetu, którą można dostosować przez rozszerzenie klasy.

W tym przypadku potrzebne jest pewne dostosowanie, dlatego niestandardowa logika zostanie zaimplementowana dla następujących zachowań widgetu:

• inicjalizacja widgetu, odpowiedzialna za zdefiniowanie początkowego stanu widgetu (zobacz metodę onInitialize());
• wyświetlanie zawartości widgetu (czyli rysowanie wykresu wskaźnikowego), jeśli proces aktualizacji widgetu zakończył się pomyślnie i bez błędów (zobacz metodę processUpdateResponse(response) oraz powiązane metody _resizeChart() i _updatedChart())
• zmiana rozmiaru widgetu (zobacz metodę onResize() oraz powiązaną metodę _resizeChart())

Dla pozostałych aspektów widgetu wykresu wskaźnikowego zostanie użyta domyślna implementacja zachowania widgetu. Aby dowiedzieć się więcej o metodach JavaScript klasy CWidget, zobacz: JavaScript.

Ponieważ ten JavaScript jest wymagany dla widoku widgetu, powinien być ładowany wraz ze stroną dashboardu. Aby włączyć ładowanie JavaScript, należy zaktualizować parametry assets/js i js_class w pliku manifest.json, jak pokazano w kroku 10.

ui/modules/lesson_gauge_chart/assets/js/class.widget.js

class WidgetLessonGaugeChart extends CWidget {

    static UNIT_AUTO = 0;
    static UNIT_STATIC = 1;

    onInitialize() {
        super.onInitialize();

        this._refresh_frame = null;
        this._chart_container = null;
        this._canvas = null;
        this._chart_color = null;
        this._min = null;
        this._max = null;
        this._value = null;
        this._last_value = null;
        this._units = '';
    }

    processUpdateResponse(response) {
        if (response.history === null) {
            this._value = null;
            this._units = '';
        }
        else {
            this._value = Number(response.history.value);
            this._units = response.fields_values.value_units == WidgetLessonGaugeChart.UNIT_AUTO
                ? response.history.units
                : response.fields_values.value_static_units;
        }

        this._chart_color = response.fields_values.chart_color;
        this._min = Number(response.fields_values.value_min);
        this._max = Number(response.fields_values.value_max);

        super.processUpdateResponse(response);
    }

    setContents(response) {
        if (this._canvas === null) {
            super.setContents(response);

            this._chart_container = this._body.querySelector('.chart');
            this._chart_container.style.height =
                `${this._getContentsSize().height - this._body.querySelector('.description').clientHeight}px`;
            this._canvas = document.createElement('canvas');

            this._chart_container.appendChild(this._canvas);

            this._resizeChart();
        }

        this._updatedChart();
    }

    onResize() {
        super.onResize();

        if (this._state === WIDGET_STATE_ACTIVE) {
            this._resizeChart();
        }
    }

    _resizeChart() {
        const ctx = this._canvas.getContext('2d');
        const dpr = window.devicePixelRatio;

        this._canvas.style.display = 'none';
        const size = Math.min(this._chart_container.offsetWidth, this._chart_container.offsetHeight);
        this._canvas.style.display = '';

        this._canvas.width = size * dpr;
        this._canvas.height = size * dpr;

        ctx.scale(dpr, dpr);

        this._canvas.style.width = `${size}px`;
        this._canvas.style.height = `${size}px`;

        this._refresh_frame = null;

        this._updatedChart();
    }

    _updatedChart() {
        if (this._last_value === null) {
            this._last_value = this._min;
        }

        const start_time = Date.now();
        const end_time = start_time + 400;

        const animate = () => {
            const time = Date.now();

            if (time <= end_time) {
                const progress = (time - start_time) / (end_time - start_time);
                const smooth_progress = 0.5 + Math.sin(Math.PI * (progress - 0.5)) / 2;
                let value = this._value !== null ? this._value : this._min;
                value = (this._last_value + (value - this._last_value) * smooth_progress - this._min) / (this._max - this._min);

                const ctx = this._canvas.getContext('2d');
                const size = this._canvas.width;
                const char_weight = size / 12;
                const char_shadow = 3;
                const char_x = size / 2;
                const char_y = size / 2;
                const char_radius = (size - char_weight) / 2 - char_shadow;

                const font_ratio = 32 / 100;

                ctx.clearRect(0, 0, size, size);

                ctx.beginPath();
                ctx.shadowBlur = char_shadow;
                ctx.shadowColor = '#bbb';
                ctx.strokeStyle = '#eee';
                ctx.lineWidth = char_weight;
                ctx.lineCap = 'round';
                ctx.arc(char_x, char_y, char_radius, Math.PI * 0.749, Math.PI * 2.251, false);
                ctx.stroke();

                ctx.beginPath();
                ctx.strokeStyle = `#${this._chart_color}`;
                ctx.lineWidth = char_weight - 2;
                ctx.lineCap = 'round';
                ctx.arc(char_x, char_y, char_radius, Math.PI * 0.75,
                    Math.PI * (0.75 + (1.5 * Math.min(1, Math.max(0, value)))), false
                    );
                ctx.stroke();

                ctx.shadowBlur = 2;
                ctx.fillStyle = '#1f2c33';
                ctx.font = `${(char_radius * font_ratio)|0}px Arial`;
                ctx.textAlign = 'center';
                ctx.textBaseline = 'middle';
                ctx.fillText(`${this._value !== null ? this._value : t('No data')}${this._units}`,
                    char_x, char_y, size - char_shadow * 4 - char_weight * 2
                );

                ctx.fillStyle = '#768d99';
                ctx.font = `${(char_radius * font_ratio * .5)|0}px Arial`;
                ctx.textBaseline = 'top';

                ctx.textAlign = 'left';
                ctx.fillText(`${this._min}${this._min != '' ? this._units : ''}`,
                    char_weight * .75, size - char_weight * 1.25, size / 2 - char_weight
                );

                ctx.textAlign = 'right';
                ctx.fillText(`${this._max}${this._max != '' ? this._units : ''}`,
                    size - char_weight * .75, size - char_weight * 1.25, size / 2 - char_weight
                );

                requestAnimationFrame(animate);
            }
            else {
                this._last_value = this._value;
            }
        };

        requestAnimationFrame(animate);
    }
}

10. Otwórz manifest.json i dodaj:

• nazwę pliku (class.widget.js) do tablicy w sekcji assets/js;
• nazwę klasy (WidgetLessonGaugeChart) do parametru js_class w sekcji widget.

Klasa WidgetLessonGaugeChart będzie teraz automatycznie ładowana wraz z dashboardem.

ui/modules/lesson_gauge_chart/manifest.json

{
    "manifest_version": 2.0,
    "id": "lesson_gauge_chart",
    "type": "widget",
    "name": "Gauge chart",
    "namespace": "LessonGaugeChart",
    "version": "1.0",
    "author": "Zabbix",
    "actions": {
        "widget.lesson_gauge_chart.view": {
            "class": "WidgetView"
        }
    },
    "widget": {
        "js_class": "WidgetLessonGaugeChart"
    },
    "assets": {
        "js": ["class.widget.js"]
    }
}

Dodawanie stylów CSS do widgetu

W tej sekcji dowiesz się, jak dodać niestandardowe style CSS, aby widget wyglądał bardziej atrakcyjnie.

1. Aby dodać style widgetu, utwórz nowy katalog css w katalogu assets.

2. Utwórz plik widget.css w katalogu assets/css. Aby stylizować elementy widgetu, użyj selektora div.dashboard-widget-{widget id}. Aby skonfigurować CSS dla całego widgetu, użyj selektora form.dashboard-widget-{widget id}

ui/modules/lesson_gauge_chart/assets/css/widget.css

div.dashboard-widget-lesson_gauge_chart {
    display: grid;
    grid-template-rows: 1fr;
    padding: 0;
}

div.dashboard-widget-lesson_gauge_chart .chart {
    display: grid;
    align-items: center;
    justify-items: center;
}

div.dashboard-widget-lesson_gauge_chart .chart canvas {
    background: white;
}

div.dashboard-widget-lesson_gauge_chart .description {
    padding-bottom: 8px;
    font-size: 1.750em;
    line-height: 1.2;
    text-align: center;
}

.dashboard-grid-widget-hidden-header div.dashboard-widget-lesson_gauge_chart .chart {
    margin-top: 8px;
}

3. Otwórz plik manifest.json i dodaj nazwę pliku CSS (widget.css) do tablicy w sekcji assets/css. Umożliwi to wczytywanie stylów CSS zdefiniowanych w widget.css wraz ze stroną dashboardu.

ui/modules/lesson_gauge_chart/manifest.json

{
    "manifest_version": 2.0,
    "id": "lesson_gauge_chart",
    "type": "widget",
    "name": "Gauge chart",
    "namespace": "LessonGaugeChart",
    "version": "1.0",
    "author": "Zabbix",
    "actions": {
        "widget.lesson_gauge_chart.view": {
            "class": "WidgetView"
        }
    },
    "widget": {
        "js_class": "WidgetLessonGaugeChart"
    },
    "assets": {
        "css": ["widget.css"],
        "js": ["class.widget.js"]
    }
}

4. Odśwież stronę dashboardu, aby zobaczyć gotową wersję widgetu.