9 カスタム・データ・アクション・プラグインの作成
Oracle Analyticsで使用するカスタム・データ・アクション・プラグインを作成できます。
データ・アクション・プラグインは、Oracle Analyticsを拡張し、ユーザーがビジュアライゼーションのデータ・ポイントを選択し、特定のアクションを起動できるようにします。Oracle Analyticsには、多くの一般的なユースケースを網羅するデータ・アクションのコア・セットが用意されていますが、独自のデータ・アクション・プラグインを作成することで、この機能をさらに拡張できます。
チュートリアルでは、例を使用してカスタム・データ・アクション・プラグインの作成方法を理解できます。
カスタム・データ・アクション・プラグインを作成するには、次の要素に関する基本的な理解が必要です:
- JavaScript
- RequireJS
- JQuery
- KnockoutJS
データ・アクション・プラグインおよびデータ・アクション・フレームワークについて
データ・アクション・プラグインは、データ・アクション・フレームワークを活用して、Oracle Analyticsユーザー・インタフェースに緊密に統合されているカスタムのデータ駆動型アクションを提供します。
ユーザーがデータ・アクションを起動すると、データ・アクション・マネージャは、リクエストの処理を担当するデータ・アクション・プラグインにリクエスト・コンテキスト(修飾データ参照、メジャー値、フィルタ、メタデータなど)を渡します。Oracleでは、CanvasDataAction、URLNavigationDataAction、HTTPAPIDataActionおよびEventDataActionという4つのタイプのデータ・アクション・プラグインが提供されます。これらのデータ・アクション・プラグイン・タイプとその抽象ベース・クラスを拡張して、独自のデータ・アクションを提供できます。
データ・アクション・カテゴリ
データ・アクション・カテゴリには、URLへのナビゲート、HTTP API、キャンバスへのナビゲート、およびイベント・アクションが含まれます:
- URLへのナビゲート: 指定されたURLを新しいブラウザ・タブで開きます。
- HTTP API:
GET/POST/PUT/DELETE/TRACEコマンドを使用してHTTP APIをターゲット指定し、結果を新しいタブで開きません。かわりに、HTTPステータス・コードが調査され、一時的な成功または失敗メッセージが表示されます。 - キャンバスへのナビゲート: 同じかまたは異なるビジュアライゼーションでユーザーがソース・キャンバスからターゲット・キャンバスにナビゲートできるようにします。ソース・キャンバス内で有効なフィルタは、すべて外部フィルタとしてターゲット・キャンバスに渡されます。ターゲット・キャンバスが開かれると、ビジュアライゼーションへの外部フィルタの適用が試行されます。外部フィルタが適用されるメカニズムは、ここでは説明しません。
- イベント・アクション: Oracle Analyticsイベント・ルーターを使用してイベントを公開します。どのJavaScriptコード(サード・パーティ・プラグインなど)でもこれらのイベントにサブスクライブでき、その結果に基づいてカスタム・レスポンスを処理できます。プラグイン開発者はデータ・アクションの応答方法を選択できるため、柔軟性が最大限に高まります。たとえば、ユーザー・インタフェースを表示することも、一度に複数のサービスにデータを渡すこともできます。
URLへのナビゲートとHTTP APIのデータ・アクション・カテゴリ・タイプは、両方ともトークン構文を使用して、ビジュアライゼーションからURLおよびPOSTパラメータにデータまたはメタデータを挿入できます。
URLトークンの置換
HTTPデータ・アクションでは、URL内のトークンを、データ・アクションに渡されるコンテキストに基づいた値に置換できます。たとえば、修飾データ参照値、フィルタ値、ユーザー名、プロジェクト・パスおよびキャンバス名が対象になります。
| トークン | ノート | 置換後の値 | 例 | 結果 |
|---|---|---|---|---|
${valuesForColumn:COLUMN} |
該当なし | 修飾データ参照に基づいた列の表示値。 | ${valuesForColumn: "Sales"."Products"."Brand"} |
BizTech,FunPod |
${valuesForColumn:COLUMN, separator:"/"}
|
複数の値に置換される可能性のあるトークンでは、任意のセパレータ・オプションがサポートされます。separatorは、カンマ(,)がデフォルトですが、任意の文字列に設定できます。この文字列内で二重引用符をエスケープするには、バックスラッシュ(\)を使用します。
|
修飾データ参照に基づいた列の表示値。 | ${valuesForColumn: "Sales"."Products"."Brand"} |
BizTech,FunPod |
${valuesForColumn:COLUMN, separationStyle:individual}
|
separationStyleは、delimitedがデフォルトですが、値ごとに個別のURLパラメータを生成する必要がある場合はindividualに設定できます。
|
修飾データ参照に基づいた列の表示値。 | &myParam=${valuesForColumn: "Sales"."Products"."Brand"} |
&myParam=BizTech&myParam=FunPod |
${keyValuesForColumn:COLUMN}
|
NA | 修飾データ参照に基づいた列のキー値。 | ${keyValuesForColumn:COLUMN} |
10001,10002 |
${env:ENV_VAR}
|
サポートされる環境変数は、sProjectPath、sProjectName、sCanvasName、sUserIDおよびsUserNameです。
|
環境変数。 | ${env:'sUserID'} |
myUserName |
データ・アクション・コンテキスト
ユーザーがデータ・アクションを起動したときに渡されるコンテキストを定義できます。
データ・アクションの作成時に、そのデータ・アクションに渡されるコンテキストの分量を定義します。
修飾データ参照
データ・アクションが起動されると、LogicalFilterTreeオブジェクトの配列を使用して、マークされたデータ・ポイントごとに修飾データ参照が生成されます。LogicalFilterTreeは、ツリー構造に編成された複数のLogicalFilterNodeオブジェクトで構成されます。このオブジェクトには次のものが含まれます:
- データ・レイアウトの行エッジまたは列エッジの属性。
- マークされた各セルに対応するメジャー・エッジの特定のメジャー。
- マークされた各セルの特定のメジャー値。
- キー値と表示値。
環境変数
一部のデータ・アクションでは、マークされた各データ・ポイントを説明するデータおよびメタデータに加え、データ・アクションが起動される環境を説明するより詳細なコンテキストが必要になることがあります。このような環境変数には次のものが含まれます:
- プロジェクト・パス
- プロジェクト名
- キャンバス名
- ユーザーID
- ユーザー名
データ・アクション・コード設計
APIクラスを使用してデータ・アクションを作成します。
AbstractDataActionクラスから継承されるデータ・アクションの4つの具象クラスは次のとおりです:CanvasDataActionURLNavigationDataActionHTTPAPIDataActionEventDataAction
- データ・アクション・プラグインAPIを使用して、新しいタイプのデータ・アクションを作成できます。Data Visualization SDKリファレンスを参照してください。
- データ・アクション・タイプの登録は、
DataActionPluginHandlerによって管理されます。 - データ・アクションのインスタンスの作成、読取り、編集、削除または起動を行うコードは、イベントを公開することでそれらを行います。
- イベントは、
DataActionManagerによって処理されます。
データ・アクション・モデル・クラス
データ・アクション・モデル・クラスにはいくつかの異なるタイプがあります。
AbstractDataAction
このクラスの役割は次のとおりです:
- Knockoutモデルの格納(サブクラスは独自のプロパティでこれを自由に拡張できます)。
- サブクラスが実装する必要のある抽象メソッドの定義:
+ invoke(oActionContext: ActionContext, oDataActionContext:DataActionContext) <<abstract>>渡されたコンテキストでデータ・アクションを起動します(コール元は常に
DataActionManagerである必要があります)。+ getGadgetInfos(oReport): AbstractGadgetInfo[] <<abstract>>このタイプのデータ・アクションを編集するためのユーザー・インタフェース・フィールドをレンダリングする役割を持つ
GadgetInfosを構築して返します。+ validate() : DataActionErrorデータ・アクションを検証して、有効な場合はnullを、無効な場合は
DataActionErrorを返します。
- データ・アクションのユーザー・インタフェース・フィールドの一般的な部分をレンダリングするために使用される次のメソッドのデフォルト実装を提供:
+ getSettings():JSONレポートに含める準備のためにデータ・アクションのKnockoutモデルをJSONにシリアライズします(komapping.toJS(_koModel)を使用します)。
+ createNameGadgetInfo(oReport) : AbstractGadgetInfoデータ・アクションの「名前」フィールドをレンダリングできる
GadgetInfoを構築して返します。+ createAnchorToGadgetInfo(oReport) : AbstractGadgetInfoデータ・アクションの「アンカー先」フィールドをレンダリングできる
GadgetInfoを構築して返します。+ createPassValuesGadgetInfo(oReport) : AbstractGadgetInfoデータ・アクションの「値を渡す」フィールドをレンダリングできる
GadgetInfoを構築して返します。
サブクラスでは、ベース・クラスによって提供されるすべてのGadgetInfoが必要とされるわけではないため、状況によってはこれらすべてのメソッドをコールする必要はありません。この方法で各フィールドのレンダリングを抽出することで、サブクラスは必要なガジェットを自由に選択できます。一部のサブクラスでは、これらの一般的なデータ・アクション・ガジェットの異なる実装を提供することも可能です。
CanvasDataAction、URLNavigationDataAction、HTTPAPIDataAction、EventDataAction
これらは、データ・アクションの基本タイプの具象クラスです。これらのクラスは、独自に動作して、これらのタイプのデータ・アクションに対して一般的なユーザー・インタフェースを提供します。また、カスタム・データ・アクション・プラグインで拡張できる有益なベース・クラスとしても動作します。
- CanvasDataAction: キャンバスにナビゲートするために使用します。
- URLNavigationDataAction: 新しいブラウザ・ウィンドウでWebページを開くために使用します。
- HTTPAPIDataAction: HTTP APIに対する
GET/POST/PUT/DELETE/TRACEリクエストを作成してHTTP Responseをプログラムで処理するために使用します。 - EventDataAction: イベント・ルーターを通じてJavaScriptイベントを公開するために使用します。
各クラスの役割は次のとおりです:
- ベース・クラスからの抽象メソッドの実装。
invoke(oActionContext: ActionContext, oDataActionContext:DataActionContext)このメソッドは、KOModelで定義されたプロパティと指定された
DataActionContextオブジェクトを結合してデータ・アクションを起動します。getGadgetInfos(oReport): AbstractGadgetInfo[]このメソッドの操作内容は次のとおりです:
AbstractGadgetInfosを格納した配列を作成します。- 各
AbstractGadgetInfoを配列に配置する個々のcreateXXXGadgetInfo()メソッドをコールします。 - 配列を返します。
- データ・アクションの特定のサブクラスに固有の個々のガジェットを作成するための追加メソッドを提供。
これらの具象クラスのサブクラスでは、カスタム・ユーザー・インタフェースのスーパークラスによって提供されるすべてのガジェットを使用する必要はありません。この方法で各ガジェットの構築を抽出することで、サブクラスは必要なガジェットを自由に選択できます。
DataActionKOModel、ValuePassingMode
DataActionKOModelクラスは、AbstractDataActionの異なるサブクラスによって共有されるベースKOModelを提供します。「DataActionKOModel クラス」を参照してください。
データ・アクション・サービス・クラス
いくつかの異なるデータ・アクション・サービス・クラスがあります。
DataActionManager
DataActionManagerとのすべてのやり取りでは、次の操作用のイベント・ハンドラを実装しているClientEvents.DataActionManagerを使用します:
- 現在のプロジェクトに定義されたデータ・アクション・セットの管理。
- データ・アクションの起動。
- 現在のプロジェクトに定義されたすべてのデータ・アクションの取得。
- マークされた現在のデータ・ポイントに適用できるすべてのデータ・アクションの取得。
DataActionContext、EnvironmentContext
データ・アクションが起動されると、ターゲットに渡されるコンテキストがDataActionContextクラスに格納されます。
getColumnValueMap()属性列名でキー設定された属性列値のマップを返します。これらは、データ・アクションの起動元となるデータ・ポイントの修飾データ参照を定義します。
getLogicalFilterTrees()データ・アクションの起動元となる特定のデータ・ポイントの修飾データ参照を記述した
LogicalFilterTreesオブジェクトを返します(詳細はInteractionServiceを参照してください)。getEnvironmentContext()ソース環境を記述した次のような
EnvironmentContextクラスのインスタンス:getProjectPath()getCanvasName()getUserID()getUserName()
getReport()データ・アクションの起動元のレポートを返します。
DataActionHandler
DataActionHandlerクラスは、様々なデータ・アクション・プラグインを登録します。そのAPIは、他のプラグイン・ハンドラ(VisualizationHandlerなど)と広範囲にわたり整合性があります。
DataActionHandlerクラスは、次のパブリック・メソッドを提供しています:
getClassName(sPluginType:String) : String指定されたデータ・アクション・タイプの完全修飾クラス名を返します。
getDisplayName(sPluginType:String) : String指定されたデータ・アクション・タイプの翻訳された表示名を返します。
getOrder(sPluginType:String) : Numberデータ・アクション・タイプのリストを優先順序にソートするために使用される数値を返します。
DataActionHandlerクラスは、次の静的メソッドを提供しています:
getDependencies(oPluginRegistry:Object) : Object.<String, Array>登録されたすべてのデータ・アクション・タイプをカバーする依存性マップを返します。
getHandler(oPluginRegistry:Object, sExtensionPointName:String, oConfig:Object) : DataActionPluginHandlerDataActionHandlerクラスの新規インスタンスを構築して返します。
DataActionUpgradeHandler
DataActionUpgradeHandlerクラスは、レポートが開かれたときにUpgradeServiceによってコールされます。
DataActionHandlerクラスは、次の2つのメイン・メソッドを提供しています:
deferredNeedsUpgrade(sCurrentVersion, sUpgradeTopic, oDataActionJS, oActionContext) : Promise指定されたデータ・アクションをアップグレードするか(
true)、アップグレードしないか(false)を示すブールに解決されるPromiseを返します。このメソッドは、データ・アクション・インスタンスのバージョン番号を、データ・アクションのコンストラクタから取得したバージョン番号と比較して、データ・アクションをアップグレードする必要があるかどうかを決定します。インスタンスのバージョン番号がコンストラクタのバージョン番号より小さい場合、データ・アクション・インスタンスをアップグレードする必要があります。performUpgrade(sCurrentVersion, sUpgradeTopic, oDataActionJS, oActionContext, oUpgradeContext) : Promise指定されたデータ・アクションでアップグレードを実行し、
Promiseを解決します。アップグレード自体は、データ・アクションのupgrade()メソッドをコールすることで実行されます(アップグレード自体の要件を満たすのは、アップグレードされるデータ・アクションの特定のサブクラスのみです)。getOrder(sPluginType:String) : Numberデータ・アクション・タイプのリストを優先順序にソートするために使用される数値を返します。
データ・アクション・コード相互作用
データ・アクションは、ユーザー・インタフェース・フィールドを作成するとき、およびユーザーがデータ・アクションを起動するときに、Oracle Analyticsコードとやり取りします。
新しいデータ・アクション・インスタンス用のフィールドの作成
このやり取りは、Oracle Analyticsがデータ・アクションのユーザー・インタフェース・フィールドをレンダリングするときに開始します。そのために、次を行います:
- データ・アクションから返される
GadgetInfosの親のGadgetInfoとして動作するPanelGadgetInfoを作成します。 - データ・アクションの
getGadgetInfos()をコールします。 - 最初のステップで作成した
PanelGadgetInfoの子としてデータ・アクションのGadgetInfosを追加します。 PanelGadgetInfoをレンダリングするPanelGadgetViewを作成します。PanelGadgetViewのコンテナであるHTMLElementを設定します。HostedComponentツリーにすでに接続されているHostedComponentの子のHostedComponentとしてPanelGadgetViewを登録します。これにより、
getGadgetInfos()から返される配列の表示順序でパネル・ガジェット内にデータ・アクションのガジェットがレンダリングされます。
データ・アクションの起動
ユーザーがOracle Analyticsユーザー・インタフェースから(たとえば、ビジュアライゼーションのデータ・ポイントのコンテキスト・メニューから)データ・アクションを起動すると、このやり取りが開始します。
ユーザー相互作用に応答して、コードにより次の操作が行われます:
- データ・アクションのID、データ・アクションの起動元である
DataVisualization、およびTransientVizContextオブジェクトが含まれるINVOKE_DATA_ACTIONイベントを公開します。 DataActionManagerは、次の操作によってこのイベントを処理します:- データ・アクション・インスタンスをそのIDから取得します。
- 指定された
DataVisualizationでマークされたデータ・ポイントのLogicalFilterTreesを取得します。 - データ・アクションのターゲットに渡されるすべての情報が含まれた
DataActionContextを構築します。 - データ・アクションの
invoke(oDataActionContext)をコールします。
データ・アクションplugin.xmlファイルの例
ここでは、CanvasDataActionデータ・アクションのplugin.xmlファイルの例を示します。
plugin.xmlの例
<?xml version="1.0" encoding="UTF-8"?>
<tns:obiplugin xmlns:tns="http://plugin.frameworks.tech.bi.oracle"
xmlns:viz="http://plugin.frameworks.tech.bi.oracle/extension-points/visualization"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
id="obitech-currencyconversion"
name="Oracle BI Currency Conversion"
version="0.1.0.@qualifier@"
optimizable="true"
optimized="false">
<tns:resources>
<tns:resource id="currencyconversion" path="scripts/currencyconversion.js" type="script" optimizedGroup="base"/>
<tns:resource-folder id="nls" path="resources/nls" optimizable="true">
<tns:extensions>
<tns:extension name="js" resource-type="script"/>
</tns:extensions>
</tns:resource-folder>
</tns:resources>
<tns:extensions>
<tns:extension id="oracle.bi.tech.currencyconversiondataaction" point-id="oracle.bi.tech.plugin.dataaction" version="1.0.0">
<tns:configuration>
{
"resourceBundle": "obitech-currencyconversion/nls/messages",
"properties":
{
"className": "obitech-currencyconversion/currencyconversion.CurrencyConversionDataAction",
"displayName": { "key" : "CURRENCY_CONVERSION", "default" : "Currency Conversion" },
"order": 100
}
}
</tns:configuration>
</tns:extension>
</tns:extensions>
</tns:obiplugin>拡張するために最適なデータ・アクション・クラスの選択
カスタム・データ・アクション・プラグインの記述を開始する前に、拡張する既存のデータ・アクション・クラスを決定します。データ・アクションで実行しようとする操作に最も近い機能を提供するデータ・アクション・クラスを選択してください。
各データ・アクションは、クラス図に示すように、AbstractDataActionクラスから継承されます。このクラス図は、拡張可能な2つの抽象データ・アクション・クラス(AbstractDataActionとAbstractHTTPDataAction)および4つの具象データ・アクション・クラス(CanvasDataAction、URLNavigationDataAction、HTTPAPIDataActionおよびEventDataAction)を示しています。提供する各データ・アクションは、これらのクラスのいずれかを拡張する必要があります。どのクラスを拡張するかは、データ・アクションの起動時に実装する動作によります。ほとんどのサード・パーティ・データ・アクションは、URLNavigationDataAction、HTTPAPIDataActionまたはEventDataActionのいずれかを拡張することになります。
拡張するクラスとは関係なく、データ・アクションを起動すると、データ・アクションの起動元であるデータ・ポイントの完全なコンテキストを説明したメタデータが提供されます。「データ・アクション・コンテキスト」を参照してください。
AbstractDataActionクラス
AbstractDataActionは、すべてのタイプのデータ・アクションの継承元となる抽象ベース・クラスです。これは、サブクラスで使用できる共通機能およびデフォルト動作を提供する役割を果たします。
AbstractDataAction
すべてのタイプのデータ・アクションは、AbstractDataActionベース・クラスのサブクラスです。これは、すべてのデータ・アクションに共通する機能のコア・セットを提供します。起動時に複数のタイプのアクションを実行する複雑なデータ・アクションを作成する場合や具象クラスでサポートされない操作を実行する場合を除き、このクラスを直接拡張しないでください。複雑なデータ・アクションを作成する必要がある場合は、必要な機能に最も近い機能を提供する具象クラスを拡張することを検討してください。
AbstractDataActionの構文
+ AbstractDataAction(oKOModel)
+ getKOViewModel():DataActionKOModel
+ createFromJS(fDataActionConstructor, sClassName, oDataActionKOModelUS) : AbstractDataAction+ invoke(oActionContext, oDataActionContext)
+ getGadgetInfos(oReport) : AbstractGadgetInfo[]
+ validate() : DataActionError+ getSettings() : Object
+ requiresActionContextToInvoke() : Boolean
+ isAllowedHere() : Boolean# createNameGadgetInfo(oReport) : AbstractGadgetInfo
# createAnchorToGadgetInfo(oReport) : AbstractGadgetInfo
# createPassValuesGadgetInfo(oReport) : AbstractGadgetInfoDataActionKOModelクラス
AbstractDataActionの各サブクラスは、その独自のサブクラスであるDataActionKOModelを作成することが多くあります。DataActionKOModelベース・クラスには、次のプロパティがあります:
DataActionKOModel、ValuePassingMode
sID:Stringデータ・アクション・インスタンスに割り当てられる一意のID。
sClass:Stringこの特定タイプのデータ・アクションのクラス名。
sName:Stringデータ・アクション・インスタンスに割り当てられる表示名。
sVersionsScopeIDeValuePassingMode:ValuePassingModeコンテキスト値を渡すときに使用されるモード。モードは、
ValuePassingMode値(ALL、ANCHOR_DATA、NONE、CUSTOM)のいずれかです。aAnchorToColumns: ColumnKOViewModel[]このデータ・アクションのアンカー先の列。これはオプションです。指定しない場合、データ・アクションはすべての列で使用できます。
aContextColumns : ColumnKOViewModel[]このデータ・アクションが、その起動時にデータ・アクション・ターゲットに渡されるコンテキストに含める列。指定しない場合、マークされたすべての列がコンテキストに含まれます。
CanvasDataActionクラス
CanvasDataActionは、AbstractDataActionベース・クラスのサブクラスです。この具象クラスを拡張して、必要な機能を提供できます。
CanvasDataAction
CanvasDataActionクラスを使用して、ビジュアライゼーションのデータ・ポイントから別のキャンバスにナビゲートします。ナビゲート先のキャンバスは、同じプロジェクト内でも別のプロジェクト内でもかまいません。ソース・ビジュアライゼーションのすべてのアクティブ・フィルタは、データ・ポイント自体の修飾データ参照を説明する新しいフィルタとともにターゲット・キャンバスに渡されます。データ・アクションを別のキャンバスにナビゲートする必要がある場合、それはデータ・アクションで拡張する必要のあるクラスです。
+ CanvasDataAction(oKOModel)
+ create(s)ID_sName) : CanvasDataAction
+ upgrade(oOldDataActionJS) : Object
+ invoke(oActionContext: ActionContext, oDataActionContext:DataActionContext)
+ getGadgetInfos(oReport) : AbstractGadgetInfo[]
+ validate() : DataActionError# createProjectGadgetInfo(oReport) : AbstractGadgetInfo
# createCanvasGadgetInfo(oReport) : AbstractGadgetInfoEventDataActionクラス
EventDataActionは、AbstractDataActionベース・クラスのサブクラスです。この具象クラスを拡張して、必要な機能を提供できます。
EventDataAction
EventDataActionクラスを使用してクライアント側イベントを公開します。その後、そのイベントをリスニングして独自のアクションを実行する1つ以上のサブスクライバを登録できます。このタイプのデータ・アクションは、大量のコードがあって、データ・アクションの起動時に必要なアクションを実行するコードと疎結合されたデータ・アクション・コードを維持することでメリットを得ることのできる複雑なユースケースで使用してください。
+ EventDataAction(oKOModel)
+ create(sID_sName) : EventDataAction
+ upgrade(oOldDataActionJS) : Object
+ invoke(oActionContext: ActionContext, oDataActionContext:DataActionContext)
+ getGadgetInfos(oReport) : AbstractGadgetInfo[]
+ validate() : DataActionError# createEventGadgetInfo(oReport) : AbstractGadgetInfoAbstractHTTPDataActionクラス
AbstractHTTPDataActionは、URLNavigationDataActionおよびHTTPAPIDataActionサブクラスが共通機能とデフォルト動作を継承する抽象ベース・クラスです。
AbstractHTTPDataAction
AbstractHTTPDataAction抽象ベース・クラスは、URLNavigationDataActionクラスとHTTPAPIDataActionクラスの両方で共有されます。データ・アクションでWebページを新しいブラウザ・タブで開く場合、URLNavigationDataActionを拡張する必要があります。データ・アクションでHTTP APIを起動する場合、HTTPAPIDataActionを拡張する必要があります。状況によっては、AbstractHTTPDataActionを直接拡張することも可能です。
+ HTTPDataAction(oKOModel)+ validate() : DataActionError# createURLGadgetInfo(oReport) : AbstractGadgetInfoURLNavigationDataActionクラス
URLNavigationDataActionは、AbstractHTTPDataActionベース・クラスのサブクラスです。
URLNavigationDataAction
URLNavigationDataActionクラスを使用して、特定のURLを新しいブラウザ・タブで開きます。データ・アクションの起動時にユーザーが選択したデータ・ポイントから導出される値に置き換えられるトークンを使用して、URLを構成します。データ・ポイント値は、データ・アクション・コンテキストの一部として外部Webページに渡されます。たとえば、Oracle Sales Cloudなどのカスタマ・リレーションシップ・マネジメント・アプリケーションで顧客のWebページが表示されるように、CustomerID列を使用して起動されるデータ・アクションを作成します。
+ URLNavigationDataAction(oKOModel)+ create(sID_sName) : URLNavigationDataAction
+ upgrade(oOldDataActionJS) : Object+ invoke(oActionContext: ActionContext, oDataActionContext:DataActionContext)
+ getGadgetInfos(oReport) : AbstractGadgetInfo[]HTTPAPIDataActionクラス
HTTPAPIDataActionは、AbstractHTTPDataActionベース・クラスのサブクラスです。この具象クラスを拡張して、必要な機能を提供できます。
HTTPAPIDataAction
HTTPAPIDataActionクラスを使用し、非同期XMLHTTPRequest (XHR)を作成してそれを指定したURLに送信することで、HTTP APIを起動します。HTTPレスポンス・コードによって、キャンバスにメッセージが簡潔に表示されます。たとえば、JSONまたはXMLペイロードをRESTまたはSOAPサーバーに送信するようにリクエストをカスタマイズしたり、カスタム・ユーザー・インタフェースを表示するようにレスポンス・ハンドラをカスタマイズできます。
HTTPAPIDataActionデータ・アクションを動作させるには、アクセスするHTTP APIのURLを「安全ドメイン」のリストに追加し、「接続」アクセス権を付与する必要があります。安全なドメインの登録を参照してください。
+ HTTPAPIDataAction(oKOModel)+ create(sID_sName) : HTTPAPIDataAction
+ upgrade(oOldDataActionJS) : Object+ invoke(oActionContext: ActionContext, oDataActionContext:DataActionContext)
+ getGadgetInfos(oReport) : AbstractGadgetInfo[]# createHTTPMethodGadgetInfo(oReport) : AbstractGadgetInfo
# createPostParamGadgetInfo(oReport) : AbstractGadgetInfoテンプレートからのデータ・アクション・プラグインの生成
一連のコマンドを使用して開発環境を生成し、カスタム・データ・アクション・プラグインを作成するために必要なフォルダとファイル付きでHTTP APIデータ・アクションを移入します。
プラグイン・ファイルはすべて、同じ基本構造に従います。ファイルとフォルダを手動で作成することも、それらをテンプレートから生成することもできます。これを行うツールは、Oracle Analytics Desktopに付属しているOracle Analytics Desktopソフトウェア開発キット(SDK)に含まれています。Oracle Analytics Desktop SDKのリファレンスを参照してください。
Oracle Analytics Desktopバージョン5.4以上を使用して、カスタム・データ・アクション・プラグインを作成するために必要なクラスにアクセスします。
次のコマンドを使用して開発環境を生成し、それにHTTP APIデータ・アクションを移入します。
生成されたフォルダとファイル
新しく生成されたデータ・アクション開発環境には、次のフォルダとファイルが含まれます:
1 %PLUGIN_DEV_DIR%\src\customdataaction
2 company-mydataaction\
3 extensions\
4 oracle.bi.tech.plugin.dataaction\
5 company.mydataaction.json
6 nls\
7 root\
8 messages.js
9 messages.js
10 mydataaction.js
11 mydataactionstyles.css
12 plugin.xml- 行2:
company-mydataactionフォルダは、指定したIDです。 - 行6:
nlsフォルダには、プラグインでネイティブ言語サポートを提供できるようにする外部化文字列のファイルが含まれます。 - 行7:
nls\rootフォルダ以下のファイルの文字列は、リクエストされた言語の翻訳が使用できない場合に使用されるデフォルト文字列です。 - 行8:
messages.jsファイルには、追加可能なプラグイン用の外部化文字列が含まれます。 - 行9:
messages.jsファイルには、ローカライズされた文字列を提供する追加言語ごとに追加したエントリが含まれる必要があります。翻訳を追加する各ロケールのnlsフォルダ以下に、対応するフォルダを追加する必要があります。各フォルダには、nls\rootフォルダ以下に追加されたファイルと同じファイル名で、同じファイル・セットが含まれる必要があります。 - 行10:
mydataaction.jsファイルは、カスタム・データ・アクションを開発するための開始ポイントを提供する、新しく生成されたJavaScriptモジュール・テンプレートです。 - 行11:
mydataactionstyles.cssファイルには、追加する予定があり、データ・アクションのユーザー・インタフェースで使用できる任意のCSSスタイルを含めることができます。 - 行12:
plugin.xmlファイルは、プラグインとそのファイルをOracle Analyticsに登録します。
データ・アクション・ベース・クラスの拡張
拡張するデータ・アクションのサブクラスを選択し、必要なフォルダとファイルを生成したら、新しいデータ・アクションに固有のコードの記述を開始できます。
新しく生成されたデータ・アクション・コードは、%PLUGIN_DEV_DIR%\src\dataaction以下にあります。ファイルおよびフォルダ構造の説明は、「生成されたフォルダとファイル」を参照してください。編集する必要のあるメイン・ファイルは、JavaScriptファイルです。たとえば、カスタム・データ・アクションIDがcompany.MyDataactionである場合、検索するファイルは%PLUGIN_DEV_DIR%\src\dataaction\company-mydataaction\mydataaction.jsです。
格納する必要のある追加プロパティがデータ・アクションに含まれる場合、それらを監視可能プロパティとしてKnockoutモデルに追加する必要があります。データ・アクションのIDがcompany.MyDataactionである場合、Knockoutモデルはmydataaction.MyDataActionKOModelと呼ばれ、mydataaction.jsの最上位付近にあります。デフォルトで、このKnockoutモデルはデータ・アクションのスーパークラスで使用されるKnockoutモデルを拡張するように構成されるため、モデルに追加プロパティを追加するだけで済みます。
HTTPAPIDataActionベース・クラスを拡張しているデータ・アクションでは、次のようなコードを使用します:
1 - mydataaction.MydataactionKOModel = function (sClass, sID, sName, sVersion, sScopeID, aAnchorToColumns, eValuePassingMode, sURL,
eHTTPMethod, sPOSTParams)
2 - {
3 - mydataaction.MydataactionKOModel.baseConstructor.call(this, sClass, sID, sName, sVersion, sScopeID, aAnchorToColumns, eValuePassingMode, sURL, eHTTPMethod, sPOSTParams);
4 - };
5 - jsx.extend(mydataaction.MydataactionKOModel, dataaction.HTTPAPIDataActionKOModel);- 行1: これは、Knockoutモデルのコンストラクタです。モデルが格納する必要のあるプロパティを受け入れます。
- 行3: これは、スーパークラスのコンストラクタであり、Knockoutモデルのスーパークラスのいずれかによって処理されるすべてのプロパティに対する値の受渡し先となる
baseConstructorでもあります。 - 行5: これは、このKnockoutモデル・クラスのスーパークラスを設定します。
次のようなコードを使用して文字列と配列を追加し、データ・アクションによって永続化されるプロパティを設定します。
1 mydataaction.MydataactionKOModel = function (sClass, sID, sName, sVersion, sScopeID, aAnchorToColumns, eValuePassingMode, sURL, eHTTPMethod, sPOSTParams)
2 {
3 mydataaction.MydataactionKOModel.baseConstructor.call(this, sClass, sID, sName, sVersion, sScopeID, aAnchorToColumns, eValuePassingMode, sURL, eHTTPMethod, sPOSTParams);
4
5
6 // Set Defaults
7 sMyString = sMyString || "My default string value";
8 aMyArray = aMyArray || [];
9
10
11 // Asserts
12 jsx.assertString(sMyString, "sMyString");
13 jsx.assertArray(aMyArray, "aMyArray");
14
15
16 // Add observable properties
17 this.sMyString = ko.observable(sMyString);
18 this.aMyArray = ko.observableArray(aMyArray);
19 };
20 jsx.extend(mydataaction.MydataactionKOModel, dataaction.HTTPAPIDataActionKOModel);オーバーライドするデータ・アクションの継承メソッドの選択
各データ・アクションは、適切に動作するために様々なメソッドを実装する必要があるため、変更して使用できる動作を実装しているメソッドをオーバーライドすることになります。
汎用メソッド
HTTPAPIDataActionなどの具象データ・アクション・クラスのいずれかを拡張する場合、必要なメソッドのほとんどはすでに実装されており、変更して使用できる動作を実装しているメソッドをオーバーライドするだけで済みます。
この項では、様々なメソッドとその予期される動作について説明します。
すべてのタイプのデータ・アクションは、ここで説明されているメソッドを実装する必要があります。
create(sID, sName)
create()静的メソッドは、新しいデータ・アクションを作成してドロップダウン・メニューからデータ・アクション・タイプを選択したときにコールされます。このメソッドの役割は次のとおりです:
- データ・アクションで使用するKnockoutモデル・クラスの構築。
Knockoutモデル・クラスには、他のすべてのプロパティにとって意味のあるデフォルト値とともに
create()メソッドに渡されるIDと名前が含まれる必要があります。たとえば、通貨換算データ・アクションでは、ドルに換算するデフォルト通貨を設定できます。Knockoutモデルは、デフォルト値を提供するための適切な場所です。 - Knockoutモデルからのデータ・アクションのインスタンスの構築。
- データ・アクションのインスタンスの返却。
invoke(oActionContext, oDataActionContext)
invoke()メソッドは、ビジュアライゼーションのデータ・ポイントのコンテキスト・メニューからユーザーがデータ・アクションを起動したときにコールされます。このメソッドは、選択されたデータ・ポイント、ビジュアライゼーション、フィルタ、プロジェクトおよびセッションを記述したメタデータを含むDataActionContext引数を渡します。「データ・アクション・サービス・クラス」を参照してください。
validate()
validate()メソッドは、「データ・アクション」ダイアログでユーザーが「OK」をクリックしたときに各データ・アクションでコールされます。validate()メソッドは、すべてが有効であることを示す場合はnullを返し、何かが無効である場合はDataActionErrorを返します。ダイアログでいずれかのデータ・アクションにエラーが発生した場合、ダイアログは閉じられず、ユーザーにエラー・メッセージが表示されます。このメソッドは、this.validateName()メソッドを使用してデータ・アクションの名前を検証します。
getGadgetInfos(oReport)
getGadgetInfos()メソッドは、ユーザー・インタフェースでデータ・アクション・プロパティ・フィールドを表示できるようにするためにコールされます。このメソッドは、ユーザーが希望するユーザー・インタフェースへの表示順序でGadgetInfosの配列を返します。ガジェットは、最も一般的なタイプのすべてのフィールドに対して提供されますが(たとえば、テキスト、ドロップダウン、パスワード、複数選択、ラジオ・ボタン、チェック・ボックスなど)、より複雑なフィールドが必要な場合はカスタム・ガジェットを作成できます(たとえば、複数のガジェットをまとめてグループ化する場合や、ユーザーの選択したオプションに応じて異なるガジェット・フィールドを表示する場合など)。配列で必要な各GadgetInfoを構築するメソッドを作成する方が、後でサブクラスがその提供されたGadgetInfoから選択しやすくなるため、ベスト・プラクティスです。このベスト・プラクティスに従う場合、ユーザー・インタフェースで使用されるフィールドごとにGadgetInfoを返すことができる各種データ・アクション・ベース・クラスによって実装された様々なメソッドがすでに用意されています。また、これらのGadgetInfoのいずれかが必要な場合、対応するcreate****GadgetInfo()メソッドをコールして、その戻り値をガジェットの配列に配置します。
isAllowedHere(oReport)
isAllowedHere()メソッドは、ユーザーがビジュアライゼーションのデータ・ポイントを右クリックし、ユーザー・インタフェースがコンテキスト・メニューの生成を開始したときにコールされます。選択されたデータ・ポイントに関連するデータ・アクションが存在する場合、メソッドはtrueを返し、そのデータ・アクションがコンテキスト・メニューに表示されます。メソッドがfalseを返した場合、データ・アクションはコンテキスト・メニューに表示されません。スーパークラスから継承したデフォルト動作を受け入れることを検討してください。
upgrade(oOldDataActionJS)
最初のデータ・アクションを作成する場合、upgrade(oOldDataActionJS)メソッドを使用しないでください。このメソッドは、最初のKnockoutモデルの作成後に、第2バージョンのKnockoutモデルのプロパティを大幅に変更する場合にのみ使用してください。たとえば、最初のバージョンのデータ・アクションではそのKnockoutモデルにURLを格納するが、次のバージョンでは別個のプロパティにURLコンポーネント部分を格納する予定の場合です(たとえば、protocol、hostname、port、path、queryString、bookmarkなど)。
第2バージョンのKnockoutモデル・コードは、問題が発生する可能性のある最初のバージョンのKnockoutモデル・コードに保存されているデータ・アクションを開こうとする場合があります。この問題を解決するため、システムでは、現在のデータ・アクション・コードのバージョンが、開かれようとしているデータ・アクションのバージョンより新しいことを認識すると、新しいデータ・アクション・クラスのupgrade()メソッドをコールして、古いデータ・アクションのKnockoutモデル(JSONオブジェクトにシリアライズ済)を渡します。その後、古いJSONオブジェクトを使用して新しいKnockoutモデルに移入し、JSONオブジェクトのアップグレード・バージョンを返すことができます。これにより、データ・アクション・コードを改善しても、古いデータ・アクション・メタデータは動作し続けることが保証されます。
HTTPAPIDataActionメソッド
HTTPAPIDataActionクラスを拡張する場合、オーバーライドできる次の追加メソッドが用意されています:
getAJAXOptions(oDataActionContext)
getAJAXOptions()メソッドは、データ・アクションのinvoke()メソッドによってコールされます。getAJAXOptions()メソッドは、データ・アクションで作成されるHTTPリクエストを記述したAJAX Optionsオブジェクトを作成します。getAJAXOptions()メソッドには、選択されたデータ・ポイント、ビジュアライゼーション、フィルタ、プロジェクトおよびセッションを記述したメタデータを含むoDataActionContextオブジェクトが渡されます。統合しようとしているHTTP APIの要件どおりにAJAX Optionsを設定し、HTTPRequestが成功するかエラーで終了した場合にコールする関数を指定します。jQuery.ajaxオブジェクトとそのプロパティの説明は、JQueryのWebサイトを参照してください。
次の実装は、HTTPAPIDataActionクラスから継承されています。継承メソッドをリライトして要件を指定する必要があります。たとえば、HTTPリクエストと、HTTPレスポンスを処理するコードを構成します。この実装は、getAJAXOptions()関数に渡されるパラメータ、返されることが予期されるオブジェクト、およびメソッド内でコードを構成する方法の明確な例を示しているため、役に立ちます。
1 /**
2 * This method returns an object containing the AJAX settings used when the data action is invoked.
3 * Subclasses may wish to override this method to provide their own behavior.
4 * @param {module:obitech-reportservices/dataactionmanager.DataActionContext} oDataActionContext The context metadata describing where the data action was invoked from.
5 * @returns {?object} A JQuery AJAX settings object (see http://api.jquery.com/jQuery.ajax/ for details) - returns null if there is a problem.
6 */
7 dataaction.HTTPAPIDataAction.prototype.getAJAXOptions = function (oDataActionContext)
8 {
9 jsx.assertInstanceOfModule(oDataActionContext, "oDataActionContext", "obitech-reportservices/dataactionmanager", "DataActionContext");
10
11 var oAJAXOptions = null;
12 var oKOViewModel = this.getKOViewModel();
13 var sURL = oKOViewModel.sURL();
14 if (sURL)
15 {
16 // Parse the URL
17 var sResultURL = this._parseURL(sURL, oDataActionContext);
18 if (sResultURL)
19 {
20 // Parse the POST parameters (if required)
21 var eHTTPMethod = oKOViewModel.eHTTPMethod()[0];
22 var sData = null;
23 if (eHTTPMethod === dataaction.HTTPDataActionKOModel.HTTPMethod.POST)
24 {
25 var sPOSTParams = oKOViewModel.sPOSTParams();
26 sData = sPOSTParams.replace(dataaction.AbstractHTTPDataAction.RegularExpressions.LINE_END, "&");
27 sData = this._parseURL(sData, oDataActionContext, false);
28 }
29 oAJAXOptions = {
30 type: eHTTPMethod,
31 url: sResultURL,
32 async: true,
33 cache: false,
34 success: function (/*oData, sTextStatus, oJQXHR*/)
35 {
36 oDataActionContext.getReport().displaySuccessMessage(messages.HTTP_API_DATA_ACTION_INVOCATION_SUCCESSFUL.format(oKOViewModel.sName()));
37 },
38 error: function (oJQXHR/*, sTextStatus, sError*/)
39 {
40 oDataActionContext.getReport().displayErrorMessage(messages.HTTP_API_DATA_ACTION_INVOCATION_FAILED.format(oKOViewModel.sName(), oJQXHR.statusText, oJQXHR.status));
41 }
42 };
43 if (sData)
44 {
45 oAJAXOptions.data = sData;
46 }
47 }
48 }
49 return oAJAXOptions;
50 };Knockoutモデル変更のためのアップグレード・ハンドラの使用
一部のKnockoutモデル変更では、アップグレード・ハンドラを使用してデータ・アクション・プラグインをアップグレードする必要があります。
Knockoutモデルを変更せずにデータ・アクション・プラグインを改善する場合、通常どおりJavaScriptまたはCSSファイルを編集し、新しいZIPファイルを作成して、既存のデータ・アクション・プラグインを新しいZIPファイルに置き換えます。ただし、データ・アクションのKnockoutモデルを変更した場合、データ・アクションのVERSIONプロパティを変更してアップグレード・ハンドラを指定する必要があります。
アップグレード・ハンドラを使用する必要があるかどうかを決定します:
- Knockoutモデルのプロパティ名を変更する場合。
- Knockoutモデルの複数のプロパティを単一のプロパティに結合する場合。
- Knockoutモデルの単一のプロパティを複数のプロパティに分割する場合。
- Knockoutモデルに新しいプロパティを追加する際に、その正しいデフォルト値がKnockoutモデルの他の値に依存する場合。
- Knockoutモデルに新しいプロパティを追加する際に、データ・アクションのすべての既存の使用方法に対して正しいデフォルト値を指定できる場合。
- データ・アクション・コードで使用しなくなったためにKnockoutモデルからプロパティを除去する場合。
データ・アクション・プラグインのアップグレード
データ・アクション・プラグインをアップグレードしてデータ・アクション・コードを改善するか、メタデータをアップグレードして既存のデータ・アクションで新しいデータ・アクション・コードを操作できるようにします。
データ・アクション・プラグイン・ファイルのリファレンス
データ・アクション・プラグインごとに1つのplugin.xmlファイルが必要で、各plugin.xmlファイルには任意の数のデータ・アクションを含めることができます。
データ・アクションplugin.xmlファイルの例
plugin.xmlファイルには、tns:obiplugin、tns:resourcesおよびtns:extensionという3つのメイン・セクションがあります。
plugin.xmlの例
この例は、1つのデータ・アクションに対する一般的なplugin.xmlファイルを示しています。
1 <?xml version="1.0" encoding="UTF-8"?>
2 <tns:obiplugin xmlns:tns="http://plugin.frameworks.tech.bi.oracle"
3 id="obitech-currencyconversion"
4 name="Oracle BI Currency Conversion"
5 version="0.1.0.@qualifier@"
6 optimizable="true"
7 optimized="false">
8
9
10 <tns:resources>
11 <tns:resource id="currencyconversion" path="scripts/currencyconversion.js" type="script" optimizedGroup="base"/>
12 <tns:resource-folder id="nls" path="resources/nls" optimizable="true">
13 <tns:extensions>
14 <tns:extension name="js" resource-type="script"/>
15 </tns:extensions>
16 </tns:resource-folder>
17 </tns:resources>
18
19
20 <tns:extensions>
21 <tns:extension id="oracle.bi.tech.currencyconversiondataaction" point-id="oracle.bi.tech.plugin.dataaction" version="1.0.0">
22 <tns:configuration>
23 {
24 "host": { "module": "obitech-currencyconversion/currencyconversion" },
25 "resourceBundle": "obitech-currencyconversion/nls/messages",
26 "properties":
27 {
28 "className": "obitech-currencyconversion/currencyconversion.CurrencyConversionDataAction",
29 "displayName": { "key" : "CURRENCY_CONVERSION", "default" : "Currency Conversion" },
30 "order": 100
31 }
32 }
33 </tns:configuration>
34 </tns:extension>
35 </tns:extensions>
36
37 </tns:obiplugin>データ・アクションplugin.xmlファイルのプロパティ・セクション - tns:obiplugin
tns:obipluginセクションでは、すべてのタイプのプラグインに共通のプロパティを定義します。
プラグインのプロパティ
tns:obipluginセクションでは、すべてのタイプのプラグインに共通のプロパティを定義します。
1 <?xml version="1.0" encoding="UTF-8"?>
2 <tns:obiplugin xmlns:tns="http://plugin.frameworks.tech.bi.oracle"
3 id="obitech-currencyconversion"
4 name="Oracle BI Currency Conversion"
5 version="0.1.0.@qualifier@"
6 optimizable="true"
7 optimized="false">- 行1: XML宣言。
- 行2: プラグインのルートXMLElementの開始タグと、plugin.xmlファイル全体で使用される
tnsネームスペースの宣言。 - 行3: プラグインの一意のID。
- 行4: プラグインのデフォルトの表示名(ローカライズされたバージョンが使用できない場合に使用されます)。
- 行5: プラグインのバージョン番号。
- 行6: JS/CSSが最適化(圧縮)可能であるかどうかを示すブール。
- 行7: JS/CSSが最適化(圧縮)済であるかどうかを示すブール。
データ・アクションplugin.xmlファイルのリソース・セクション - tns:resources
tns:resourcesセクションでは、プラグインに提供するファイルをすべて登録します。
リソース
1 <tns:resources>
2 <tns:resource id="currencyconversion" path="scripts/currencyconversion.js" type="script" optimizedGroup="base"/>
3 <tns:resource-folder id="nls" path="resources/nls" optimizable="true">
4 <tns:extensions>
5 <tns:extension name="js" resource-type="script"/>
6 </tns:extensions>
7 </tns:resource-folder>
8 </tns:resources>各JavaScript、CSS、イメージおよび翻訳リソース・ファイルをここで登録する必要があります。このセクションは、<tns:resources>要素内に含まれ、次の要素を任意の数だけ含みます:
<tns:resource>これらの要素は、単一のファイルを登録するために使用します(たとえば、JavaScriptまたはCSSファイル)。
<tns:resource-folder>これらの要素は、指定したフォルダ内のすべてのファイルを同時に登録するために使用します。たとえば、イメージ・フォルダまたはネイティブ言語サポートのリソース・ファイルを含むフォルダです。
各タイプのファイルを登録する方法の詳細は、次の各項を参照してください。
JavaScriptファイル
プラグインの各JavaScriptファイルは、次に示すような行に登録する必要があります。
<tns:resource id="currencyconversion" path="scripts/currencyconversion.js" type="script" optimizedGroup="base"/>説明:
- idは、ファイルに割り当てられるIDです。
IDは、JavaScriptファイル名(.js拡張子なし)に一致するよう設定します。
- pathは、plugin.xmlファイルからJavaScriptファイルへの相対パスです。JavaScriptファイルは、プラグインの
scriptsディレクトリに格納する必要があります。JavaScriptファイルには、アンダースコアやハイフンなどの特殊文字なしで、すべて小文字を使用してください。
- typeは、登録するファイルのタイプです。JavaScriptファイルの場合、これは
scriptに設定する必要があります。 - optimizedGroupは、複数のJavaScriptファイルを1つの圧縮ファイルにグループ化します。サード・パーティ・プラグインでは、この設定を
baseのままにする必要があります。
CSSファイル
プラグインの各CSSファイルは、次に示すような行に登録する必要があります。
<tns:resource id="currencyconversionstyles" path="resources/currencyconversion.css" type="css"/>説明:
- idは、ファイルに割り当てられるIDです。
IDは、CSSファイル名(.css拡張子なし)に一致するよう設定します。
- pathは、plugin.xmlファイルからCSSファイルへの相対パスです。CSSファイルは、プラグインの
resourcesディレクトリに格納する必要があります。CSSファイルには、アンダースコアやハイフンなどの特殊文字なしで、すべて小文字を使用してください。
- typeは、登録するファイルのタイプです。CSSファイルの場合、これは常に
cssに設定する必要があります。
イメージ・フォルダ
JavaScriptコード内から参照するために必要なイメージがプラグインに含まれる場合、プラグインのディレクトリ構造内のresources/imagesディレクトリにそれらを配置し、次のように<tns:resource-folder>要素をplugin.xmlに追加します:
<tns:resource-folder id="images" path="resources/images" optimizable="false"/> イメージがCSSファイルからのみ参照される場合、この<tns:resource-folder>要素をplugin.xmlファイルに追加する必要はありません。この場合は、resources/imagesディレクトリにそれらを追加して、CSSファイルからの相対パスを使用して参照できるようにする必要があります。
ネイティブ言語サポートのリソース・フォルダ
Oracle Analyticsは、ネイティブ言語サポートを実装しています。そのため、開発者は、ユーザー・インタフェースに表示する文字列を、個別のJSONリソース・ファイルに外部化する必要があります。その後、所定のディレクトリ構造でこれらのファイルの様々なローカライズ・バージョンを提供することができ、Oracle Analyticsでは、ユーザーの選択した言語に対して適切なファイルが自動的に使用されます。リソース・ファイルの翻訳バージョンは、必要な数だけ提供できます。ネイティブ言語サポートのリソース・フォルダにより、Oracle Analyticsはプラグインで使用される所定のネイティブ言語サポート・ディレクトリ構造のルートを指します。ネイティブ言語サポートのリソース・ファイルを使用するすべてのプラグインには、次の例とまったく同じ<tns:resource-folder>エントリが含まれる必要があります。
1 <tns:resource-folder id="nls" path="resources/nls" optimizable="true">
2 <tns:extensions>
3 <tns:extension name="js" resource-type="script"/>
4 </tns:extensions>
5 </tns:resource-folder>ファイルの内容および準拠する必要のある所定のディレクトリ構造の詳細は、「生成されたフォルダとファイル」を参照してください。
データ・アクションplugin.xmlファイルの拡張機能セクション - tns:extension
プラグインで提供するデータ・アクションごとに、次のような<tns:extension>要素を使用してデータ・アクションの拡張機能を登録する必要があります:
<tns:extension id="oracle.bi.tech.currencyconversiondataaction" point-id="oracle.bi.tech.plugin.dataaction" version="1.0.0">
<tns:configuration>
{
"host": { "module": "obitech-currencyconversion/currencyconversion" },
"resourceBundle": "obitech-currencyconversion/nls/messages",
"properties":
{
"className": "obitech-currencyconversion/currencyconversion.CurrencyConversionDataAction",
"displayName": { "key" : "CURRENCY_CONVERSION", "default" : "Currency Conversion" },
"order": 100
}
}
</tns:configuration>
</tns:extension>説明:
- idは、データ・アクションに割り当てる一意のIDです。
- point-idは、登録する拡張機能のタイプです。データ・アクションの拡張機能では、これを
oracle.bi.tech.plugin.dataactionに設定する必要があります。 - versionは、拡張機能定義で使用する拡張機能のAPIバージョンです(この設定は1.0.0のままにします)。
<tns:configuration>要素には、次を定義するJSON文字列が含まれます:
- host.module - これは、データ・アクションが含まれるモジュールの完全修飾名です。この完全修飾モジュール名は、
%PluginID%/%ModuleName%という書式で示されます。ここで:%PluginID%は、<tns:obiplugin>要素のid属性で指定したプラグインIDに置き換える必要があります。%ModuleName%は、データ・アクションが含まれるJavaScriptファイルの<tns:resource>要素のid属性で指定したリソースIDに置き換える必要があります。
- resourceBundle - これは、このデータ・アクションのローカライズされたリソースが含まれるリソース・ファイルへのネイティブ言語サポート・パスです。リソース・ファイルがmessages.jsという名前で所定の
nlsディレクトリ構造に正しく格納されている場合、このプロパティを%PluginID%/nls/messagesに設定します(ここで、%PluginID%は、plugin.xmlファイルの先頭にある<tns:obiplugin>要素のid属性で指定したプラグインIDに置き換える必要があります)。 - properties.className - これは、登録するデータ・アクションに割り当てられる完全修飾クラス名です。この完全修飾クラス名は、
%PluginID%/%ModuleName%.%ClassName%という書式で示されます。ここで:%PluginID%は、<tns:obiplugin>要素のid属性で指定したプラグインIDに置き換える必要があります。%ModuleName%は、データ・アクションが含まれるJavaScriptファイルの<tns:resource>要素のid属性で指定したリソースIDに置き換える必要があります。%ClassName%は、JavaScriptファイルでデータ・アクション・クラスに割り当てた名前に置き換える必要があります。
- properties.displayName - このプロパティには、1つのオブジェクトと2つの追加プロパティが含まれます:
- keyは、指定された
resourceBundle内からデータ・アクションのローカライズされた表示名を検索するために使用できるネイティブ言語サポートのメッセージ・キーです。 - defaultは、なんらかの理由でローカライズされたバージョンの表示名を検出できない場合に使用されるデフォルトの表示名です。
- keyは、指定された
- properties.order - このプロパティによって、データ・アクションのリストが表示されるときに、データ・アクションの表示位置を決定するためのヒントを提供できます。orderプロパティで小さい数値を持つデータ・アクションは、大きい数値を持つデータ・アクションより前に表示されます。同じ数値の場合、データ・アクションは、システムにロードされた順序で表示されます。