カスタム・アクションの定義
ここでは、Business Intelligence の実装プロセスの一環として、ダッシュボードで使用するカスタム・アクションを定義する方法を説明します。
概要
KPI クラス内でカスタム・アクションを定義します。次に、以下の操作を行います。
-
ウィジェットで指定の KPI を表示すると、カスタム・アクションを呼び出すそのウィジェットにコントロールを追加できます。"ウィジェット・コントロールの追加" を参照してください。
-
KPI クラスを <cube> 要素の actionClass 属性として指定すると、このクラス内のすべてのアクションをそのキューブを使用するピボット・テーブルで使用できるようになります。つまり、それらのピボット・テーブルを表示するウィジェットにアクションをコントロールとして追加することができます。
-
KPI クラスを別の <kpi> 要素の actionClass 属性として指定すると、その KPI 内で定義されているすべてのアクションに加えて、このクラス内のすべてのアクションをその KPI で使用できるようになります。
-
アナライザ内からアクションを実行できます。この場合、クライアント側のコマンドのサブセット (alert、navigate、および newWindow) のみサポートされます。その他のコマンドは無視されます。
KPI の定義の詳細は、"InterSystems Business Intelligence の上級モデリング" を参照してください。
同じ操作の多くは、以下のように標準アクションまたはカスタム・アクションのいずれかで実行できます。
演算 | 標準アクションとして使用可能か | カスタム・アクションで実行可能か |
---|---|---|
フィルタの設定 | はい | はい |
フィルタの設定と表示の更新 | はい | はい |
ウィジェットの表示の更新 | はい | はい |
ダッシュボード全体の表示の更新 | はい | いいえ |
ピボット・テーブルの行または列の並べ替えの指定 | はい | いいえ |
ピボット・テーブルの行数または列数の指定 | はい | いいえ |
ピボット・テーブルのリストの表示 | はい | いいえ |
別のダッシュボードの表示 | はい | はい |
同じページでの URL の表示 | はい | はい |
新しいページでの URL の表示 | いいえ | はい |
サーバでのコードの実行 | いいえ | はい |
ウィジェットのデータ・ソースの変更 | はい | いいえ |
ウィジェットの行仕様または列仕様の変更 | はい | いいえ |
標準アクションの詳細は、"ウィジェット・コントロールの追加" を参照してください。
コンテキスト情報
システムは、2 つの異なるメカニズムによって、アクションでコンテキスト情報を利用できるようにします。ユーザがカスタム・アクションを起動すると、システムはコンテキスト情報を pContext 変数に書き込みます。この変数は、サーバ上のカスタム・コードで使用できます。カスタム・アクションが URL を開くとき、その URL に $$$VALUELIST および $$$CURRVALUE トークンが含まれていれば、システムはそれらのトークンを置換します。以下の図は、これらのメカニズムを示しています。
アクションの動作の定義
カスタム・アクションを定義するには、アクションを宣言して動作を定義する必要があります。
アクションの宣言
アクションを宣言するには、KPI クラスで以下のタスクのどちらかか両方を実行します。
-
<kpi> 要素内に、アクションごとに <action> 要素を 1 つずつ含めます。
この要素では、この KPI クラス内で使用可能なアクションの名前を指定します。ユーザ・インタフェースでは、この情報を使用して、ユーザが使用できるアクションの一覧が作成されます。以下はその例です。
<kpi xmlns="http://www.intersystems.com/deepsee/kpi" name="Holefoods Actions"> <action name="ActionA"/> <action name="ActionB"/> <action name="ActionC"/> </kpi>
<action> の詳細は、"KPI クラスおよびプラグイン・クラスのリファレンス情報" を参照してください。
-
KPI クラスの %OnGetActionList() コールバック・メソッドをオーバーライドします。このメソッドには、以下のシグニチャがあります。
ClassMethod %OnGetActionList(ByRef pActions As %List, pDataSourceName As %String = "") As %Status
pActions は以下のノードの配列です。
ノード 値 pActions アクションの数 pActions(n) n 番目のアクションに関する詳細。これは、以下の項目で構成される $LISTBUILD リストです。 -
論理アクション名に等しい文字列
-
対応する表示名に等しい文字列
pDataSourceName は、将来使用するためのものです。
以下はその例です。
ClassMethod %OnGetActionList(ByRef pActions As %List, pDataSourceName As %String = "") As %Status { set newaction=$LB("New Action","New Action Display Name") set pActions($I(pFilters))=newaction quit $$$OK }
-
アクションの動作の定義
アクションの動作を定義するには、KPI クラスの %OnDashboardAction() コールバック・メソッドをオーバーライドします。このメソッドには、以下のシグニチャがあります。
classmethod %OnDashboardAction(pAction As %String, pContext As %ZEN.proxyObject) as %Status
このコールバックは、ユーザがダッシュボードでアクションを呼び出したときに実行されます。pAction は、キューブの論理名です。pContext は、現在選択されているスコアカード行に関する情報を含むオブジェクトであり、メソッドがダッシュボードにコマンドを返す方法を提供します。以降のセクションで詳細を説明します。
簡単な例を以下に示します。
ClassMethod %OnDashboardAction(pAction As %String, pContext As %ZEN.proxyObject) As %Status
{
Set sc = $$$OK
Try {
If (pAction = "Action 1") {
//this part defines Action 1
//perform server-side actions
}
Elseif (pAction="Action 2")
{
//this part defines Action 2
//perform other server-side actions
}
}
Catch(ex) {
Set sc = ex.AsStatus()
}
Quit sc
}
このメソッドでは、Action 1 と Action 2 の 2 つのアクションを定義します。
%OnDashboardAction() はクラス・メソッドであるため、このメソッドから %seriesNames や KPI クラスのその他のプロパティにはアクセスできません (クラス・インスタンスは、メソッドからは利用できません)。
使用可能なコンテキスト情報
アクションでは、コンテキスト情報 (アクションを起動する前にユーザが選択した行に基づくダッシュボードからの値) を使用できます。これらの値は、コンテキストに依存するデータベースに変更を加えたい場合に便利です。
%OnDashboardAction() はクラス・メソッドであるため、このメソッドから %seriesNames や KPI クラスのその他のプロパティにはアクセスできません。その代わりに、pContext 変数が用意されています。この変数は、当該操作で使用するための情報を提供するプロパティを持つオブジェクトです。詳細は、以下のシナリオごとに異なります。
シナリオ : ピボット・テーブルをデータ・ソースとして使用するピボット・テーブル・ウィジェット
このシナリオでは、%OnDashboardAction() メソッド内の pContext オブジェクトに、以下の表で説明しているプロパティが格納されます。説明されているように、pContext オブジェクトのコンテンツは、ウィジェットにピボット・テーブル自体が表示される (ピボット・モード) か、リストが表示される (リスト・モード) かによって異なります。
プロパティ名 | ピボット・モードのコンテンツ | リスト・モードのコンテンツ |
---|---|---|
currValue | 最初に選択されているセルの値 | リストの表示前に表示されていた最初の選択セルの値 |
currSeriesNo | 列番号 | リストの表示前に表示されていた最初の選択セルの列番号 |
currItemNo | 行番号 | NULL |
currFilterSpec | 現在のセル・コンテキストに適用されるフィルタ処理を表す 1 つまたは複数の MDX %FILTER 句。これには、すべてのフィルタ・コントロールの値、および行と列のコンテキストが含まれます。 | NULL |
valueList | NULL | リストの 1 列目の値のコンマ区切りリスト (これらの値にコンマが含まれていてはいけません) |
cubeName | このピボット・テーブルによるクエリの対象になるキューブ名 | NULL |
mdx | このピボット・テーブルで定義された MDX クエリ。 | NULL |
pivotVariables | ピボット変数ごとに 1 つのプロパティが含まれているプロキシ・オブジェクト。具体的には、pContext.pivotVariables.varname にはピボット変数 varname の値が含まれています。このプロキシ・オブジェクトでは、すべてのピボット変数名は小文字で表記されます。例えば、サーバ側で MyVar というピボット変数が定義されている場合、このピボット変数は pContext.pivotVariables.myvar として使用できます。 | ピボット・モードと同じ |
filters | 現在アクティブなフィルタ・コントロールの現在値を示す配列。配列内の各ノードの添え字は、フィルタの MDX 式です。ノードの値は、それに対応する 1 つ以上のキーです。キーの形式については、"指定可能なフィルタの既定値" を参照してください。 | ピボット・モードと同じ |
dataSource | 現在のデータ・ソースの名前。 | 現在のデータ・ソースの名前。 |
シナリオ : KPI をデータ・ソースとして使用するピボット・テーブル・ウィジェット
このシナリオでは、%OnDashboardAction() メソッド内の pContext オブジェクトに、以下のテーブルで説明しているプロパティが格納されます。説明されているように、pContext オブジェクトのコンテンツは、ウィジェットにピボット・テーブル自体が表示される (ピボット・モード) か、リストが表示される (リスト・モード) かによって異なります。
プロパティ名 | ピボット・モードのコンテンツ | リスト・モードのコンテンツ |
---|---|---|
currValue | 最初に選択されているセルの値 | リストの表示前に表示されていた最初の選択セルの値 |
currSeriesNo | 列番号 | リストの表示前に表示されていた最初の選択セルの列番号 |
valueList | NULL | リストの 1 列目の値のコンマ区切りリスト (これらの値にコンマが含まれていてはいけません) |
pivotVariables | ピボット変数ごとに 1 つのプロパティが含まれているプロキシ・オブジェクト。具体的には、pContext.pivotVariables.varname にはピボット変数 varname の値が含まれています。このプロキシ・オブジェクトでは、すべてのピボット変数名は小文字で表記されます。例えば、サーバ側で MyVar というピボット変数が定義されている場合、このピボット変数は pContext.pivotVariables.myvar として使用できます。 | ピボット・モードと同じ |
filters | すべてのフィルタ・コントロールの現在値を示す配列。配列内の各ノードは、データ・ソースである KPI で定義されているいずれかのフィルタに対応します。配列内の各ノードの添え字は、KPI 定義クラスで指定されているフィルタの名前です。ノードの値は、そのフィルタで現在選択されている 1 つ以上のキーです。キーの形式については、"指定可能なフィルタの既定値" を参照してください。フィルタにキーが選択されていない場合、対応するノードの値は NULL です。 | ピボット・モードと同じ |
dataSource | 現在のデータ・ソースの名前。 | 現在のデータ・ソースの名前。 |
シナリオ : ピボット・テーブルまたは KPI をデータ・ソースとして使用するスコアカード
スコアカードでは、%OnDashboardAction() メソッド内の pContext オブジェクトのコンテンツは、データ・ソースがピボット・テーブルであるか KPI であるかに関係なくほぼ同じです。以下の表は、スコアカードの pContext のコンテンツを示しており、データ・ソースによって差異がある点について説明しています。
プロパティ名 | データ・ソースとしてピボット・テーブルを使用する場合のコンテンツ | データ・ソースとして KPI を使用する場合のコンテンツ |
---|---|---|
currValue | このスコアカード内で [値列] としてマークされているピボット列の値 | このスコアカード内で [値列] としてマークされている KPI プロパティの値 |
currSeriesNo | 行番号 | データ・ソースがピボット・テーブルの場合と同じ |
valueList | このスコアカード内で [値列] としてマークされているピボット列の値 | このスコアカード内で [値列] としてマークされている KPI プロパティの値 |
pivotVariables | ピボット変数ごとに 1 つのプロパティが含まれているプロキシ・オブジェクト。具体的には、pContext.pivotVariables.varname にはピボット変数 varname の値が含まれています。このプロキシ・オブジェクトでは、すべてのピボット変数名は小文字で表記されます。例えば、サーバ側で MyVar というピボット変数が定義されている場合、このピボット変数は pContext.pivotVariables.myvar として使用できます。 | データ・ソースがピボット・テーブルの場合と同じ |
filters | 現在アクティブなフィルタ・コントロールの現在値を示す配列。配列内の各ノードの添え字は、フィルタの MDX 式です。ノードの値は、それに対応する 1 つ以上のキーです。キーの形式については、"指定可能なフィルタの既定値" を参照してください。 | すべてのフィルタ・コントロールの現在値を示す配列。配列内の各ノードは、データ・ソースである KPI で定義されているいずれかのフィルタに対応します。配列内の各ノードの添え字は、KPI 定義クラスで指定されているフィルタの名前です。ノードの値は、そのフィルタで現在選択されている 1 つ以上のキーです。キーの形式については、"指定可能なフィルタの既定値" を参照してください。フィルタにキーが選択されていない場合、対応するノードの値は NULL です。 |
dataSource | 現在のデータ・ソースの名前。 | データ・ソースがピボット・テーブルの場合と同じ |
クライアント側コマンドの実行
アクションには、制御がダッシュボードに戻ったときに実行するコマンドを含めることができます。そのようなコマンドを含めるには、アクションの定義内に pContext.command プロパティを設定します。以下はその例です。
//this part defines Action 1
//perform server-side actions
//on returning, refresh the widget that is using this KPI
Set pContext.command="refresh;"
pContext.command には、以下の形式の文字列を指定して、単一のコマンドを実行します。
command1
pContext.command には、セミコロンで区切ったコマンドのリストを指定します。
command1;command2;command3;...;
最後のセミコロンはオプションです。
一部のコマンドは、1 つ以上の引数を受け入れます。それらのコマンドには、command の代わりに command:arg1:arg2:... を使用します。
使用可能なコマンド
pContext.command 内では、以下のコマンドを使用できます。
alert:message
メッセージがダイアログ・ボックスに表示されます。message は表示されるメッセージです。
以下はその例です。
Set pContext.command = "alert:hello world!"
applyFilter:target:filterSpec
引数の詳細は、"applyFilter と setFilter の詳細" を参照してください。
このコマンドは、指定されたフィルタを設定し、ブラウザ・ウィンドウを更新します。
例えば、以下のように、ピボット・テーブルにフィルタを適用します。
Set pContext.command = "applyFilter:samplepivot:[DateOfSale].[Actual].[YearSold]:&[2008]"
navigate:url
url は、表示する URL です。
このコマンドは、指定された URL を同じブラウザ・ウィンドウ内で開きます。
以下はその例です。
Set pContext.command = "navigate:http://www.google.com"
newWindow:url
url は、表示する URL です。
このコマンドは、指定された URL を新しいブラウザ・ウィンドウ内で開きます。
以下はその例です。
Set pContext.command = "newWindow:http://www.google.com"
popup:popupurl
popupurl は、ポップアップ・ウィンドウの相対 URL です。
このコマンドにより、指定されたポップアップ・ウィンドウが表示されます。以下はその例です。
Set pContext.command = "popup:%ZEN.Dialog.fileSelect.cls"
refresh:widgetname
widgetname は更新するウィジェットのオプションの名前です。この引数を省略すると、コマンドはユーザがアクションを起動したウィジェットを更新します。
このコマンドは、ブラウザ・ウィンドウの更新に、フィルタの現在の設定を使用します。
以下はその例です。
// Refresh the widget that fired this action and another named samplepivot.
Set pContext.command = "refresh;refresh:samplepivot"
この例では複数のコマンドがセミコロンで区切られています。
setFilter:target:filterSpec
引数の詳細は、"applyFilter と setFilter の詳細" を参照してください。
このコマンドは、指定されたフィルタを設定しますが、ブラウザ・ウィンドウは更新しません。
applyFilter と setFilter の詳細
applyFilter および setFilter コマンドはそれぞれ以下のとおりです。
applyFilter:target:filterSpec
および、
setFilter:target:filterSpec
以下は、この指定の説明です。
-
target は、フィルタ処理するウィジェットです。アスタリスク (*) を使用すると、すべてのウィジェットにフィルタを適用できます。
-
filterSpec では、指定のターゲットに適用するフィルタ値を指定します。これは、以下の形式にする必要があります。
filter_name:filter_values
引数は、以下のようにターゲット・ウィジェットの詳細によって異なります。
シナリオ filter_name filter_values ターゲット・ウィジェットでピボット・テーブルを表示する [dimension].[hierarchy].[level] "設定の構成" の "指定可能なフィルタの既定値" を参照してください。 ターゲット・ウィジェットで KPI を表示する その KPI に定義されているフィルタ名 このフィルタに使用できる値のいずれか (KPI で定義されているものと同じ) メモ :
-
複数のフィルタ仕様を使用できます。そのためには、チルダ (~) でそれぞれを区切ります。以下はその例です。
FILTER:filterspec1~filterspec2
-
MDX クエリを使用する KPI やピボット・テーブルの場合、フィルタ名とフィルタ値では大文字と小文字は区別されません。
-
このフィルタが作用するウィジェットは、同じフィルタを使用するフィルタ・コントロール (非表示の場合もあります) で構成されているウィジェットのみです。例えば、ウィジェットに Cities フィルタ・コントロールが含まれていて、その他のフィルタ・コントロールが含まれていないとします。アクションが市町村に対するフィルタ処理の場合、そのウィジェットは更新されます。アクションが郵便番号に対するフィルタ処理の場合、そのウィジェットは更新されません。
-
別のダッシュボードの表示
カスタム・アクションでは、navigate または newWindow を使用して別のダッシュボードを表示できます。これには、ダッシュボードの URL を使用します ("アプリケーションからダッシュボードへのアクセス" を参照してください)。この URL には、ダッシュボードの状態を初期化する SETTINGS キーワードを含めることができます。
キューブ・コンテキストからの SQLテーブルの生成
カスタム・アクションでは、キューブ・コンテキストから SQL テーブルを作成する %CreateTable API を使用できます。テーブルは、以下のいずれかから作成されます。
-
フィールド・リスト
-
キューブで定義されたリスト (フィールド・リストまたはカスタム SQL クエリ) の名前
詳細は、クラスリファレンスOpens in a new tabを参照してください。