ユースケース開発WorkshopEmbed Foundry appsiframeを利用したカスタムウィジェット

注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。

iframe

カスタムウィジェットを開発する場合は、iframe ウィジェットの双方向オプションではなく、カスタムウィジェットを使用することを推奨します。

iframe ウィジェットを使用すると、外部のフルページアプリケーションを Workshop 内に埋め込めるため、ビルダーはモジュールにカスタム表示を追加できます。

埋め込みアプリケーションは、Workshop の変数とイベントを使用して双方向に通信することもでき、カスタムウィジェットと同様に動作できます。Workshop からの読み取りと Workshop への書き込みが可能なアプリケーションを iframe で埋め込む方法については、双方向の設定オプションを参照してください。

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

Foundry 環境で外部リソースを iframe で埋め込むには、コンテンツセキュリティポリシー（CSP）を設定する必要があります。外部リソース自体にも、Foundry の URL によるリソースの埋め込みを許可する Content-Security-Policy ヘッダーの frame-ancestors ディレクティブ ↗を設定する必要があります。Foundry API にリクエストを送信する、Foundry 環境外の URL を使用する場合は、さらにクロスオリジンリソース共有（CORS）を設定する必要があります。

URL

アプリケーションの URL を固定の文字列または文字列変数として入力します。別の Foundry アプリケーションを埋め込む場合は、URL クエリパラメーター embedded=true を追加することで、Foundry のサイドバーを非表示にできます。

標準の YouTube URL（たとえば https://www.youtube.com/watch?v=VIDEO_ID）を貼り付けると、Workshop が URL の形式を検出し、iframe 内での表示に必要な適切な埋め込み形式（https://www.youtube.com/embed/VIDEO_ID）にワンクリックで変換するオプションを表示します。

Slate

Slate 設定オプションを使用すると、Workshop モジュールに Slate アプリケーションを埋め込めます。パラメーターを使用することで、埋め込んだ Slate アプリケーションと Workshop モジュールを相互に連携させることができます。

以下のセクションでは、iframe ウィジェットで Slate アプリケーションを埋め込む方法について詳しく説明します。

Slate ソース

Slate ソースは、モジュール内に埋め込む Slate の参照方法を定義します。Slate ソースとして、Compass 参照またはパーマリンクを選択できます。

Compass 参照： Foundry リソースセレクターを使用して、埋め込む Slate アプリケーションを選択できます。
パーマリンク： Slate アプリケーションのパーマリンクまたは RID を入力して、埋め込むアプリケーションを選択できます。Slate の RID は、URL 内の /workspace/slate/documents/<slate-permalink>/latest で確認できます。

URL パラメーター

URL パラメーターは Slate の URL に追加され、Slate の変数を設定するために使用されます。URL パラメーターを変更するとページ全体が再読み込みされるため、変更がほとんど必要ない変数にのみ URL パラメーターを使用することを推奨します。Slate で URL パラメーターを参照するには、URL パラメーターと同じ名前の変数を設定し、handlebars を使用して参照します（{{username}}）。固定の文字列の URL パラメーターは、URL パラメーターとして直接渡されるため、URI エンコードする必要があります。

例：読み込み時に、ユーザー名とユーザーIDに基づいて、埋め込んだ Slate アプリケーションの外観を変更します。

入力パラメーター

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

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

Copied!1
2
const payload = {{slEventValue}}
return payload["<parameter_key>"]

例： Workshop のフィルターを設定して、埋め込んだ Slate アプリケーションの表示を調整します。

Copied!1
2
const payload = {{slEventValue}}
return payload["flight-alerts"]

Workshop 内の Slate アプリケーションの表示を調整するパラメーターが設定された、Slate のイベントパネル。

出力パラメーター

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

return {
    type: "WORKSHOP//SET_OUTPUT_VALUE",
    outputParameterKey: "<parameter_key>",
    value: {{<data_to_be_sent>}}
}

文字列変数に値を格納する際、一部の JavaScript プリミティブは適切な Workshop のデータ型にマッピングされます。undefined は undefined にマッピングされ（実質的に変数をデフォルト値に戻します）、null は文字列変数の値をクリアします。

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

return {
    type: "WORKSHOP//SET_OUTPUT_VALUE",
    outputParameterKey: "selected-objects",
    value: {{f_selection}}
}

Workshop のフィルターセットを変更するパラメーターが設定された、Slate のイベントパネル。

トリガー可能なイベント

Slate から任意の Workshop イベントをトリガーできます。トリガー可能なイベントは、キーとイベントの種類によって定義されます。オーバーレイを開く、変数をリセットするなどのイベントをトリガーできます。

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

return {
    type: "WORKSHOP//TRIGGER_WORKSHOP_EVENT",
    eventKey: "<event_key>",
}

例： Slate でボタンをクリックして、Workshop の折りたたみ可能なセクションの開閉を切り替えます。

return {
    type: "WORKSHOP//TRIGGER_WORKSHOP_EVENT",
    eventKey: "<event_key>",
}

キーと Workshop イベントの入力オプションがある、トリガー可能なイベントの設定メニュー。

Workshop のセクションの開閉を切り替えるパラメーターが設定された、Slate のイベントパネル。

双方向

双方向の設定オプションでは、独自に構築したアプリケーションを埋め込み、定義した設定フィールドを使用して Workshop との双方向通信を有効にできます。これにより、埋め込みアプリケーションはほかの Workshop ウィジェットと同様に動作し、Workshop 変数の読み取りと書き込み、および Workshop イベントの実行が可能になります。アプリケーションでオントロジーにアクセスするには、オントロジー SDK を使用します。

使用するタイミング

Workshop にはさまざまなウィジェットが用意されていますが、状況によっては Workshop の組み込みウィジェットが提供する機能を超える特定の機能が必要になる場合があります。この双方向ウィジェットのオプションでは、独自のアプリケーションを作成し、設定フィールドを定義して、ほかのウィジェットと同様に Workshop に埋め込むことができます。

双方向ウィジェットを設定する

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

ステップ1：カスタムアプリケーションを変更して Workshop と通信する

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

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

このパッケージは、useWorkshopContext 関数を通じて Workshop と双方向に通信するための機能を提供します。この関数は、アプリケーションが Workshop から受け取りたい変数とイベントの定義を受け取り、Workshop 変数の値の読み取り、Workshop 変数の値への書き込み、および Workshop イベントの実行を行うインターフェースを備えたコンテキストオブジェクトを返します。詳細および追加の手順については、@osdk/workshop-iframe-custom-widget ↗ の npm パッケージページを確認してください。

ステップ2：双方向ウィジェットを設定する

Workshop と双方向に通信するための変更を加えてアプリケーションをデプロイしたら、Workshop モジュールに iframe ウィジェットを追加し、双方向の選択肢を選択します。

アプリケーションの URL を、固定の文字列または文字列変数で入力します。埋め込みアプリケーションに必要な変数とイベントの定義を受信するまで、ウィジェットの設定パネルには読み込み中の状態が表示されます。

必要な変数とイベントの定義を受信すると、ウィジェットの設定パネルに、要求された変数とイベントそれぞれの変数ピッカーとイベントセレクターが表示され、それぞれを設定できます。

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

双方向ウィジェットの例

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

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

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

制限事項

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

オブジェクトセット変数は、iframe に埋め込まれたアプリケーションに送信する際、10,000個のオブジェクトに制限されます。10,000個を超えるオブジェクトを含むオブジェクトセット変数を Workshop から iframe に埋め込まれたアプリに渡そうとした場合、または iframe に埋め込まれたアプリケーション内から10,000個を超えるオブジェクトを含む Workshop 変数を設定しようとした場合、10,000個目より後のオブジェクトは切り捨てられ、受信者には送信されません。
現在、構造体変数はサポートされていません。
iframe は、ページから取り除かれた後に再表示されるたびに再読み込みされ、iframe 内に保持されていた状態はすべて破棄されます。この場合にウィジェットがリセットされないようにするには、ウィジェットの表示の最適化設定でマウント状態を保持するように設定するか、ウィジェットに渡す Workshop 変数に双方向ウィジェットのデータを保存します。

ローカルネットワークアクセス

デフォルトでは、ブラウザーのセキュリティポリシーにより、埋め込みアプリケーションから localhost やほかのローカルネットワークアドレスへのリクエストが制限されます。埋め込みアプリケーションがローカルサービスと通信する必要がある場合は、ローカルネットワークアクセスを有効にします。

ローカルネットワークアクセスを許可するには、iframe ウィジェットの設定でローカルネットワークアクセスを許可オプションを有効にします。有効にすると、iframe の allow 属性に local-network 権限が含まれ、埋め込みアプリケーションから localhost アドレスへのリクエストが許可されます。

ローカルネットワークアクセスを有効にすると、埋め込みアプリケーションがユーザーのローカルマシン上のサービスと通信できるようになります。このオプションは、必要な場合で、かつ埋め込みアプリケーションを信頼できる場合にのみ有効にしてください。

←

PREVIOUSEmbed Foundry apps

NEXTWorkshop のドラッグアンドドロップ / 概要

→