設定

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

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 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 CWidgetFieldTextBox('description', _('Description'))
            )
            ->addField(
                (new CWidgetFieldColor('chart_color', _('Color')))->setDefault('FF0000')
            );
    }
}

CWidgetFormView

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

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

• addField() - CWidgetFieldView クラスのインスタンスをパラメータとして受け取ります。 各 CWidgetField クラスには、ウィジェット設定ビューで使用するための対応する CWidgetFieldView クラスがあります。
• addFieldset() - フィールドを折りたたみ可能なコンテナにまとめる CWidgetFieldsGroupView クラスのインスタンスを受け取ります。
• addFieldsGroup() - フィールドをグループとして視覚的に（境界線付きで）まとめる CWidgetFormFieldsetCollapsibleView のインスタンスを受け取ります。
• includeJsFile() - ウィジェット設定ビューに JavaScript ファイルを追加できます。
• addJavaScript() - ウィジェット設定ビューの読み込み直後に実行されるインライン JavaScript を追加できます。

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

views/widget.edit.php の例

<?php

/**
 * My custom widget form view.
 *
 * @var CView $this
 * @var array $data
 */

use Modules\MyCustomWidget\Includes\WidgetForm;

(new CWidgetFormView($data))
    ->addField(
        (new CWidgetFieldMultiSelectItemView($data['fields']['itemid']))->setPopupParameter('numeric', true)
    )
    ->addFieldset(
        (new CWidgetFormFieldsetCollapsibleView(_('Advanced configuration')))
            ->addField(
                new CWidgetFieldTextBoxView($data['fields']['description'])
            )
            ->addField(
                new CWidgetFieldColorView($data['fields']['chart_color'])
            )
    )
    ->includeJsFile('widget.edit.js.php')
    ->addJavaScript('my_custom_widget_form.init('.json_encode([
        'color_palette' => WidgetForm::DEFAULT_COLOR_PALETTE
    ]).');')
    ->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\MyCustomWidget\Widget;

?>

window.my_custom_widget_form = new class {

    init({color_palette}) {
        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'); });
        }
    }
};

CWidgetField

CWidgetField クラスは、すべてのフォームフィールドクラス（CWidgetFieldCheckBox、CWidgetFieldTextArea、CWidgetFieldRadioButtonList など）が継承する基底クラスです。
CWidgetField を拡張するクラスは、ウィジェット設定値の受け取り、保存、検証を担当します。

以下の CWidgetField クラスを使用できます。