イベントとアクションの設定

イベントパネルでは、Slate アプリケーション内で定義されたイベントの動作のリストを表示できます。つまり、イベントによってアクションがトリガーされるさまざまな方法をすべて確認できます。さらに、ハンドルバー参照や JavaScript を使用して、これらのイベントのカスタムロジックを定義し、トリガーされたアクションに送信される値を制御できます。 Functions 機能と同様に、イベント JavaScript は DOM や Slate 名前空間にアクセスできず、状態は保存されません。

イベントは、ハンドルバー参照だけでは実現できないページ上のイベントに基づく動作を制御するために使用されます。ダイアログの開閉、ユーザーのクリック、クエリの実行完了などのユーザーインタラクションイベントを利用して、トーストの開閉、クエリの実行、変数の値の設定を行うことができます。これにより、ハンドルバー参照よりもはるかに堅牢なアプリケーションの動作が可能になります。

用語

イベントとは、ボタンの使用やユーザーが選択した値の変更、クエリの完了など、アクションを開始するものです。イベントはアクションの開始者であり、それに対応できるものです。

アクションとは、変数の設定、クエリの実行、ダイアログの開閉など、トリガーされるものです。アクションは、イベントに対応してアプリケーションで何かを実行するために使用できるものです。

グローバルイベント

グローバルイベントは、ウィジェット固有のイベントではなく、すべての Slate アプリケーションで利用可能なイベントです。

slate.ready

slate.ready イベントは、ページが起動して実行される際に発火します。ページが完全にロードされたときではなく、フレームワークがロードされ、クエリが発行され始めたときに発火します。ページの読み込み時にすぐに実行したいアクション（ページの読み込み時に実行したい手動クエリがある場合など）は、ここで行う必要があります。

slate.resize

slate.resize イベントは、ブラウザウィンドウのサイズが変更されるたびに発火します。ブラウザウィンドウのサイズに基づいて何らかの方法でサイズが変更されるウィジェットは、サイズが変更されることになりますが、すべてのウィジェットがそれによって自動的に再配置されるわけではありません。再配置されないウィジェット（チャートなど）には、redraw アクションがあり、ここで発火させることで、関連するウィジェットがブラウザウィンドウのサイズ変更に応じて正しいサイズに再描画されるようになります。

slate.onPrint

slate.onPrint イベントは、ユーザーが slate.print アクションで以前に開いた印刷モーダルを閉じたときにトリガーされます。

slate.userStorageChanged

slate.userStorageChanged イベントは、slate.setUserStorage アクションを使って userStorage が更新されたときに検出されます。これは、別のブラウザタブやウィンドウでユーザーストレージが更新された場合も対応しています。

slate.getMessage

slate.getMessage イベントは、他のアプリケーション内の iframe に表示される Slate アプリケーション用です。slate.getMessage イベントは、特定の形式の親 iframe からのメッセージを受け取るたびに Slate で発火します。具体的には、親フレームからの postMessage の形式で、次のようなものです。

{
  "target": "slate-parent-iframe-event",  // ターゲット： "slate-parent-iframe-event"
  "message": <payload>  // メッセージ： <payload>
}

slate.getMessage イベントは、子ウィンドウまたは親ウィンドウが、次のターゲットプロパティが設定されたオブジェクトを含む postMessage を送信した場合にもトリガーされます:

{
  "target": "SLATE_MESSAGING_SERVICE", // SLATEメッセージングサービス
  ...<payload> // ペイロード
}

次に、このイベントがトリガーされ、イベントの JavaScript ペイン内では <payload> が {{slEventValue}} として利用可能になります。そのため、メッセージ内のデータを適切に使用できます。

Slate に送信されるメッセージは、変数を設定するなどのアクションを実行することもできます：

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
{
  // "slateActionOption"は操作の種類を示します。
  "slateActionOption": {
    // "type"は操作の種類を指定します。ここでは"SET_VARIABLES"が設定されています。これは変数を設定する操作を意味します。
    "type": "SET_VARIABLES",
    // "payload"は操作の詳細を指定します。
    "payload": {
      // "v_variable"は設定する変数の名前を示し、123はその値を示します。
      "v_variable": 123
      }
    }
}

アクションを実行することもできます:

Copied!
1
2
3
4
5
6
7
8
9
{
  // "slateActionOption"という名前のオブジェクト
  "slateActionOption": {
    // "type"という名前のプロパティ。その値は"TRIGGER_ACTION"
    "type": "TRIGGER_ACTION",
    // "payload"という名前のプロパティ。その値はアクションのためのペイロード
    "payload": <アクションのためのペイロード>
    }
}

クエリイベント

QUERY_NAME.success

QUERY_NAME で指定されたクエリが成功した場合にこのイベントが発生します。各クエリはこのイベントの自分だけのインスタンスを持っています。

QUERY_NAME.failure

QUERY_NAME で指定されたクエリが成功せずに完了した場合 – タイムアウト、クエリの形式が不正、または他のサーバー問題などの理由で – このイベントが発生します。各クエリはこのイベントの自分だけのインスタンスを持っています。

クエリアクション

QUERY_NAME.exportCsv & QUERY_NAME.exportXlsx

このアクションは、クエリの出力をユーザーのローカルマシンにダウンロードします。結果は CSV ファイルまたは Excel ファイルとしてダウンロードできます。デフォルトでは、ファイルはクエリの名前を取ります。イベントで { fileName: <<custom_string>> } オブジェクトを返すことで名前をカスタマイズできます。

関数イベント

FUNCTION_NAME.ran

FUNCTION_NAME で指定された関数が実行を終えたときにこのイベントが発生します。各関数はこのイベントの自分だけのインスタンスを持っています。

変数イベント

VARIABLE_NAME.changed

VARIABLE_NAME で指定された変数が変更されたときにこのイベントが発生します。変更された値は {{slEventValue}} として利用可能です。各変数はこのイベントの自分だけのインスタンスを持っています。

ウィジェットイベント

WIDGET_ID.cssClassesUpdated

WIDGET_ID で指定されたウィジェットに属する「追加の CSS クラス」プロパティが変更されたときにこのイベントが発生します。このイベントは DOM が更新された後、しかし描画される前に発生します – つまり、css クラスを使用して異なるウィジェットのサイズを変更している場合、このイベントをトリガーしてそれらのウィジェットに redraw アクションをトリガーすると、期待通りに動作します。各ウィジェットはこのイベントの自分だけのインスタンスを持っています。

WIDGET_ID.transitionend

WIDGET_ID で指定されたウィジェットの直接内部から JavaScript の transitionend イベントが発生するときにこのイベントが発生します（直接とは、その子ウィジェットではなく – transitionend ごとに1つのイベントのみが発火されます）。具体的には – ページ上の要素をアニメーションさせるために CSS トランジションを使用できます。たとえば、サイドバーが存在から存在しない状態にスライドインおよびスライドアウトするなどです。これらのトランジションのいずれかが終了すると、JavaScript は transitionend イベントを発火し、Slate はそれをキャプチャして渡します。これは、これらのトランジションが完了したときにページ上で他の変更を発生させたい場合、またはサイズが変更された可能性があるウィジェットに resize アクションをトリガーする場合などに役立ちます。

このイベントがトリガーされると、{{slEventValue}} は以下のプロパティを持つ JavaScript オブジェクトです: - elapsedTime – トランジションにかかった時間 - propertyName – アニメーション化されているプロパティの名前 - targetId – アニメーション化されている DOM 要素に id プロパティがあった場合、それはここで利用可能です

これらのプロパティは、特定のトランジションを他のものから識別し、コードが正しいものに対応していることを確認するのに役立つかもしれません。各ウィジェットはこのイベントの自分だけのインスタンスを持っています。

WIDGET_ID.INTERACTION_PROPERTY.changed

WIDGET_ID で指定されたウィジェットに属する INTERACTION_PROPERTY という名前のプロパティが変更されたときにこのイベントが発生します。変更された値は {{slEventValue}} として利用可能です。このイベントは各ウィジェットのすべてのプロパティではなく、「インタラクションプロパティ」すなわち、ユーザーの操作によって変更可能なウィジェットのプロパティ、たとえば selectedValue などに対してのみ利用可能です。各ウィジェットのインタラクションプロパティはこのイベントの自分だけのインスタンスを持っています。

グローバルアクション

slate.scrollToId

slate.scrollToId アクションは、指定された id を持つ DOM 要素にページ（およびページ内の他のスクロール可能なコンテナ）をスクロールします – id はイベントパネルの JavaScript コードで返されます。このアクションは、プログラム的に特定の要素にページをスクロールさせるため、またはスクロール可能なテーブルやリストの特定の場所に戻るために使用できます。

slate.sendMessage

slate.sendMessage アクションは、他のアプリケーションの iframes 内に存在する Slate アプリケーション用です – 具体的には、このアクションは渡された値（パネルの JavaScript コードから返される）を取り、親フレームに postMessage を送ります。親フレームへのメッセージは以下の形式になります:

Copied!
1
2
3
4
5
6
7
{
  // "source" : ソースの情報を示します。ここでは "slate-parent-iframe-action" という名前が与えられています。
  "source": "slate-parent-iframe-action", 

  // "message" : 送信するメッセージやデータを指定します。ここでは <payload> というデータが指定されています。
  "message": <payload>
}

ここで、<payload> はパネル内の JavaScript コードから返される値です。

また、slate.sendMessage アクションは、Slate が iframe の中にない場合でも、他のウィンドウにメッセージを送信するために使用できます。

例えば、slate.redirectToUrl を使用して、新しいタブやブラウザウィンドウで子ウィンドウを開き、そのウィンドウに ID を設定することができます。

そして、slate.sendMessage アクションを使って、特定のウィンドウにメッセージを送信することができます。以下のように行います：

Copied!
1
2
3
4
5
6
7
8
9
10
return {
        "targetOptions": {
          // "targetWindow"は送信先ウィンドウを指定します。値は "child"、"opener"、または "parent"のいずれかです。
          "targetWindow": "child" | "opener" | "parent",
          // "children"はオプションで、送信先ウィンドウが "child"の場合に子ウィンドウのIDを指定します。
          "children": ["child-id1", "child-id2"]
        }, 
        // "message"は送信するデータ（ペイロード）を指定します。
        "message": <payload>
        }

ターゲットウィンドウが childに設定されている場合、slate.redirectToUrlを使用して設定された子ウィンドウのIDの配列を提供できます。これが提供されない場合、すべての子ウィンドウにメッセージが送信されます。

openerとparentのtargetWindowはそれぞれwindow.openerとwindow.parentにpostMessageを実行します。

slate.setWindowTitle

slate.setWindowTitleアクションを使用すると、現在のブラウザウィンドウのタイトルを変更できます。これにより、タブ名が更新されます。アクションを呼び出し、文字列を返すことでタブ名を設定します。このアクションがページの読み込み時に呼び出されなかった場合、Slateはタブのタイトルをドキュメント名にデフォルト設定します。

slate.print

slate.printアクションを使用すると、ブラウザの印刷ダイアログを開き、ユーザーが印刷オプションを選択することができます。

slate.downloadBlob

slate.downloadBlobアクションを使用すると、Slateのエクスポート制限に従いながら任意のデータブロブをダウンロードできます。このアクションを使用するには、以下のようにreturn文を追加します：

Copied!
1
2
3
4
5
6
7
8
// ファイル名とblobオブジェクトを含むオブジェクトを返す
return {
  fileName: "my_file.txt", // ファイル名
  blob: new Blob(
    ["Hello, world!"], // テキスト内容
    { type: "text/plain;charset=utf-8" } // MIMEタイプと文字エンコーディング
  ),
};

例えば、ExcelJSのようなライブラリを使用して条件付き書式のExcelファイルを作成し、Functionsタブでそれをslate.downloadBlobに送信してユーザーがダウンロードするという使い方があります。Blobsについての詳細は、MDN web docsを参照してください。

slate.exportWidget

slate.exportWidgetアクションを使用すると、ウィジェットをPNGまたはPDFとしてエクスポートすることができます。このアクションを使用するには、以下のようにreturn文を追加します：

Copied!
1
2
3
4
5
6
return {
    widgetId: "my_chart", // ウィジェットID
    exportType: "download", // エクスポートタイプ
    outputType: "png", // 出力形式
    fileName: "exported_chart", // ファイル名
}

エクスポート設定

サポートされていないウィジェット

iframe、code sandbox、および multiselect box ウィジェットおよび前述のウィジェットを含むコンテナはエクスポートできません。

slate.openAppsPortal

slate.openAppsPortal アクションは、アプリケーションポータルを開きます。オプションで引数を渡すことで、アプリケーションポータルのどの部分に移動するかを指定できます。引数は次の形式でなければなりません。

slate.logout

slate.logout アクションは、ユーザーがログアウトするかどうかを確認するブラウザダイアログを開きます。ユーザーが確認すると、Foundry からログアウトされます。

slate.copyToClipboard

slate.copyToClipboard アクションは、パネル内の JavaScript コードから返された値をユーザーのクリップボードにコピーします。

slate.redirectToUrl

slate.redirectToUrl アクションは、アクションに渡された URL にユーザーをリダイレクトします。slate.ready イベントと一緒にこのアクションを使用することはお勧めしません。これは、ページが読み込まれるとすぐにユーザーがリダイレクトされるため、ユーザーが編集を難しくなります。ユースケースが slate.ready イベントと slate.redirectToUrl アクションを使用することを必要とする場合は、アクションを無効にするクエリパラメーターを追加することをお勧めします。

また、リダイレクトのターゲットを制御することもできます。これを使用するには、アクションを作成し、次のプロパティを持つオブジェクトを返します。

Copied!
1
2
3
4
{
  "url": "https://www.palantir.com/", // このキーはウェブページのURLを指定します
  "target": "_blank" // このキーはオプションで、新しいブラウザタブでURLを開く場合に使用します
}

子ウィンドウで postMessages を送信/受信したい場合、子ウィンドウ用の一意の ID を持つ windowSharingOptions フィールドを追加できます。

Copied!
1
2
3
4
5
6
7
{
  "url": "https://www.palantir.com/", 
  "target": "_blank" (任意), // ウィンドウを新しいタブで開く (オプション)
  "windowSharingOptions": {
    "id": "child-window-id1" // 子ウィンドウのID
  }
}

このウィンドウとは、slate.sendMessageアクションを介して通信することができます。

クエリアクション

QUERY_NAME.run

このアクションは、QUERY_NAMEで指定されたクエリを即座に実行します。クエリが手動であるかどうかに関係なく、これは機能します。各クエリは、このアクションの独自のインスタンスを持っています。

QUERY_NAME.export、QUERY_NAME.exportXlsx、QUERY_NAME.exportCsv

QUERY_NAME.exportは、QUERY_NAMEで指定されたクエリの結果を.xlsxファイルとしてエクスポートします。サーバー上でクエリを実行し、ファイルを生成し、それをユーザーのコンピューターにダウンロードします。各クエリは、このアクションの独自のインスタンスを持っています。

QUERY_NAME.exportアクションは、QueriesタブのExport onドロップダウンメニューからイベントのトリガーとして追加できます。

デフォルトでは、ファイル名はQUERY_NAME.xlsxになります。これを変更するには、Eventsタブに移動し、QUERY_NAME.exportを選択します。次に、戻り値ステートメントを追加してファイル名を設定できます。例えば、return "january_data" または return {fileName: "january_data"} とすると、january_data.xlsx という名前の.xlsxファイルがダウンロードされます。有効なファイル名は空でなく、文字、数字、アンダースコア、またはスペースのみを含んでいる必要があります。戻り値ステートメントのファイル名が無効な場合、クエリの名前がファイル名として使用されます。

EventsタブのActionsドロップダウンメニューから、QUERY_NAME.exportXlsxまたはQUERY_NAME.exportCsvアクションを選択できます。次に、戻り値ステートメントを追加して、ファイル名を有効なファイル名に変更できます。

関数アクション

FUNCTION_NAME.run

このアクションは、FUNCTION_NAMEで指定された関数を即座に実行します。各関数は、このアクションの独自のインスタンスを持っています。

FUNCTION_NAME.export、FUNCTION_NAME.exportXlsx、FUNCTION_NAME.exportCsv

FUNCTION_NAME.exportは、FUNCTION_NAMEで指定された関数の結果を.xlsxファイルとしてエクスポートします。関数を実行し、結果をサーバーに送信し、ファイルを生成し、それをユーザーのコンピューターにダウンロードします。各関数は、このアクションの独自のインスタンスを持っています。

FUNCTION_NAME.exportアクションは、FunctionsタブのExport onドロップダウンメニューからイベントのトリガーとして追加できます。

デフォルトでは、ファイル名はFUNCTION_NAME.xlsxになります。これを変更するには、Eventsタブに移動し、FUNCTION_NAME.exportを選択します。次に、戻り値ステートメントを追加してファイル名を設定できます。例えば、return "january_data" または return {fileName: "january_data"} とすると、january_data.xlsx という名前の.xlsxファイルがダウンロードされます。有効なファイル名は空でなく、文字、数字、アンダースコア、またはスペースのみを含んでいる必要があります。戻り値ステートメントのファイル名が無効な場合、関数の名前がファイル名として使用されます。

EventsタブのActionsドロップダウンメニューから、FUNCTION_NAME.exportXlsxまたはFUNCTION_NAME.exportCsvアクションを選択できます。次に、戻り値ステートメントを追加して、ファイル名を有効なファイル名に変更できます。

変数アクション

VARIABLE_NAME.set

このアクションは、VARIABLE_NAMEで指定された変数を、アクションに渡された値（つまり、アクションパネル内のJavaScriptコードの戻り値）に設定します。古い/現在の変数の値は、{{VARIABLE_NAME}}として利用可能であり、新しい値を設定するために前の値を使用することができます。各変数は、このアクションの独自のインスタンスを持っています。

例

例 1: ボタンクリックで手動クエリをトリガーする

このイベントは、ボタンがクリックされたときにクエリを実行します。

イベントパネルを開き、新しいイベントを作成します。

トリガーイベントにw_button.click、トリガーされるアクションにq_query.runを選択し、変更を確定するためにUpdateを選択します。このペアにはJavaScriptは必要ありません。

これで、ボタンがクリックされるたびに、クエリが再度実行され、他のスレート関数やウィジェットで使用するための新しいデータが取得されます。

例 2: ドロップダウンの値の2倍に変数を設定する

このイベントは、ドロップダウンで選択された金額の2倍に変数を設定します。注: この例は説明のためだけのものであり、通常はスレート関数を使用してこのようなことを行うべきです。

例として、w_selectionDropdownという名前のドロップダウンウィジェットがあり、ユーザーが選択できるさまざまな数字があり、v_doubleSelectionという名前の変数が選択された値の2倍を含むことを想定しています。これを作成するには、イベントパネルを開き、新しいイベントを作成します。イベントにw_selectionDropdown.selectedValue.changedを選び、アクションにv_doubleSelection.setを選びます。次に、イベントパネルに次のようにコードを記入します。

Copied!
1
2
3
4
// 変数dropdownSelectionValueに{{slEventValue}}を代入します。
var dropdownSelectionValue = {{slEventValue}};
// dropdownSelectionValueの2倍の値を返します。
return 2 * dropdownSelectionValue;

最終的な結果は以下のようになります。

{{slEventValue}} はイベントパネル内の特別なハンドルバーの値です。トリガーされたアクションに関連する値がある場合、{{slEventValue}} はその関連する値になります。「.changed」アクションの場合、{{slEventValue}} は関連するウィジェットプロパティが変更された値です。

したがって、ドロップダウンが変更されるたびに、コードはドロップダウンが変更された値を取得し、それを倍にして返します。返される値は、「.set」アクションによって変数に設定される値として使用されます。つまり、ドロップダウンが変更されるたびに、コードはドロップダウンの新しい値を取得し、それを倍にして、変数にこの倍の値を設定します。

例 3: 時間経過で蓄積されたオブジェクトのリストを変数で追跡する

このイベントでは、ユーザーがドロップダウンで選択したすべての値の履歴を保持し、アプリケーションの他の部分でこの値のリストを何らかの方法で使用できるようにします。

w_selectionDropdown という名前のドロップダウンウィジェットがあり、ユーザーが選択できるオプションがあり、選択履歴を含むことを目的とした変数 v_selectionHistory があると仮定します。これを作成するには、イベントパネルを開いて新しいイベントを作成します。「w_selectionDropdown.selectedValue.changed」をイベントに、「v_selectionHistory.set」をアクションに選択します。次に、イベントパネルに次のようにコードを記入します。

Copied!
1
2
3
4
5
6
7
8
// 変数historyに{{v_selectionHistory}}を代入
var history = {{v_selectionHistory}};
// 変数newValueに{{slEventValue}}を代入
var newValue = {{slEventValue}};
// history配列にnewValueを追加
history.push(newValue);
// historyを返す
return history;

最終的な結果は次のようになります。

これで、ユーザーがドロップダウンから何かを選択するたびに、イベントがトリガーされます。コードは現在の v_selectionHistory の値を取得し、新しく選択された値（{{slEventValue}}で渡される）をリストの末尾に追加し、新しく拡張された履歴を返します。アクションが v_selectionHistory.set なので、変数 v_selectionHistory はこの新しい配列に設定され、新しく選択されたアイテムが蓄積された履歴に追加されます。

例 4: ボタンのクリックによる手動クエリのトリガー、条件付き

このイベントは、ボタンがクリックされたときにクエリを実行します - ただし、ユーザーが必要な入力ウィジェット w_input1 と w_input2 にデータを入力した場合のみです。

2つの入力ウィジェット（ユーザーが入力可能なテキストフィールド）w_input1 と w_input2 があると仮定します。さらに、w_buttonConditional という名前のボタンと、手動クエリ q_queryConditional があると仮定します。

さらに、クエリが入力ボックスにユーザーが入力した値、つまり w_input1.text と w_input2.text に依存していて、これら2つの値がなければクエリを実行する意味がない - つまり、これらが空白であってもボタンがクリックされた場合にクエリを実行したくない場合があります。これを次のように実装できます。新しいイベントを作成し、そのイベントには w_buttonConditional.click を、アクションには q_queryConditional.run を選択します。次に、以下のようにイベントパネルにコードを記入します：

Copied!
1
2
3
4
5
6
7
8
// 入力テキストを収集します
var input1Text = {{w_input1.text}};
var input2Text = {{w_input2.text}};

// もし入力が空の場合、アクションを無効化します
if (input1Text === "" || input2Text === "") {
  return {{slDisableAction}};
}

結果は以下のようになるはずです。

{{slDisableAction}} は、イベントパネルの特別なハンドルバーズの値です。パネルのコードからこの値を返すと、トリガーされたアクションが無効になります。つまり、w_input1 または w_input2 のいずれかが空の場合、この特別な値が返され、クエリ q_query は実行されません。ただし、これらの入力の両方が値を持っている場合は、何も返されず、アクションは通常通り進行します。