プレゼンテーション

このページでは、ウィジェットプレゼンテーションビューの作成に使用できるコンポーネントについて説明します。 ウィジェットプレゼンテーションビューは、ウィジェットの設定に従ってデータを受信し、コンテナ内のダッシュボードに表示するウィジェットの一部です。

プレゼンテーションビューは、次の3つの部分で設定されます。

• ウィジェットアクション
• ウィジェットビュー
• JavaScript

Widget action

ウィジェットアクションクラス(WidgetView)には、プレゼンテーションビューモードでウィジェットを操作するためのメソッドが含まれています。 ウィジェットアクションの大部分は、デフォルトのコントローラークラスCControllerDashboardWidgetViewを使用または拡張します。

ウィジェットのアクションクラスはactionsディレクトリに配置され、manifest.jsonファイル内のactionsパラメーター(actions/widget.{id}.view/class)で指定される必要があります。

actions/WidgetView.php example (implemented in the 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()
            ]
        ]));
    }
}

Widget view

ウィジェットビュークラス(CWidgetView)は、ウィジェットプレゼンテーションビューの構築を担当します。

ウィジェットビュークラスはviewsディレクトリに配置する必要があります。 ウィジェットビュークラスを含むファイルの名前がデフォルト(widget.view.php)とは異なる場合は、manifest.jsonファイルのactionsパラメーター (actions/widget.{id}.view/view)で指定する必要があります。

views/widget.view.php example

<?php

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

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

JavaScript

JavaScriptクラスは、ウィジェットデータの更新、ウィジェットのサイズの変更、ウィジェット要素の表示など、ウィジェットの動作を決定する責任があります。

すべてのJavaScript操作は、すべてのダッシュボードウィジェットのベースJavaScriptクラスであるCWidgetを使用または拡張をします。 CWidgetクラスには、ウィジェット動作のデフォルトの実装を備えた一連のメソッドが含まれています。 ウィジェットの複雑さに応じて、これらのメソッドはそのまま使用または拡張できます。

CWidgetクラスには、次のメソッドが含まれています。

• ウィジェットのライフサイクルを定義するメソッド: _init(), _registerEvents(), _doActivate(), _doDeactivate(), _doDestroy(), setEditMode().
• ウィジェットのデータ更新と表示を処理するメソッド: _promiseUpdate(), _getUpdateRequestData(), _processUpdateResponse(response), _processUpdateErrorResponse(error), _setContents().
• ウィジェットの外観を変更するメソッド: resize(), _hasPadding().

JavaScriptクラスはassets/jsディレクトリに配置し、manifest.jsonファイルのassets (assets/js)パラメーターで指定する必要があります。

ライフサイクルメソッド

ウィジェットのライフサイクルメソッドは、ダッシュボードによって呼び出され、ダッシュボード内に存在する間、ウィジェットのライフサイクルのさまざまな段階で呼び出されます。

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()メソッドは、ウィジェットがダッシュボードから削除される前にクリーンアップタスクを実行します。 クリーンアップタスクとは、ウィジェットの初期化中に確立されたデータベース接続を閉じたり、リソースリークを回避するために一時的なデータをクリーンアップしてシステムメモリを解放したり、不要なイベントの取り扱いやメモリリークを防ぐためにサイズ変更イベントまたはボタンクリックに関連するイベントリスナーの登録を解除したりなどします。 このメソッドは、ウィジェットまたはそれを含むダッシュボードページが削除されたときに呼び出されます。

Note that before the onDestroy() method is invoked, a widget in an active state (WIDGET_STATE_ACTIVE) is always deactivated with the invocation of the onDeactivate() method. 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);
    }
}

onEdit()メソッドは、ダッシュボードが編集モードに変換されるときのウィジェットの外観と動作を定義します。 このメソッドは、通常ユーザーがウィジェットの編集ボタンまたはダッシュボードのダッシュボードの変更ボタンを押し、ダッシュボードが編集モードに移行するときに呼び出されます。

例:

onEdit() {
    this._deactivateGraph();
}

更新プロセスメソッド

ウィジェット更新プロセスメソッドは、Zabbixサーバーまたはその他のデータソースから更新されたデータを取得し、ウィジェットに表示する役割を担います。

promiseUpdate()メソッドは、通常、WebリクエストまたはAPI呼び出しを使用してデータを取得することにより、データ更新プロセスを開始します。 このメソッドは、ダッシュボードページが表示されたときに呼び出され、その後、ダッシュボードページが別のダッシュボードページに切り替わるまで定期的に呼び出されます。

以下は、ほとんどのZabbixネイティブウィジェットが使用するpromiseUpdate()メソッドのデフォルトの実装の例です。 デフォルトの実装では、promiseUpdate()メソッドは、サーバーからデータを取得するための一般的なパターンに従います。 適切なURLとリクエストパラメーターを使用して新しいCurlオブジェクトを作成し、getUpdateRequestData()メソッドで構築されたデータオブジェクトを使用してfetch()メソッドでPOSTリクエストを送信し、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._content_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)メソッドは、レスポンスがエラーである場合、更新リクエスト後にサーバーから受信したレスポンスを処理し、エラーメッセージ/-sを表示します。 このメソッドは、デフォルトのpromiseUpdate()メソッドの一部として、つまりウィジェット更新プロセス中のみ呼び出されます。

デフォルトの実装:

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

setContents(response)メソッドは、ウィジェットの更新プロセスがエラーなく成功した場合にウィジェットの内容を表示します。これには、DOM要素の操作、UIコンポーネントの更新、スタイルの適用、フォーマットなどが含まれます。 このメソッドは、デフォルトのprocessUpdateResponse(response)メソッドの一部として、つまり更新リクエスト後にサーバーから受信したレスポンスを処理するプロセス中のみ呼び出されます。

デフォルトの実装:

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

プレゼンテーション変更メソッド

ウィジェットのプレゼンテーション変更メソッドは、ウィジェットの外観を変更します。

onResize()メソッドは、新しいウィジェットサイズに対応するためにウィジェットの視覚要素の調整を担当します。これには、要素の再配置、要素の寸法調整、テキストの切り捨て、サイズ変更中の応答性を向上させるための遅延読み込みの実装などが含まれます。 このメソッドは、ウィジェットがサイズ変更されたときに呼び出されます。たとえば、ユーザーがウィジェットを手動でサイズ変更するときやブラウザウィンドウのサイズが変更されたときです。

例:

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

hasPadding()メソッドは、ヘッダーを表示に構成されている場合、ウィジェットの下部に8pxの垂直パディングを適用します 。 このメソッドは、ダッシュボードページがアクティブになったとき、つまりユーザーインターフェースの表示されるページになったときに呼び出されます。

デフォルトの実装:

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

一部のウィジェットの場合、使用可能なすべてのウィジェットスペースを使用して、たとえばカスタムの背景色を構成する必要があります。 以下は、zabbixネイティブのアイテムの値ウィジェットで使用されるhasPadding()メソッドの実装の例です。

hasPadding() {
    return false;
}