ユースケース開発WorkshopFoundry アプリケーションの埋め込みiframe

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

iframe

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

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

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

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

Foundry 環境で外部リソースを iframe に埋め込むには、コンテンツセキュリティポリシー（CSP）を設定する必要があります。外部リソース自体にも、Foundry の URL によるリソースの埋め込みを許可する Content-Security-Policy ヘッダーの frame-ancestors ディレクティブ ↗を設定する必要があります。Foundry 環境の外部にある URL を使用し、その URL から Foundry API にリクエストを送信する場合は、さらにクロスオリジンリソース共有（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 の設定オプションを使用すると、Slate アプリケーションを Workshop モジュールに埋め込むことができます。パラメーターを使用すると、埋め込まれた 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 を使用します。

グローバルブランチで埋め込みの Developer Console アプリケーションを使用するには、ブランチコンテキストの要件に従ってください。ほかの iframe 設定は Workshop モジュールのグローバルブランチコンテキストを継承せず、main にアクションを適用する可能性があります。

使用する場面

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 アドレスにリクエストを送信できるようになります。

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

←

PREVIOUS概要

NEXTアプリケーション間のインタラクティビティ / 概要

→