設定

このページでは、カスタム設定フィールドを使用してウィジェット設定ビューを作成するために使用できるクラスについて説明します。 ウィジェット設定ビューは、ユーザーがプレゼンテーションのウィジェットパラメーターを設定できるウィジェットの一部です。

Widget

プライマリウィジェットクラス、すべてのダッシュボードウィジェットの基本クラスCWidgetを拡張します。 デフォルトのウィジェットの動作をオーバーライドするために必要です。

Widgetクラスは、ウィジェットのルートディレクトリ(zabbix/ui/modules/my_custom_widgetなど)に配置する必要があります。

Widget.php example

<?php
       
       namespace Modules\MyCustomWidget;
       
       use Zabbix\Core\CWidget;
       
       class Widget extends CWidget {
       
           public const MY_CONSTANT = 0;
       
           public function getTranslationStrings(): array {
               return [
                   'class.widget.js' => [
                       'No data' => _('No data')
                   ]
               ];
           }
       }

WidgetForm

WidgetFormクラスは、デフォルトクラスCWidgetFormを拡張し、データベース内でウィジェット構成の保存構造を定義し、入力検証を処理するために必要なCWidgetFieldフィールドのセットを含みます。

WidgetFormクラスはincludesディレクトリに配置する必要があります。 クラスに別の名前が付いている場合は、その名前をmanifest.jsonファイルのwidget/form_classパラメーターで指定する必要があります。

includes/WidgetForm.php example

<?php
       
       namespace Modules\MyCustomWidget\Includes;
       
       use Modules\MyCustomWidget\Widget;
       
       use Zabbix\Widgets\{
           CWidgetField,
           CWidgetForm
       };
       
       use Zabbix\Widgets\Fields\{
           CWidgetFieldMultiSelectItem,
           CWidgetFieldTextBox,
           CWidgetFieldColor
       };
       
       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)
                           ->setFilterParameter('numeric', true)
                   )
                   ->addField(
                       new CWidgetFieldTextBox('description', _('Description'))
                   )
                   ->addField(
                       (new CWidgetFieldColor('chart_color', _('Color')))->setDefault('FF0000')
                   );
           }
       }

CWidgetFormView

CWidgetFormViewクラスは、WidgetFormクラスで定義されたフィールドのプレゼンテーションロジックを指定し、設定ビューで表示されるときの外観と動作を決定するために必要です。

CWidgetFormViewクラスは次のメソッドをサポートします。

  • addField() - CWidgetFieldViewクラスのインスタンスをパラメーターとして受け取ります。 各CWidgetFieldクラスには、ウィジェット設定ビューで使用するためのそれぞれのCWidgetFieldViewクラスがあります。
  • includeJsFile() - JavaScriptファイルをウィジェット設定ビューに追加できます。
  • addJavaScript() - ウィジェット設定ビューがロードされるとすぐに実行されるインラインJavaScriptを追加できます。

CWidgetFormViewクラスはviewsディレクトリに配置する必要があります。

views/widget.edit.php example

<?php
           
       /**
        * My custom widget form view.
        *
        * @var CView $this
        * @var array $data
        */
       
       use Zabbix\Widgets\Fields\CWidgetFieldGraphDataSet;
       
       (new CWidgetFormView($data))
           ->addField(
               new CWidgetFieldMultiSelectItemView($data['fields']['itemid'], $data['captions']['items']['itemid'])
           )
           ->addField(
               new CWidgetFieldTextBoxView($data['fields']['description']),
               'js-advanced-configuration'
           )
           ->addField(
               new CWidgetFieldColorView($data['fields']['chart_color']),
               'js-advanced-configuration'
           )
           ->includeJsFile('widget.edit.js.php')
           ->addJavaScript('my_widget_form.init('.json_encode([
               'color_palette' => CWidgetFieldGraphDataSet::DEFAULT_COLOR_PALETTE
           ], JSON_THROW_ON_ERROR).');')
           ->show();

JavaScript

JavaScriptクラスを使用して、ウィジェット設定ビューに動的な動作と対話性を追加できます。 たとえば、CWidgetFormViewクラスで定義されたカラーピッカーを初期化できます。

JavaScriptクラスはフォームとともにロードする必要があるため、メソッドincludeJsFile()およびaddJavaScript()を使用してCWidgetFormViewクラスで参照する必要があります。

以下の例では、シングルトンクラスインスタンスがすぐに作成され、window.my_custom_widget_formという名前で保存されます。 したがって、フォームを2回目に開くとインスタンスが再作成されます。

JavaScriptクラスはviewsディレクトリに配置する必要があります。

views/widget.edit.js.php example

<?php
       
       use Modules\LessonGaugeChart\Widget;
       
       ?>
       
       window.widget_lesson_gauge_chart_form = new class {
       
           init({color_palette}) {
               this._advanced_configuration = document.getElementById('adv_conf');
       
               this._advanced_configuration.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() {
               const show_advanced_configuration = this._advanced_configuration.checked;
       
               for (const element of this._form.querySelectorAll('.js-advanced-configuration')) {
                   element.style.display = show_advanced_configuration ? '' : 'none';
               }
           }
       };

CWidgetField

CWidgetFieldクラスは、すべてのフォームフィールドクラス (CWidgetFieldCheckBoxCWidgetFieldTextAreaCWidgetFieldRadioButtonListなど) が継承される基本クラスです。 CWidgetFieldを拡張するクラスは、ウィジェット設定値の受信、保存、検証を担当します。

次のCWidgetFieldクラスが利用可能です。

CWidgetFieldクラス データベースフィールドタイプ 説明
CWidgetFieldCheckBox int32 Single checkbox.
CWidgetFieldCheckBoxList array of int32 Multiple checkboxes under a single configuration field.
CWidgetFieldColor string Color selection field.
CWidgetFieldDatePicker string Date selection field.
CWidgetFieldHostPatternSelect string Multiselect field that allows to select one or multiple hosts. Supports defining host name patterns (all matching hosts will be selected).
CWidgetFieldIntegerBox int32 Field to enter an integer. Can be used to configure minimum and maximum values.
CWidgetFieldLatLng string Text box that allows to enter comma-separated latitude, longitude, and map zoom level.
CWidgetFieldMultiSelectAction ID Multiselect field for selecting actions (from the list of actions defined in the Alerts → Actions).
CWidgetFieldMultiSelectGraph ID Multiselect field for selecting custom graphs.
CWidgetFieldMultiSelectGraphPrototype ID Multiselect field for selecting custom graph prototypes.
CWidgetFieldMultiSelectGroup ID Multiselect field for selecting host groups.
CWidgetFieldMultiSelectHost ID Multiselect field for selecting hosts.
CWidgetFieldMultiSelectItem ID Multiselect field for selecting items.
CWidgetFieldMultiSelectItemPrototype ID Multiselect field for selecting item prototypes.
CWidgetFieldMultiSelectMediaType ID Multiselect field for selecting media types.
CWidgetFieldMultiSelectService ID Multiselect field for selecting services.
CWidgetFieldMultiSelectSla ID Multiselect field for selecting SLAs.
CWidgetFieldMultiSelectUser ID Multiselect field for selecting users.
CWidgetFieldNumericBox string Field to enter a float number.
CWidgetFieldRadioButtonList int32 Radio box group that consists of one or more radio boxes.
CWidgetFieldRangeControl int32 Slider to select an integer type value.
CWidgetFieldSelect int32 Dropdown select box.
CWidgetFieldSeverities array of int32 CWidgetFieldCheckBoxList preset with trigger severities.
CWidgetFieldTags array of (string, int32, string) Allows to configure one or more tag filter rows.
CWidgetFieldTextArea string Text area for entering multi-line text.
CWidgetFieldTextBox string Text box for entering single-line text.
CWidgetFieldTimeZone string Dropdown with timezones.
CWidgetFieldUrl string Text box that allows to enter URLs.

次のCWidgetFieldクラスが特定のウィジェット用に作成されています。 これらのクラスには非常に特殊な使用例がありますが、必要に応じて再利用することもできます。

CWidgetFieldクラス データベースフィールドタイプ 説明
CWidgetFieldColumnsList array of (multiple mixed) For Top hosts widget. Create a table with custom columns of allowed types.
CWidgetFieldGraphDataSet array of (multiple mixed) For Graph widget. Setup dataset configuration and all related options.
CWidgetFieldGraphOverride array of (multiple mixed) For Graph widget. Setup overrides for specific hosts/items. Any dataset configuration can be overridden.
CWidgetFieldNavTree string For Map navigation tree widget. Replaces widget view in edit mode with the map selection tree.
CWidgetFieldReference string For Map navigation tree widget. Creates a unique identifier for this widget on dashboard. It is used to reference this widget from other widgets.
CWidgetFieldSelectResource ID For Map widget. Allows to select Zabbix network map.
CWidgetFieldThresholds array of (string, string) For Top hosts widget. Allows to configure color and number pairs.
CWidgetFieldWidgetSelect string For Map widget. Allows to select a map navigation tree from the current dashboard. Must be used in combination with CWidgetFieldReference in the Map navigation tree widget.