注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。
iframeを利用したカスタムウィジェットは、Workshop内に外部のフルページアプリケーションを埋め込むことを可能にし、開発者がモジュールにカスタムビューを追加する方法を提供します。
埋め込まれたアプリケーションは、Workshopの変数やイベントを使用して双方向に通信することもでき、埋め込まれたアプリがカスタムウィジェットとして機能することを可能にします。アプリケーションを読み書き可能な完全なカスタムウィジェットとしてiframe化する方法の詳細については、カスタムウィジェットの設定オプションを参照してください。
iframeは追加のメモリと処理リソースを必要とするため、Workshopモジュールの安定性とパフォーマンスに影響を与える可能性があることに注意してください。1つ以上のiframeウィジェットを画面に埋め込むことは推奨しません。
Foundry環境に外部リソースをiframeで埋め込むためには、コンテンツセキュリティポリシー (CSP)を設定する必要があります。Foundry環境外のURLを使用してFoundry APIにリクエストを行う場合は、さらにクロスオリジンリソース共有 (CORS)を設定する必要があります。
アプリケーションのURLを静的文字列または文字列変数として入力します。
Slate設定オプションを使用すると、SlateアプリケーションをWorkshopモジュールに埋め込むことができます。パラメーターを使用して、埋め込まれたSlateアプリケーションとWorkshopモジュールが相互にやり取りすることができます。
以下のセクションでは、iframeウィジェットでSlateアプリケーションを埋め込む方法の詳細を提供します。
Slateソースは、モジュール内に埋め込まれたSlateをリファレンスする方法を定義します。CompassリファレンスまたはパーマリンクをSlateソースとして選択することができます。
/workspace/slate/documents/\<slate-permalink>/latest
。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>}} // 送信するデータの値を指定
}
特定の JavaScript プリミティブは、値を文字列変数に格納する際に適切な Workshop タイプにマッピングされます。undefined
は undefined
にマッピングされ(事実上、変数をデフォルト値に戻します)、null
は文字列変数の値をクリアします。
例: 埋め込まれた 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 化する必要があります。
カスタムアプリケーションと 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 ↗ を参照してください。
ユーザーのアプリケーションが 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 ボタンを選択すると、モジュールがライトモードに切り替わります。