この章では、他のアプリケーションで生成されたコンテンツをBI Publisherレポートに統合する目的で、カスタム・プラグインを使用してレイアウト・エディタの機能を拡張する方法について説明します。カスタム・コンテンツは、インタラクティブ・ビューアで表示できます。
この章では、次の項目について説明します。
BI Publisherでは、レポートにカスタム・コンポーネントを追加する目的で、JavaScriptプラグインの拡張機能のレイアウト・エディタへの追加がサポートされます。カスタム・コンポーネントは、インタラクティブ・モードでレポートを表示する場合、レポートに含まれます。設計時にプラグインをレイアウト・エディタに追加すると、そのプラグインに定義したアイコンが、レイアウト・エディタの「挿入」メニューに表示されます。次に、レイアウト・エディタでの他のコンポーネントと同様に、カスタム・コンポーネントをレポート・レイアウトにドラッグ・アンド・ドロップできます。
この機能を使用して、テキスト、イメージ、映像、データ駆動コンポーネントなどの静的コンポーネントをレポートに挿入します。
この機能では、プラグインに関するカスタム・プロパティの定義もサポートされるため、レポート設計者は、作成したコンポーネント・プラグインに固有のプロパティを追加できます。
プラグインを実装するには、次のようにします。
第11.3項「カスタム・プラグインのコード化」で説明するガイドラインを使用して、JavaScriptプラグインをコード化します。
<BI Publisher repository>\Admin\Plugins
にJavaScript(.js)ファイルを置きます。
レイアウト・エディタをリロードします。プラグインがレイアウト・エディタの「挿入」メニューに表示されます。
この項では、プラグイン構造の仕様を示し、プラグインで使用するために提供されるAPIについて説明します。内容は次のとおりです。
プラグイン・モジュール・ファイルは簡単なJavaScriptファイルです。プラグインを有効にするには、プラグイン定義オブジェクトを指定して単一の関数を呼び出します。
プラグイン定義JavaScriptオブジェクトには次のフィールドがあります。
id
は識別文字列です。名前の競合を回避するには、逆のドメイン名を使用することをお薦めします(例: com.example.helloworld)。
component
オブジェクトは次のフィールドで構成されます。
コンポーネントの名前。例: "Hello World"
アイコンは、レイアウト・エディタの「挿入」メニューに表示されるイメージで、プラグインを表します。このフィールドは、アイコン・イメージを指し示すURLを取ります。例: "http://www.example.com/img/smile.gif"
アイコン・イメージについて表示するツールチップ・メッセージ。例: "Hello World Plugin"
(オプション)クリック・イベント定義オブジェクトの配列。
(文字列)イベントの識別。例: "filter"または"showselection"
trueとfalseのフラグ。trueに設定する場合、コンポーネントに対するクリック・アクションによって、それ以外のコンポーネントのフィルタ処理がトリガーされます。
trueとfalseのフラグ。trueに設定する場合、プラグイン・コンポーネントはクリック・イベントを受け取ります。
(オプション)プラグイン・コンポーネントを識別するコンポーネントのCSSクラス・セレクタ。
render関数では、プラグイン・コンテンツがレンダリングされます。render関数は、次のパラメータを渡します。
次の情報を含むオブジェクト
id
は、割り当てられるインスタンス化済コンポーネントのID文字列です。システムにより、このIDが同じテンプレート内で一意であることが保証されます。プラグイン・コードが生成するHTML要素に、このIDを接頭辞または接尾辞として使用することをお薦めします。この実施により、IDの競合が避けられます。
テンプレートに割り当てられるロケール。
コンテナのHTML要素。コンテンツをこの要素に設定する必要があります。
データ行の配列。各項目には、列に対する別の配列が含まれます。
割り当てられるxmlパス。
現在のプロパティ。第11.4項「プロパティのサポート」を参照してください。
カスタム・プラグインでは、次のJavaScript APIを使用できます。
クリック(選択)したフィールド情報を取得してシステムに送信します。
長さ文字列値からピクセル値を返します。システムでは、ほとんどのブラウザと同じ96dpiが使用されます。
このメソッドは、クリック(選択)したフィールド情報を取得してシステムに送信します。
xdo.api.handleClickEvent(info)
このメソッドは次のパラメータを取ります。
クリックしたフィールド情報オブジェクト。
オブジェクトの構造は次のようになります。
Object Structure { id: [component id], [ { field: [xpath to the element], value: [filter value] }, { field: [xpath to the element], value: [filter value] }, ]
このメソッドは、長さ文字列値からピクセル値を返します。システムでは、ほとんどのブラウザと同じ96dpiが使用されます。
xdo.api.getPixelValue(lengthString)
メソッドは1つのパラメータを取ります。
長さを指定する文字列値。サポートされる単位は、「px」、「pt」、「in」および「cm」です。
カスタム・プロパティを追加するには、propertiesフィールドを使用できます。プロパティ定義オブジェクトの配列をこのフィールドに設定できます。プロパティ定義オブジェクトを次の値から作成します。
プロパティ・キーを指定する文字列値。この値は一意である必要があります。
レイアウト・エディタの「プロパティ」ペインで該当プロパティに表示されるラベルを指定する文字列値。
プロパティ・タイプを指定する文字列値。レイアウト・エディタでは、この値を使用して、プロパティを編集する適切なエディタを開きます。typeでは次の値がサポートされています。
string - 文字列データを入力するテキスト・エントリ・ボックスを作成します。
number - 数値データを入力するテキスト・エントリ・ボックスを作成します。
bool - TrueまたはFalse(ブール型)の選択オプションを作成します。
length - 長さデータを入力して単位をpx、in、cmまたはptで選択するテキスト・エントリ・ボックスを作成します。
color - 色を選択する色選択用ダイアログを表示します。
font - 選択するサポート対象フォントのリストを表示します。
fontsize - サイズ選択用ダイアログを表示します。
lov - 値のリストを作成します。名前と値のペアの作成については、「options」を参照してください。
プロパティの初期値。値は、指定されたタイプの形式に従う必要があります。
このパラメータは、プロパティtypeが「lov」の場合のみ有効です。optionsパラメータには、値のリストを定義するラベルと値のペアが含まれます。
label - 各リスト項目のラベル
value - ラベルの値
次に、プラグインの例を示します。
この例では、最も簡単なタイプのプラグインを実装する方法を示します。このプラグインは、選択するとレイアウトの挿入ポイントに企業ロゴを挿入するアイコンを、レイアウト・エディタのツールバーに追加します。このプラグインのJavasSriptファイルでは、単一オブジェクトですべての内容が定義されます。
プラグインのJavaScriptを作成します。
この例のプラグイン定義は次のようになります。
{ id: "com.oracle.xdo.logo", component: { name: "Logo", icon: "http://localhost:7001/xmlpserver/logo_icon.gif", tooltip: "Oracle Logo Plugin" }, render: function(context, containerElem, rows, fields, props) { containerElem.innerHTML = '<img src="http://localhost:7001/xmlpserver/oracle.gif" />'; } }
ファイルを拡張子「.js」で保存し、<REPOSITORY ROOT>/Admin/Plugins
ディレクトリ下にこのファイルを置きます。
レイアウト・エディタ・アプリケーションをリロードします。ロゴ・プラグインがリボンに表示されます。
「Oracle」アイコンをクリックするか、項目をドラッグ・アンド・ドロップして、レイアウトにロゴを挿入します。図11-1を参照してください。
図11-2に示すように、挿入したプラグイン・コンポーネントが選択された状態で、「プロパティ」ペインをクリックして、デフォルトのプロパティを表示または編集します。
この例では、ユーザーがYouTubeの映像をBI Publisherレポートに埋め込むことができるプラグインを作成します。インタラクティブ出力として表示する場合、埋込みコントロールを使用してYouTube映像を表示できます。
1. プラグインのIDとコンポーネントの機能を定義します。
YouTubeでは、サードパーティによる埋込みが容易になるように、その各映像ページで簡単なHTMLコードが提供されます。このコードは、YouTubeの映像ページに表示される「共有」ボタンと「埋め込み」ボタンを順にクリックすると公開されます。このコードの例は次のようになります。
<iframe width="425" height="349" src="http://www.youtube.com/embed/TK7KYaCEGZU" frameborder="0" allowfullscreen></iframe>
映像を埋め込む場合、iframeでは、幅、高さ、映像の識別子(この例では「videoid」と呼ばれる)が必要です。これらをプロパティとしてプラグインで定義します。幅と高さはすでにデフォルト値になっていますが、ここでデフォルト値を上書きするように定義できます。YouTube映像のベースURLは一定のため、videoidをプロパティとして定義すると、予測した結果が作成されます。レポート設計者がさらに制御できるように、「allowfullscreen」や「privacy-enhanced」などのブール型プロパティを追加できます。
次に、プロパティ定義に関するサンプル・コードを示します。
{ id: "com.oracle.xdo.youtube", component: { name: "Youtube Video", cssClass: "youtube", icon: "http://hostname.com/youtube_32x32.png", tooltip: "Insert Youtube Video" }, properties: [ {key: "width", label:"Width", type:"length", value:"450px"}, {key: "height", label:"Height", type:"length", value:"370px"}, {key: "videoid", label:"Video ID", type:"string", value:"TK7KYaCEGZU"} ] ....... }
図11-3に、レイアウト・エディタの「プロパティ」ペインに表示されるプロパティを示します。
2. render関数を定義します。
render関数で、プロパティ・キーを使用してプロパティ値を取得し、getPixelValue
システム関数を呼び出して幅と高さのピクセル値を取得して、YouTube映像を埋め込むためのhtmlコードを作成します。
YouTube映像では、再生にswf(Flash)が使用されます。埋め込まれたFlashビデオ・プレーヤにより、映像の再生または一時停止に必要なクリック・イベントが中断されます。YouTubeには、この問題に対する回避策が用意されています。src
属性の埋込み後、&wmode=transparent
を追加します。
render関数のコードは次のようになります。
render: function(context, containerElem, rows, fields, props) { var videoid = props["videoid"]; var width = props["width"]; var height = props["height"]; var widthPx = xdo.api.getPixelValue(width); var heightPx = xdo.api.getPixelValue(height); var iframe = '<iframe id="'+context.id+'_iframe" style="z-index: -1" src="http://www.youtube.com/embed/'+videoid+'?wmode=transparent" width="'+(widthPx)+'" height="'+(heightPx)+'"> </iframe>'; xdo.dom.DOMElement.set(containerElem, iframe); }
同様の回避策が用意されていない別のソースからFlashコンポーネントを埋め込む場合、回避策を自身で実装する必要があります。HTMLにクリック・イベントを伝播するようにFlashコンポーネントを変更するか、ユーザーがスペースをクリックするとコンポーネントを選択できるように、Flashコンポーネントの周辺にクリック可能な追加のスペースを作成できます。
YouTubeプラグインの完全なコード・サンプルは次のようになります。
{ id: "com.oracle.xdo.youtube", component: { name: "Youtube Video", cssClass: "youtube", icon: "http://hostname.com/youtube_32x32.png", tooltip: "Insert Youtube Video" }, properties: [ {key: "width", label:"Width", type:"length", value:"450px"}, {key: "height", label:"Height", type:"length", value:"370px"}, {key: "videoid", label:"Video ID", type:"string", value:"TK7KYaCEGZU"} ], render: function(context, containerElem, rows, fields, props) { var videoid = props["videoid"]; var width = props["width"]; var height = props["height"]; var widthPx = xdo.api.getPixelValue(width); var heightPx = xdo.api.getPixelValue(height); var iframe = '<iframe id="'+context.id+'_iframe" style="z-index: -1" src="http://www.youtube.com/embed/'+videoid+'?wmode=transparent" width="'+(widthPx)+'" height="'+(heightPx)+'"> </iframe>'; xdo.dom.DOMElement.set(containerElem, iframe); } }
データ・モデルで定義されるデータ・フィールドを使用するようにプラグインを定義できます。このようにするには、プラグイン構造のfieldsコンポーネントでフィールド情報を指定します。labelとmeasureを指定します。
{ id: "com.oracle.xdo...", component: { name: "Field Test" } fields: [ {name: "labelField", caption: "Drop Label Field Here", fieldType:"label", dataType:"string"}, {name: "dataField", caption: "Drop Data Field Here", fieldType:"measure", dataType: "number", formula: "summation"} ], }
フィールドごとに次の項目を定義します。
name
caption - レイアウト・エディタがフィールドに関してユーザーに表示するテキスト。例: "Drop Label Field Here"
fieldType - fieldTypeの有効な値は、"label"と"measure"です。レイアウト・エディタには、フィールドに定義されたキャプション("Drop Label Field Here"など)が表示されます。レイアウト・エディタのユーザーは、データ・フィールドを、データ・ソース・ツリー構造からプラグイン・コンポーネントにドラッグ・アンド・ドロップできます。
dataType - 次のデータ型がサポートされます。
string(テキスト文字列、デフォルト)
number(数字、整数や浮動小数を含む)
data(XML日付形式)
レイアウト・エディタのデータ・モデル構造からドラッグ・アンド・ドロップする要素のデータ型は、ここで定義するdataTypeと一致する必要があります。
formula - fieldTypeが"measure"の場合、関数名を指定することで、集計値がサポートされます。次の関数名がサポートされます。
count
count-distinct
summation
average
maximum
minimum
データへのアクセス
計算されたデータは、ランタイムでrender
関数のrows
変数に格納されます。rows
変数は配列型で、各rows
要素には、列情報を保持するための別の配列があります。次のrender関数の実装により、データがHTMLで表示されます。
render: function(context, containerElem, rows, fields, props) { // setup column var html = '<table>'; for (var i=0, rowCount=rows.length; i<rowCount; i++) { html += "<tr>"; var col = rows[i]; for (var j=0, colCount=col.length; j<colCount; j++) { html += "<td>"; html += col[j]; html += "</td>"; } html += "</tr>"; } html += '</table>'; containerElem.innerHTML = html; }
フィールド・ラベル
ユーザーは、レイアウト・エディタのプロパティ・エディタを使用して、フィールド・ラベルの文字列を定義できます。この情報には、render
関数の引数のfields
変数や、プラグイン定義で定義される情報によってアクセスできます。
field - フィールド・パス
fieldFormula - フィールド式。このフィールドがfieldType="label"の場合、nullになります。
fieldType - フィールド・タイプ。"label"または"measure"
dataType - データ型。"string"、"number"または"data"
label - ユーザー指定のラベル文字列