iframeを利用したカスタムウィジェット

iframeを利用したカスタムウィジェットは、Workshop内に外部のフルページアプリケーションを埋め込むことを可能にし、開発者がモジュールにカスタムビューを追加する方法を提供します。

埋め込まれたアプリケーションは、Workshopの変数やイベントを使用して双方向に通信することもでき、埋め込まれたアプリがカスタムウィジェットとして機能することを可能にします。アプリケーションを読み書き可能な完全なカスタムウィジェットとしてiframe化する方法の詳細については、カスタムウィジェットの設定オプションを参照してください。

iframeは追加のメモリと処理リソースを必要とするため、Workshopモジュールの安定性とパフォーマンスに影響を与える可能性があることに注意してください。1つ以上のiframeウィジェットを画面に埋め込むことは推奨しません。

URL

アプリケーションのURLを静的文字列または文字列変数として入力します。

Slate

Slate設定オプションを使用すると、SlateアプリケーションをWorkshopモジュールに埋め込むことができます。パラメーターを使用して、埋め込まれたSlateアプリケーションとWorkshopモジュールが相互にやり取りすることができます。

以下のセクションでは、iframeウィジェットでSlateアプリケーションを埋め込む方法の詳細を提供します。

Slateソース

Slateソースは、モジュール内に埋め込まれたSlateをリファレンスする方法を定義します。CompassリファレンスまたはパーマリンクをSlateソースとして選択することができます。

• Compassリファレンス: Foundryリソースセレクターを使用して、埋め込むSlateアプリケーションを選択できます。
• パーマリンク: パーマリンクまたはSlateアプリケーションのRIDを入力して選択することができます。Slate RIDはURL内に見つけることができます：/workspace/slate/documents/\<slate-permalink>/latest。

URLパラメーター

URLパラメーターはSlate URLに追加され、Slate内の変数を設定するために使用されます。URLパラメーターを変更するとページ全体がリロードされるため、頻繁に変更する必要のない変数にのみURLパラメーターを使用することをお勧めします。SlateでURLパラメーターをリファレンスするには、URLパラメーターと同じ名前の変数を設定し、ハンドルバーを使用してリファレンスします：{{username}}。静的文字列のURLパラメーターは、URLパラメーターとして直接渡されるため、URIエンコードされる必要があります。

例: ロード時にユーザー名とIDに基づいて埋め込まれたSlateアプリケーションの外観を変更します。

入力パラメーター

入力パラメーターは、Workshopモジュールから埋め込まれたSlateアプリケーションに渡されます。入力パラメーターは、そのキーと値のタイプによって定義されます。静的文字列、文字列変数、数値、オブジェクトセットを埋め込まれたSlateアプリケーションに渡すことができます。

Slateアプリケーション内では、イベントパネルでSlate.getMessageイベントと以下のコード例をリファレンスとして使用することで、Workshopモジュールから情報を取得できます。parameter_keyは、Workshopのiframeウィジェットで定義したキーと一致する必要があります。

Copied!
1
2
const payload = {{slEventValue}} // slEventValueからペイロードを取得
return payload["<parameter_key>"] // ペイロードから指定されたキーの値を返す

例: 組み込み Slate アプリケーションのビューを調整するために Workshop フィルター処理するを設定します。

Copied!
1
2
3
const payload = {{slEventValue}}  // slEventValueからpayloadを取得

return payload["flight-alerts"]  // payloadから"flight-alerts"キーの値を返す

出力パラメーター

出力パラメーターは Slate の埋め込みから Workshop モジュールに渡されます。出力パラメーターは、そのキーと値のタイプによって定義されます。オブジェクトセット、オブジェクトセットフィルター、文字列変数を Workshop モジュールに渡すことができます。Workshop モジュール内では、Workshop 変数をパラメーターに割り当てることで Slate アプリケーションから情報を取得できます。Slate アプリケーション内では、Slate.sendMessage イベントと以下のコードスニペットを使用して情報転送を開始する必要があります。コード内のパラメーターキーは、ユーザーが Workshop ウィジェットで定義したキーと一致する必要があります。

return {
    type: "WORKSHOP//SET_OUTPUT_VALUE", // アクションのタイプを指定
    outputParameterKey: "<parameter_key>", // 出力パラメータのキーを指定
    value: {{<data_to_be_sent>}} // 送信するデータの値を指定
}

例: 埋め込まれた Slate アプリケーションの選択状態を使用して、Workshop のフィルターセット状態を変更します。

return {
    type: "WORKSHOP//SET_OUTPUT_VALUE", // タイプを示すフィールド
    outputParameterKey: "selected-objects", // 出力パラメータのキー
    value: {{f_selection}} // 選択されたオブジェクトの値を設定
}

トリガー可能なイベント

Slate から任意の Workshop イベント をトリガーできます。トリガー可能なイベントは、そのキーとイベントタイプによって定義されます。オーバーレイを開いたり、変数をリセットしたり、さらに多くのイベントをトリガーできます。

Workshop モジュール内で、event_key とトリガーしたいイベントを定義します。Slate アプリケーション内では、Events パネルで Slate.sendMessage イベントと以下のコードスニペットをリファレンスとして使用します。event_key は iframe ウィジェットで定義したキーと一致する必要があります。

return {
    type: "WORKSHOP//TRIGGER_WORKSHOP_EVENT", // ワークショップイベントをトリガーするタイプ
    eventKey: "<event_key>", // イベントキーを指定
}

例: Slate からのボタンクリックで Workshop の折りたたみ可能なセクションを切り替える。

カスタムウィジェット

カスタムウィジェットの設定オプションを使用すると、カスタムで構築されたアプリケーションを埋め込み、定義された設定フィールドを使用して Workshop との双方向通信を可能にします。これにより、埋め込まれたアプリケーションが他の Workshop ウィジェットのように動作し、Workshop の変数を読み書きし、Workshop のイベントを実行することができます。アプリケーションでオントロジーにアクセスするには、Ontology SDK を使用してください。

使用するタイミング

Workshop にはさまざまなウィジェットが用意されていますが、状況によっては Workshop のビルトインウィジェットが提供する機能を超える特定の機能が必要になる場合があります。このカスタムウィジェットオプションを使用すると、ユーザー自身のアプリケーションを作成し、設定フィールドを定義し、他のウィジェットのように Workshop に埋め込むことができます。

カスタムウィジェットの設定

双方向通信を可能にするためには、カスタムアプリケーションのソースコードを設定し、カスタムウィジェットとして iframe 化する必要があります。

ステップ 1: カスタムアプリケーションを Workshop と通信するように変更する

カスタムアプリケーションと Workshop の間の通信は、npm パッケージ @osdk/workshop-iframe-custom-widget を使用して行います。以下のコマンドを使用して、このパッケージをカスタムアプリケーションにインストールしてください。

Copied!
1
npm i @osdk/workshop-iframe-custom-widget

このコマンドは、@osdk/workshop-iframe-custom-widget パッケージをインストールするためのものです。npm は Node.js のパッケージマネージャであり、i は install の略です。 このパッケージは、useWorkshopContext 関数を通じて Workshop と双方向に通信する手段を提供します。この関数は、ユーザーのアプリケーションが Workshop から受け取りたい変数とイベントの定義を受け取り、Workshop の変数値を読み取ったり、Workshop の変数値に書き込んだり、Workshop のイベントを実行するためのインターフェースを持つコンテキストオブジェクトを返します。詳細とさらなる指示については、npm パッケージページ @osdk/workshop-iframe-custom-widget ↗ を参照してください。

ステップ 2: カスタムウィジェットの設定

ユーザーのアプリケーションが Workshop と双方向に通信する変更を加えてデプロイされたら、Workshop モジュールに iframe 経由のカスタムウィジェット を追加し、Custom widget オプションを選択します。

アプリケーションの URL を静的文字列または文字列変数として入力します。ウィジェットの設定パネルは、埋め込まれたアプリケーションによって必要とされる変数とイベントの定義を受け取るのを待つ間、ロード状態を表示します。

必要な変数とイベントの定義を受け取った後、ウィジェットの設定パネルは各変数とイベントのための変数ピッカーとイベントセレクターを表示し、それぞれを設定できるようにします。

設定された Workshop 変数の値は、その変数の値またはロード状態が変わるたびにカスタムアプリケーションに送信されます。設定されたイベントは、カスタムアプリケーション内から実行できるイベントを決定します。

カスタムウィジェットの例

以下のスクリーンショットは、Workshop 内の変数の値の変更がカスタムアプリケーションに即座に送信され、反映される例を示しています。Workshop の文字列変数はカスタムアプリケーションの定義内の変数の1つとして、また Text Input widget の出力として設定されています。ユーザーがウィジェットの入力フィールドにテキストを入力すると（つまり文字列変数の値が変更されると）、その値は即座に送信され、埋め込まれたアプリケーションに反映されます。

以下のスクリーンショットは、Workshop 変数の値を埋め込まれたアプリケーションから設定できる例を示しています。カスタムアプリケーション内の numberField に対して Set a random value ボタンを選択すると、数値が生成され、iframe ウィジェットの設定内で設定された数値変数に渡されます。

以下のスクリーンショットは、埋め込まれたアプリケーション内から Workshop イベントを実行する例を示しています。埋め込まれたアプリケーション設定のために Toggle between light and dark mode イベントが設定されています。アプリケーション内の Execute event ボタンを選択すると、モジュールがライトモードに切り替わります。

制限事項

• 埋め込まれたアプリケーションによって送信されたオブジェクトセットフィールドの定義は、単一のプリセットオブジェクトタイプで指定されます。Workshop で変数を設定する際、変数が制約されるオブジェクトタイプがオブジェクトセット変数の設定パネルに表示されます。Workshop オブジェクトセット変数にプリセットオブジェクトタイプではないオブジェクトが含まれている場合、そのオブジェクトはフィルター処理され、埋め込まれたアプリケーションに送信される前に除外されます。

• オブジェクトセット変数は、埋め込まれたアプリケーションに送信される際に10,000個のオブジェクトに制限されています。Workshop から埋め込まれたアプリケーションに10,000個を超えるオブジェクトを持つオブジェクトセット変数を渡そうとする場合、または埋め込まれたアプリケーション内から10,000個を超えるオブジェクトを持つ Workshop 変数を設定しようとする場合、10,000個目以降のオブジェクトはカットされ、受信者に送信されません。
• 現在、struct 変数はサポートされていません。