プレゼンテーション

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

プレゼンテーションビューは、次の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() メソッドは、ウィジェットがダッシュボードから削除される前にクリーンアップ処理を実行します。これには、ウィジェットの初期化中に確立されたデータベース接続の終了、システムメモリを解放してリソースリークを防ぐための一時データのクリーンアップ、不要なイベント処理やメモリリークを防ぐためのサイズ変更イベントやボタンクリックに関連するイベントリスナーの登録解除などが含まれます。

このメソッドは、ウィジェット、またはウィジェットを含むダッシュボードページが削除されたときに呼び出されます。

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() メソッドは、ダッシュボードが編集モードに切り替わったときのウィジェットの外観と動作を定義します。 このメソッドは、ダッシュボードが編集モードに切り替わる際に呼び出されます。通常は、ユーザーがウィジェットの Edit ボタンまたはダッシュボードの Edit dashboard ボタンを操作したときです。

例:

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._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)メソッドは、レスポンスがエラーである場合、更新リクエスト後にサーバーから受信したレスポンスを処理し、エラーメッセージ/-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;
}