1. Oracle ADFデスクトップ統合によるアプリケーションの開発
  2. 統合Excelワークブックのデプロイ

15 統合Excelワークブックのデプロイ

Fusion Webアプリケーションと統合したワークブックをエンド・ユーザーに公開してデプロイする方法、Fusion Webアプリケーションからのパラメータを統合Excelワークブックに渡す方法、およびADFワークブック・コンポーザをFusion Webアプリケーションに統合する方法について説明します。

この章の内容は次のとおりです。

統合Excelワークブックのデプロイについて

統合Excelワークブックの開発が終了した後、最終の統合Excelワークブックをエンド・ユーザーが使用できるようにするために、完成したFusion Webアプリケーションをアプリケーション・サーバーにデプロイします。

Fusion Webアプリケーションと統合される最終のExcelワークブックをデプロイする前に、「統合Excelワークブックの公開」の説明に従って、このExcelワークブックを公開する必要があります。Excelワークブックを公開した後、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「Fusion Webアプリケーションのデプロイ」に概説されている方法のいずれかを使用してワークブックをデプロイできます。

エンド・ユーザーがADFデスクトップ統合アドインをインストールできるように、ADFデスクトップ統合のadfdi-excel-addin-installer.exeをエンド・ユーザーが使用できるようにしてください。詳細は、「エンド・ユーザーがADFデスクトップ統合を使用できるようにするための処理」を参照してください。

統合Excelワークブックをデプロイするエンド・ユーザーは、Windowsベースのコンピュータ上にExcel用のADFデスクトップ統合アドインをインストールする必要があります。

統合Excelワークブックのデプロイのユース・ケースと例

「Oracle ADF」タブの「公開」ボタンを使用して、ワークブックの公開済コピーを保存します。図15-1に、「公開」ボタン、およびこのボタンをクリックすると開く「ワークブックの公開」ダイアログを示します(このダイアログを使用して、公開およびFusion Webアプリケーションとともにデプロイするための準備が整った統合Excelワークブックのコピーを保存します)。

図15-1 ワークブックの公開ダイアログ

図15-1の説明が続きます
「図15-1 ワークブックの公開ダイアログ」の説明

統合Excelワークブックのデプロイの追加機能

統合Excelワークブックを公開してデプロイした後、必要に応じてワークブックの機能をさらに追加できます。次の各項では、使用可能なその他の機能について説明します。

エンド・ユーザーによるADFデスクトップ統合の使用を可能にする

開発者が統合Excelワークブックで構成した機能をエンド・ユーザーが使用するには、ADFデスクトップ統合をインストールする必要があります。

エンド・ユーザーがADFデスクトップ統合をインストールする方法の詳細は、「システムへのADFデスクトップ統合のインストール方法」を参照してください。

エンド・ユーザーが利用できるインストーラの詳細は、「WebサーバーからADFデスクトップ統合アドインをインストールする方法」を参照してください。

インストール・プログラム(adfdi-excel-addin-installer.exe)は、次のディレクトリにあります。

MW_HOME\oracle_common\modules\oracle.adf.desktopintegration

MW_HOMEはミドルウェア・ホーム・ディレクトリです。

デフォルトで、ADFデスクトップ統合対応Webアプリケーションは、エンド・ユーザーが統合Excelワークブックをダウンロードしようとしたときにエンド・ユーザーの環境を確認するシステム・チェックも表示します。Javaアプレットがこのシステム・チェックを実行して、ADFデスクトップ統合アドインがエンド・ユーザーのマシン上に存在するかどうかを確認します。アドインが検出されると、ワークブックのダウンロードが自動的に開始されます。ない場合は、ADFデスクトップ統合により、エンド・ユーザーにアドインのインストールを求めるプロンプトが表示されます。Javaがエンド・ユーザーのマシンにインストールされていない場合、またはエンド・ユーザーのセキュリティ設定によって無効になっている場合は、JavaアプレットがADFデスクトップ統合アドインの存在を確認できません。ADFデスクトップ統合は、アドインのインストールが確認できないことをエンド・ユーザーに通知します。ワークブックのダウンロード、およびアドインのインストールのオプションをエンド・ユーザーに提示します。

統合Excelワークブックの公開

Oracle ADFの機能を使用したExcelワークブックの構成が終了したら、これを公開する必要があります。ワークブックを公開することで、統合Excelワークブックを実行時にエンド・ユーザーが使用できるようになります。

ADFデスクトップ統合では、ワークブックを公開する方法が2つ用意されています。統合ExcelワークブックをExcelから直接公開するか、JDeveloperで使用可能な公開ツールを使用してコマンドラインからワークブックを公開できます。コマンドラインの公開ツールでは、ANTスクリプトなどのスクリプトを使用して、Fusion Webアプリケーションから統合Excelワークブックを公開できます。

注意:

  • 1つまたは複数のワークブックを公開した後で、それらのワークブックをダウンロードしてMicrosoft Excelで正常に開くために、Fusion Webアプリケーションを再起動する必要があります。Webアプリケーションが再起動されないと、次のようなエラーが発生する可能性があります。

    TampercheckErrorException: ADFDI-05537: ワークブック統合の整合性を判別できませんでした。

  • カスタマイズ対応のワークブックは、関連付けられたプロジェクトのpublic_htmlディレクトリ(またはそのサブディレクトリ)の下のターゲットの場所にのみ公開できます。

統合ExcelワークブックをExcelから公開する方法

ワークブックを公開するには、「Oracle ADF」タブ上のボタンをクリックして、表示されるダイアログで値を指定します。

始める前に:

統合Excelワークブックの公開方法について理解しておくと役立ちます。「統合Excelワークブックの公開」を参照してください。

他のADFデスクトップ統合の機能を使用して追加できる機能についても理解しておくと役立ちます。「統合Excelワークブックのデプロイの追加機能」を参照してください。

ApplicationHomeFolderプロパティやWebPagesFolderプロパティなどのプロパティの構成の詳細は、「新しい統合Excelワークブックの構成方法」を参照してください。

Excelからワークブックを公開するには:

  1. 統合Excelワークブックを開きます。
  2. 「ワークブック・プロパティの編集」ダイアログのApplicationHomeFolderおよびWebPagesFolderプロパティが正しいことを確認します。これらのプロパティが設定されていない場合、統合Excelワークブックの公開時にADFデスクトップ統合によって設定するよう求められます。
  3. 「Oracle ADF」タブで「公開」ボタンをクリックします。
  4. 図15-1のように、表示されるワークブックの公開ダイアログで、公開されたワークブックのディレクトリとファイル名を指定します。公開するワークブック用に指定するディレクトリおよびファイル名は、設計時のワークブックのディレクトリおよびファイル名とは異なるものにする必要があります。
    ADFデスクトップ統合により、JDeveloperアプリケーション・ワークスペースのViewController\public_htmlディレクトリにワークブックを保存するよう求めるプロンプトが表示されます。設計モードのときにワークブックに追加された–DTなどの接尾辞を削除し、エンド・ユーザーにわかりやすい名前で表示されるようにします。たとえば、Summitサンプル・アプリケーションでは、設計モードで使用したEditCustomers-DT.xlsxではなくEditCustomers.xlsxのファイル名を使用して、顧客の編集をするワークブックを公開しています。
  5. 「保存」をクリックして変更内容を保存します。

コマンド行公開ツールを使用して統合Excelワークブックを公開する方法

この公開ツールはコマンド行から実行するもので、MW_HOME\jdeveloper\adfdi\bin\excel\tools\publishディレクトリにあるpublish-workbook.exeを指します。公開ツールを実行する前に、ソースの統合Excelワークブックを開いて「ワークブック・プロパティの編集」ダイアログのApplicationHomeFolderおよびWebPagesFolderプロパティが正しいことを確認します。

注意:

すでに公開済のワークブックまたは実行時モードのワークブックを公開することはできません。

始める前に:

統合Excelワークブックの公開方法について理解しておくと役立ちます。「統合Excelワークブックの公開」を参照してください。

他のADFデスクトップ統合の機能を使用して追加できる機能についても理解しておくと役立ちます。「統合Excelワークブックのデプロイの追加機能」を参照してください。

MW_HOME\jdeveloper\adfdi\bin\excel\tools\publishディレクトリにナビゲートし、次の構文を使用して公開ツールを実行します。

publish-workbook -workbook (-w) <source-workbook-path> -out (-o) <destination-workbook-path>

source-workbook-pathはソース・ワークブックのフルパスで、destination-workbook-pathは公開されるワークブックの保存先のフルパスです。

次に例を示します。

publish-workbook -workbook D:\Application1\Project1\ViewController\src\oracle\sampledemo\excel\workbook-DT.xlsx -out D:\Application1\Project1\ViewController\public_html\excel\published\workbook.xlsx

ヒント:

公開ツールの必須の引数に関する詳細を参照するには、次のコマンドを実行します。

publish-workbook -help (-h)

注意:

  • 必ずソースおよび保存先のワークブックの絶対パスを指定します。公開ツールでは、ワークブックの相対パスをサポートしていません。

  • ワークブックのパスが異なる場合でも、保存先のワークブックにソースと同じ名前を付けることはできません。

統合Excelワークブックが正常に公開されると、公開ツールによって成功メッセージが表示されます。ワークブックの公開中にエラーが発生した場合は、公開ツールによって処理が中止され、コマンド行コンソールにエラー・メッセージが表示されます。

ANTでの公開ツールの使用

Fusion Webアプリケーションのビルド時にANTスクリプトを作成して、JDeveloperから公開ツールを実行できます。ANTを使用してユーティリティを実行するには、次のいずれかの方法を使用します。

  • プロジェクト用のANTビルド・スクリプトを生成して、ワークブックのコマンド行公開ツールを実行するためのターゲットを追加します。

  • ワークブックのコマンド行公開ツールを実行するために、別個のANTビルド・スクリプトを生成または作成します。

公開ツールを実行するためのANTビルド・スクリプトのサンプル(publish-workbook.xml)は、MW_HOME\jdeveloper\adfdi\bin\excel\samplesディレクトリにあります。このANTスクリプトのサンプルは、コマンド行のワークブック公開ツールの起動を実例で示します。

統合Excelワークブックを公開する際の実行時の処理

設計モードで「公開」ボタンをクリックすると、ADFデスクトップ統合では次のアクションが実行されます。

  1. 必須のワークブック設定を検証します。

  2. クライアント・レジストリを更新します。「統合Excelワークブックのメタデータの整合性チェック」を参照してください。

  3. 公開されるワークブックを、指定のファイル名で、指定のディレクトリに作成します。

    公開によっても、ワークブック定義がエクスポートされます。公開されたワークブック定義のXMLファイルは、設計時のワークブックのコピーと同じ場所に保存されます。ワークブック定義の詳細は、「Excelワークブック統合メタデータのエクスポートおよびインポート」を参照してください。

  4. 公開されるワークブックのワークブック設定からApplicationHomeFolder、WebAppRootおよびWebPagesFolderの各プロパティを消去します。

  5. 設計時のすべてのコンポーネントのプレースホルダを消去します。

  6. ワークブックのモードを実行時モードに変更します。

  7. Publishing Timestampプロパティをワークブックに挿入します。このプロパティは、「情報」ダイアログの「プロパティ」タブに表示されます。

Fusion Webアプリケーションによる公開済ワークブックのデプロイ

統合Excelワークブックを公開した場合、Fusion Webアプリケーションをデプロイすると、Fusion Webアプリケーションによって、公開されたワークブックが自動的に組み込まれます。ワークブックがJDeveloperプロジェクトを構成する他のファイルとともにパッケージ化されていない場合は、Fusion WebアプリケーションのJDeveloperプロジェクトにワークブックを追加します。

こうすることで、最終のFusion Webアプリケーションをデプロイする際に、Fusion Webアプリケーションと統合するExcelワークブックが確実にデプロイされます。たとえば、ADFデスクトップ統合のSummitサンプル・アプリケーションは、次の場所で統合された、デプロイ済Excelワークブックを保存します。

<Summit_HOME>\ViewController\public_html\excel

ここで、Summit_HOMEはADFデスクトップ統合のSummitサンプル・アプリケーションのインストール・ディレクトリです。

統合Excelワークブックの格納先を決定したら、エンド・ユーザーが統合ExcelワークブックにアクセスできるようにFusion WebアプリケーションでWebページを構成できます。たとえば、図15-2は、ADFデスクトップ統合のSummitサンプル・アプリケーションのMainPage.jsfページで、顧客サンプルの編集ワークブックのワークブックのダウンロード・ボタンをクリックすることで起動された、Internet Explorerの「ファイルのダウンロード」ダイアログを示します。

図15-2 Fusion Webアプリケーションからの統合Excelワークブックの起動

図15-2の説明が続きます
「図15-2 Fusion Webアプリケーションからの統合Excelワークブックの起動」の説明

図15-2に示されている機能を有効にするには、Excelワークブックが認識されるようにFusion WebアプリケーションのHTTPフィルタ・パラメータを構成する必要があります。Fusion WebアプリケーションでADFデスクトップ統合が有効になっている場合、これらのパラメータはJDeveloperによって自動的に構成されます。HTTPフィルタ・パラメータを手動で構成する場合は、「Webアプリケーション・デプロイメント・ディスクリプタでのADFデスクトップ統合の設定」を参照してください。

Fusion WebアプリケーションのHTTPフィルタを構成した後、Fusion Webアプリケーションによってエンド・ユーザーに表示されるWebページを構成し、エンド・ユーザーがExcelワークブックを起動できるようにします。Fusion Webアプリケーションと統合されたExcelワークブックを起動できるようにする基本的な方法は、ワークブックを起動するハイパーリンクを提供することです。たとえば、Webページに次のようなADFコードを記述できます。

<af:link text="Editable Table Sample" destination="/excel/EditCustomers.xlsx"/>

ここで、excelは、WebPagesFolderワークブック・プロパティによって指定されるディレクトリのサブディレクトリで、EditCustomers.xlsxはエンド・ユーザーが起動するExcelワークブックです。

エンド・ユーザーがWebページのボタンやメニューから統合Excelワークブックをダウンロードできるようにするための機能を提供できます。次にいくつかの例を示します。

  • ボタン

    クリックすると統合Excelワークブックが起動するボタンをWebページ上に表示します。たとえば、図15-2のワークブックのダウンロード・ボタンは、MainPage.jsfページに公開されるボタン・コンポーネントです。

  • 選択リスト

    統合Excelワークブックを起動するボタンとともに、ADF Faces selectOneChoiceコンポーネントを使用します。

  • メニュー

    ADF Faces goMenuItemコンポーネントを使用します。

Fusion WebアプリケーションのWebページの作成の詳細は、『Oracle ADF FacesによるWebユーザー・インタフェースの開発』の「ADF FacesとJDeveloperの概要」を参照してください。

ADFデスクトップ統合に対応するFusion WebアプリケーションをJDeveloperからデプロイする際の処理

ADFデスクトップ統合が有効になっているFusion WebアプリケーションをJDeveloperからデプロイする際は、ADFデスクトップ統合の共有ライブラリへの参照が適切なディスクリプタ・ファイルに追加されます。ADFデスクトップ統合のモデルAPIライブラリまたはADFデスクトップ統合ランタイム・ライブラリを参照する1つ以上のプロジェクトを含むすべてのFusion Webアプリケーションについて、プラットフォームに依存するADFデスクトップ統合モデルAPIの共有ライブラリへの参照がデプロイメント中に追加されます。

ADFデスクトップ統合ランタイム・ライブラリへの参照を含むすべてのWebアプリケーション・モジュール(WAR)プロジェクトの場合は、プラットフォームに依存しないADFデスクトップ統合ランタイム共有ライブラリへの参照がデプロイメント中に追加されます。

Fusion WebアプリケーションのOracle WebLogic Serverへのデプロイ

Oracle WebLogicサーバーにFusion Webアプリケーションをデプロイする際は、次の処理が実行されます。

  • デプロイされるアプリケーションEARファイルのMETA-INF/weblogic-application.xmlファイルに、oracle.adf.desktopintegration.modelへのライブラリ参照が含まれます。

    次に例を示します。

    <library-ref>
  <library-name>oracle.adf.desktopintegration.model</library-name>
</library-ref>

    共有ライブラリは、oracle.adf.desktopintegration.model.earファイルのMW_HOME/oracle_common/modules/oracle.adf.desktopintegration.modelに配信されます。

  • デプロイされるWebアプリケーションWARファイルのWEB-INF/weblogic.xmlファイルに、oracle.adf.desktopintegrationへのライブラリ参照が含まれます。

    次に例を示します。

    <library-ref>
  <library-name>oracle.adf.desktopintegration</library-name>
</library-ref>

    共有ライブラリは、oracle.adf.desktopintegration.warファイルのMW_HOME/oracle_common/modules/oracle.adf.desktopintegrationに配信されます。

実行時の処理: 公開されたワークブックのエンド・ユーザーによるリクエスト

web.xmlがADFデスクトップ統合を使用するFusion Webアプリケーション用に構成されている場合、次のことが起こります

ADFデスクトップ統合を使用するFusion Webアプリケーション用に構成されている場合、次のイベントが発生します。

  • DIExcelDownloadFilterフィルタが定義されます。

  • フィルタ・マッピングは、*.xlsxおよび*.xlsmファイルに定義されます。

実行時に、エンド・ユーザーがワークブックに対してHTTPリクエストを出す(たとえば、ユーザーがアプリケーションからWebページのリンクをクリックする)と、DIExcelDownloadFilterフィルタは、HTTPレスポンスとしてストリーム化されて戻されたWebAppRootプロパティをワークブックに埋め込みます。WebAppRootプロパティは後でADFデスクトップ統合クライアントにより使用されて、Fusion Webアプリケーションに接続し、ユーザー・セッションを確立し、データを相互に送信します。「Fusion Webアプリケーションのページからワークブックへパラメータ値を渡す方法」に説明されているように、パラメータ値をWebアプリケーションからワークブックに渡すこともできます。

DIExcelDownloadFilterフィルタはWebAppRoot値を、doFilter()エントリ・ポイントに渡される現在のHttpServletRequestオブジェクトから構築します。フィルタ・コードはHttpServletRequest.getRequestURL()を呼び出し、コンテキスト・パス部分の後をすべて削除する(HttpServletRequest.getContextPath()を使用)ことで、完全なURLの"root"部分を取得します。

Fusion Webアプリケーション・ページからワークブックにパラメータ値を渡す

Fusion Webアプリケーション・ページは、エンド・ユーザーがそのページからワークブックをダウンロードするときに、統合Excelワークブックにパラメータ値を渡すように構成できます。

ワークブック・パラメータを使用して、ユーザーのWebページから統合ワークブックにコンテキストを渡すことができます。渡されたコンテキストは、統合ワークブックからWebアプリケーションに送信されて戻され、アプリケーションの状態に影響します(ワークブックでどのようなデータがレンダリングされるかなど)。たとえば、図15-3に示すように、Summitサンプル・アプリケーションでは、倉庫のリストがエンド・ユーザーに表示されます。エンド・ユーザーがワークブックのダウンロード・ボタンをクリックすると、Summitサンプル・アプリケーションは、WarehouseIDパラメータの値をワークブックに渡してダウンロードします。渡されたWarehouseIDパラメータでは、倉庫のどのデータが編集用にワークシートにレンダリングされるかを制御します。

図15-3 パラメータ値に基づいたワークブックのダウンロード

この図は周囲のテキストで説明しています

Fusion Webアプリケーション・ページから統合Excelワークブックにパラメータを渡すには、次のステップに従います。

  1. エンド・ユーザーがFusion Webアプリケーションから統合Excelワークブックをダウンロードできるように、HTTPフィルタが構成されていることを確認します。デフォルトでは、プロジェクト内でADFデスクトップ統合を有効化すると、JDeveloperによってHTTPフィルタが適切な値で構成されます。HTTPフィルタのパラメータ値を検証するには、「ADFデスクトップ統合Excelダウンロード・フィルタの構成」を参照してください。

  2. エンド・ユーザーがワークブックをダウンロードできるFusion WebアプリケーションのWebページで名前/値のペアをURL引数として使用します。「パラメータを渡すためにFusion Webアプリケーションのページを構成する方法」を参照してください。

    注意:

    ?より右の、問合せ文字列全体のURLエンコードされたランタイム値は、2048バイト未満にする必要があります。ランタイム値が2048バイトを超える場合、統合Excelワークブックに含まれるURL引数は、2048バイト内に収まる分のみです。残りのURL引数は、統合Excelワークブックに含まれません。かわりに、これらのURL引数が含まれていないことを示すログ・エントリがFusion Webアプリケーションによって書き込まれます。

    たとえば、?の右にある、次のEL式が評価されてからURLエンコードされた文字列結果の合計サイズは、2048バイトよりも小さい必要があります。

    "/excel/EditWarehouseInventory.xlsx?WarehouseId=#{item.bindings.Id.inputValue}"

    この上限を超える情報を渡す必要がある場合は、(カスタム)データベース表に一時的に格納し、一意のトークンのみを渡して、その情報レイヤーを参照することを検討してください。この技術により、望ましくない公開からコンテキスト情報も保護されます。

  3. 「ワークブック・プロパティの編集」ダイアログおよび「ワークシート・プロパティの編集」ダイアログで、パラメータ名を定義します。「統合Excelワークブックでパラメータのプロパティを構成する方法」を参照してください。

  4. <parameter>要素を追加して、統合Excelワークブックのワークシートに関連付けられているページ定義ファイルを構成します。「ワークシートでパラメータを受け取るようにページ定義ファイルを構成する方法」を参照してください。

図15-4に、パラメータをWebアプリケーションからEditWarehouseInventory-DT.xlsxワークブックに渡すために、Summitサンプル・アプリケーションに実装されているステップを示します。Summitサンプル・アプリケーションの詳細は、「ADFデスクトップ統合のサンプル・アプリケーションの概要」を参照してください。

図15-4 パラメータを渡すためのワークブックとFusion Webアプリケーションの構成

図15-4の説明が続きます
「図15-4 パラメータを渡すためのワークブックとFusion Webアプリケーションの構成」の説明

パラメータを渡すためにFusion Webアプリケーションのページを構成する方法

<af:button>などのコンポーネントを使用して、統合ワークブックの公開済コピーをエンド・ユーザーがダウンロードできるようにすることができます。コンポーネントの接続先URLは、統合ワークブックを参照し、その問合せ部分では、URLパラメータの名前と値がワークブックのパラメータ名と値に対応します。また、呼び出されたときに、コンポーネントとそのプロパティ値で参照される値をリフレッシュするようFusion Webアプリケーションに要求するコマンドをページで指定します。

アクション・コンポーネントを使用したファイルのダウンロードの詳細は、『Oracle ADF FacesによるWebユーザー・インタフェースの開発』のファイルをダウンロードするためのアクション・コンポーネントの使用方法に関する項を参照してください。

始める前に:

Fusion Webアプリケーションから統合Excelワークブックへパラメータ値を渡す方法を理解しておくと役立ちます。「Fusion Webアプリケーションのページからワークブックへパラメータ値を渡す方法」を参照してください。

他のADFデスクトップ統合の機能を使用して追加できる機能についても理解しておくと役立ちます。「統合Excelワークブックのデプロイの追加機能」を参照してください。

Fusion Webアプリケーションのページを構成するには:

  1. JDeveloperで、エンド・ユーザーによる統合Excelワークブックのダウンロード元となるページにコンポーネントまたはタグ(af:buttonなど)を挿入します。
  2. 「構造」ウィンドウでコンポーネントを右クリックし、「プロパティに移動」を選択します。
  3. 「共通」セクションを展開し、プロパティの値を設定します。

    表15-1に、af:buttonコンポーネントのプロパティを示します。

    表15-1 af:buttonタグのプロパティ

    プロパティ 値

    Text

    実行時にエンド・ユーザーに表示されるテキストを記述します。

    たとえば、次のようなテキストを記述して実行時に表示します。

    Download Workbook

    Destination

    ダウンロードする統合Excelワークブックおよびその値をURL引数として指定するEL式を記述するための式ビルダーを起動します。

    たとえば、次のようなEL式を記述します。

    destination="/excel/EditWarehouseInventory.xlsx?WarehouseId=
#{item.bindings.Id.inputValue}"

    RFC3986に従い、URLの引数名および値には予約文字(#、?および&など)を含めないでください。バインディング・コンテナ属性の値をURLの引数値として使用する場合にこれらの値を取得するためにJava Beanメソッドを使用することが必要な場合があります。Beanメソッドでは、URLを仕様に準拠させるために値をURLエンコードできます。URLエンコードの詳細は、Javaのjava.net.URLEncoderクラスを参照してください。

  4. (オプション)「動作」セクションを開き、起動するとaf:buttonタグおよびDestinationプロパティの値を更新するpartialTriggersプロパティのコンポーネントIDを指定します。

    たとえば、NextButton、PreviousButton、FirstButtonおよびLastButtonというIDのナビゲーション・ボタンがある場合は、次のように指定します。

    :NextButton :PreviousButton :FirstButton :LastButton

  5. ページを保存します。

    この手順で示した必要な例を使用した場合にJDeveloperによってJSFページに生成されるエントリを、次の例に示します。 

    <af:button text="Download Workbook" id="b2"
                    destination="/excel/EditWarehouseInventory.xlsx
                               ?WarehouseId=#{item.bindings.Id.inputValue}"/>

統合Excelワークブックでパラメータのプロパティを構成する方法

エンド・ユーザーによってFusion Webアプリケーションからダウンロードされる統合Excelワークブックが、ワークブックのダウンロードURLの問合せ文字列に含まれているパラメータ値を受け取るように、ワークブックのParametersプロパティおよびワークシートのParametersプロパティを構成します。

始める前に:

Fusion Webアプリケーションから統合Excelワークブックへパラメータ値を渡す方法を理解しておくと役立ちます。「Fusion Webアプリケーションのページからワークブックへパラメータ値を渡す方法」を参照してください。

他のADFデスクトップ統合の機能を使用して追加できる機能についても理解しておくと役立ちます。「統合Excelワークブックのデプロイの追加機能」を参照してください。

ワークブックのParametersプロパティを構成するには:

  1. 統合Excelワークブックを開きます。

  2. 「Oracle ADF」タブの「ワークブック」グループで、「ワークブック・プロパティ」をクリックします。

  3. 「パラメータ」の入力フィールドの横にある参照(...)アイコンをクリックして、「パラメータの編集」ダイアログを起動します。

  4. 「追加」をクリックして新しいワークブック・パラメータを追加し、プロパティを次のように構成します。

    • 「パラメータ」フィールドで、af:buttonタグのDestinationプロパティのURL引数として使用するパラメータ名を定義し、「Fusion Webアプリケーションのページを構成してパラメータを渡す方法」の説明に従って、ページ定義パラメータに後でバインドします。

      たとえば、EditWarehouseInventory-DT.xlsxワークブックでは、図15-5に示すように、WarehouseIDパラメータ値を定義します。

      ヒント:

      定義した値が標準のURL問合せ文字列に使用できることを確認します。EL式で参照した際に適切に機能するように、使用するパラメータ名は簡単な識別子にしてください。

      図15-5 ワークブック・パラメータ

      この図は周囲のテキストで説明しています

    • (オプション)「注釈」フィールドに、ワークブック・パラメータの説明を入力します。

  5. 必要に応じて、ステップ4を繰り返し、他のワークブック・パラメータを追加します。

  6. 「OK」をクリックします。

    ワークブックのParametersプロパティの詳細は、表A-19を参照してください。

ワークシートのParametersプロパティを構成するには:

  1. 統合Excelワークブックを開きます。

  2. 「Oracle ADF」タブの「ワークブック」グループで、「ワークシート・プロパティ」をクリックします。

  3. 「パラメータ」の入力フィールドの横にある参照(...)アイコンをクリックして、「パラメータの編集」ダイアログを起動します。

  4. 「追加」をクリックして、新しいワークシート・パラメータを追加し、図15-6に示すように、EditWarehouseInventory-DT.xlsxワークブックから構成します。

    • 「ワークシートでパラメータを受け取るようにページ定義ファイルを構成する方法」でワークシートに関連付けられているページ定義ファイルに追加したパラメータ要素を、「パラメータ」フィールドで指定します。

    • ワークブック・パラメータ(ワークブックのParameters配列)に対して指定したParameterプロパティの値を参照するEL式を、「値」フィールドに記述します。EL式を記述する際は、次の構文を使用します。

      #{workbook.params.parameter}

      parameterは、ワークブック・パラメータ用に指定されたParameterプロパティの値を参照します。

    • (オプション)「注釈」フィールドに、ワークシート・パラメータの説明を入力します。

    図15-6 ワークシート・パラメータ

    この図は周囲のテキストで説明しています

  5. 必要に応じて、ステップ4を繰り返し、他のワークブック・パラメータを追加します。

  6. 「OK」をクリックします。

    ワークシートのParametersプロパティの詳細は、表A-20を参照してください。

新しい各ユーザー・セッションで初期サーバー状態を設定するのに、ワークブック・パラメータ値が必要なユースケースでは、SendParametersプロパティをTrueに設定します。また、メソッド・アクション・バインディングを指定して、ワークブック・パラメータ値を使用してサーバー状態を初期化する、ワークシートのSetupActionIDを起動する必要があります。

ワークシートのSendParametersおよびSetupActionIDプロパティを構成する手順:

  1. 統合Excelワークブックを開きます。
  2. 「Oracle ADF」タブの「ワークブック」グループで、「ワークシート・プロパティ」をクリックします。
  3. 「ワークシート・プロパティの編集」ダイアログで、表15-2および図15-7に示すように、SendParametersおよびSetupActionIDの値を設定します。

    表15-2 SendParametersおよびSetupActionIDプロパティ

    設定するプロパティ 設定する値

    SendParameters

    True: ワークシート・パラメータがワークシートのバインディング・コンテナに設定されます。Trueに設定した場合、すべてのユーザー・セッションにおいて、メタデータがリクエストされるたび、およびデータが初めてリクエストされたときに、パラメータが送信されます。False (デフォルト値): ワークシート・パラメータの明示的な送信は実行されません。

    SetupActionID

    ワークブック・パラメータ値を使用してサーバー状態を初期化する、起動するメソッド・アクション・バインディングを指定します。

    「明示的なワークシート設定アクションの使用」を参照してください。

    図15-7 SendParametersおよびSetupActionIDプロパティ

    この図は周囲のテキストで説明しています
  4. 「OK」をクリックします。

テスト・モードに入ると、「ワークブック・パラメータ」ダイアログでテスト・パラメータ値の入力を求められます。図15-8に、入力フィールド内のワークブックのテスト値を受け入れる「ワークブック・パラメータ」ダイアログを示します。

図15-8 「ワークブック・パラメータ」ダイアログ

この図は周囲のテキストで説明しています

テスト中、ここに入力した値はワークブック・パラメータ値に使用されます。ワークブック・パラメータをワークシートのページ定義パラメータにバインドした場合、ここに入力した値がバインディング・コンテナに送信されます。一部またはすべてのパラメータの値の入力は必須ではありません。テスト・パラメータ値を入力した場合、テスト・モードを終了して設計モードに戻ったときに値はクリアされません。統合Excelワークブックを再度実行する場合、キャッシュからのワークブック・パラメータ値が「ワークブック・パラメータ」ダイアログに表示されます。

提供されたテスト値は、ADFデスクトップ統合Excelダウンロード・フィルタがパラメータ値を格納するのと同じ方法でワークブックに格納されます。ワークブックを公開する際、ワークブックが公開される前にテスト・パラメータ値がクリアされます。

注意:

前述のEditWarehouseInventory-DT.xlsxワークブックの例では、FilterWarehouseMasterByIdメソッド・アクションをワークシートの設定アクション(SetupActionID)に使用できます。これにより、ワークシートが実行時に初期化されるとき(またはワークシートのバインディング・コンテナの新規インスタンスが作成されるたび)に、メソッドが自動的にコールされます。SetupActionIDの詳細は、「明示的なワークシート設定アクションの使用」を参照してください。

同じメソッド・アクションは、ユースケースに応じてリボン・コマンドやStartupイベントなどのアクション・セットの一部として構成することもできます。リボン・コマンドの場合、その実行はエンド・ユーザーによってトリガーされます。リボン・コマンドおよびStartupイベントの詳細は、「実行時リボン・タブのワークシート・リボン・コマンドの構成方法」および「ワークシート・イベントからアクション・セットを起動する方法」を参照してください。

ワークブック・パラメータ値は、ページ定義によって公開される任意のメソッドの引数として使用できます。

ワークシートでパラメータを受け取るようにページ定義ファイルを構成する方法

次の手順で、統合Excelワークブックのワークシートに関連付けられているページ定義ファイルを構成できます。

  • ワークシートのバインディング・コンテナを初期化する1つ以上のparameter要素を追加します。「パラメータを渡すためにFusion Webアプリケーションのページを構成する方法」に示されているように、これらのパラメータの値はURL引数から提供されます。

    次の例は、EditWarehouseInventory-DT.xlsxワークブックに関連付けられているExcelWarehouseInventory.xmlページ定義ファイルに定義されているWarehouseIdParamパラメータを示します。 

    <parameters>
        <parameter id="WarehouseIdParam" value="value"/>
    </parameters>

  • アプリケーション・モジュール・メソッドを起動するメソッド・アクション・バインディングを追加します。次の例は、EditWarehouseInventory-DT.xlsxワークブックに関連付けられているExcelWarehouseInventory.xmlページ定義ファイルの実装を示します。 

    <methodAction id="FilterWarehouseMasterById" RequiresUpdateModel="true"
     Action="invokeMethod" MethodName="FilterWarehouseMasterById"
     IsViewObjectMethod="false" DataControl="SummitAppModuleDataControl"
     InstanceName="data.SummitAppModuleDataControl.dataProvider">
  <NamedData NDName="warehouseId" NDValue="${bindings.WarehouseIdParam}"
     NDType="java.lang.String"/>
</methodAction>

ページ定義ファイルの構成の詳細は、「統合Excelワークブックのページ定義ファイルの使用」および『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のページ定義ファイルの使用に関する項を参照してください。

実行時の処理: Fusion Webアプリケーションから統合Excelワークブックへのパラメータの引渡し

エンド・ユーザーがFusion Webアプリケーションから統合Excelワークブックをダウンロードすると、ダウンロードをトリガーしたコンポーネント・タグ(af:buttonなど)が評価され、現在のパラメータ値(warehouseIDなど)が取得されてURLに組み込まれます。adfdiExcelDownloadフィルタによって、URLのすべてのパラメータの名前および値が、ダウンロードされた統合Excelワークブックに埋め込まれます。

これらのパラメータは、バインディング・コンテナがリフレッシュされる前にBindingContainer DCParametersに設定されます。ワークシート・パラメータがバインディング・コンテナにどのようにマップされるかの詳細は、「ワークシートでパラメータを受け取るようにページ定義ファイルを構成する方法」を参照してください。

新しい各ユーザー・セッションで初期サーバー状態を設定するのに、ワークブック・パラメータ値が必要なユースケースでは、Worksheet.ServerContext.SendParametersプロパティをTrueに設定します。また、メソッド・アクション・バインディングを指定して、ワークブック・パラメータ値を使用してサーバー状態を初期化する、ワークシートのSetupActionIDを起動する必要があります。ワークシートSetupActionIDプロパティの詳細は、「明示的なワークシート設定アクションの使用」を参照してください。

EditWarehouseInventory.xlsxワークブックでは、FilterWarehouseMasterByIdメソッドがユーザー・セッションごとに起動され、ダウンロードしたワークブックに格納されているワークブックWarehouseIdパラメータ値を使用して、正しいサーバー状態が設定されます。

ワークブックのすべてのワークシートの初期化状態をリセットするには、ClearAllDataアクションを起動します。ClearAllDataアクションの詳細は、表A-18を参照してください。

実行時のワークブック統合メタデータのカスタマイズ

ADFデスクトップ統合では、Oracle Metadata Services (MDS)ベースのランタイム・カスタマイズがサポートされます。

ワークブック統合メタデータでは、ADFデスクトップ統合コンポーネントがワークブックでどのように表示され動作するか、またワークブックがそのFusion Webアプリケーションでどのように統合されるかを定義します。ワークブックが公開されると、そのワークブック統合メタデータのXMLファイルが設計時のワークブックのコピーと同じ場所に保存されます。カスタマイズ対応ワークブックの公開の詳細は、「統合Excelワークブックの公開」を参照してください。

MDSの詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「MDSによるアプリケーションのカスタマイズ」を参照してください。

カスタマイズ対応ワークブックのワークブック統合メタデータ・ファイルは、MDSによって管理できるようにMDSメタデータ・リポジトリにデプロイする必要があります。メタデータ・リポジトリの詳細は、『Oracle Fusion Middlewareの管理』の「メタデータ・リポジトリの管理」を参照してください。

実行時のワークブックのカスタマイズを有効にする方法

ワークブック統合メタデータのカスタマイズを有効にするには、「ワークブックのプロパティ」ダイアログを開き、CustomizationEnabledをTrueに設定します。

始める前に:

ワークブック統合メタデータのカスタマイズを理解しておくと役立ちます。「実行時のワークブック統合メタデータのカスタマイズ」を参照してください。

他のADFデスクトップ統合の機能を使用して追加できる機能についても理解しておくと役立ちます。「統合Excelワークブックのデプロイの追加機能」を参照してください。

ワークブックの実行時カスタマイズを有効にする手順:

  1. 統合Excelワークブックを開きます。
  2. 「Oracle ADF」タブの「ワークブック」グループで、「ワークブック・プロパティ」をクリックします。
  3. 「CustomizationEnabled」をTrueに設定します。
  4. 「OK」をクリックします。
  5. カスタマイズ対応ワークブックを公開します。

実行時の処理: ワークブック統合メタデータがカスタマイズされた場合

カスタマイズ対応ワークブックは、ワークブックの初期化時にサーバーからそのメタデータを取得します。

この統合メタデータは、サーバー側のMDSによって管理され、MDS APIを通じてアプリケーションによってアクセスできます。実行時に、アプリケーションはユーザーにワークブック統合メタデータをカスタマイズする手段を提供できます。カスタマイズ対応ワークブックは、初期化されると、ワークブック統合メタデータをサーバーにリクエストします。MDSは、現在のカスタマイズ・コンテキストに基づいてすべてのカスタマイズを適用し、カスタマイズされたメタデータをその初期化のためにワークブックに戻します。

「Fusion WebアプリケーションへのADFワークブック・コンポーザの統合」に説明されているように、アプリケーション開発者は、シード・カスタマイズをアプリケーションに含めたり、ADFワークブック・コンポーザを統合したりできます。たとえば、アプリケーションは、ユーザーがカスタマイズ対応ワークブックの表の列をカスタマイズできるWebページを提供できます。ユーザーは、Webページ上の表から特定の列を削除し、カスタマイズ対応ワークブックをダウンロードして、ワークブックに適用される変更を確認できます。

ワークブック統合メタデータのカスタマイズに関する必知事項

カスタマイズ対応ワークブックは、関連付けられたプロジェクトのpublic_htmlディレクトリの下のディレクトリにのみ公開できます。アプリケーションをデプロイする際には、ワークブックが公開されるときに生成されたメタデータ・パスを使用して、対応するワークブック統合メタデータ・ファイルがMDSによって見つかることを確認します。

各カスタマイズ対応ワークブックには、固有のワークブック統合メタデータ・ファイルがあります。ワークブックが公開されると、そのワークブック統合メタデータのXMLファイルが設計時のワークブックのコピーと同じ場所に保存されます。このワークブック統合メタデータ・ファイルをMDSメタデータ・リポジトリにデプロイして、実行時にMDSが管理できるようにする必要があります。MDSの用語では、ワークブック統合メタデータ・ファイルはベース・ドキュメントであり、メタデータ・パスを使用してMDSによって参照されます。メタデータ・パスは、カスタマイズ対応ワークブックの公開時に決定されます。

たとえば、設計時のカスタマイズ対応ワークブックが<PROJECT_HOME>/public_html/myCompany/myPackage/myWorkbook.xlsxに公開され、そのワークブック統合メタデータ・ファイル名がmyWorkbook-DT.xlsx-workbook-definition.xmlの場合、このワークブックのメタデータ・パスは/myCompany/myPackage/myWorkbook-DT.xlsx-workbook-defintion.xmlです。実行時に、MDSはアプリケーションで構成されたリポジトリ内で、このメタデータ・パスを使用してワークブック統合メタデータを探します。メタデータ・パスは、アプリケーション全体で一意である必要があります。

デフォルトでは、MDSリポジトリがワークブック統合メタデータ・ファイルに対して構成されていない場合、MDSは前述のメタデータ・パスを使用してクラスパス上でメタデータ・ファイルを検索します。MDSの構成を回避するために、Fusion Webアプリケーションのクラスパス上にワークブック統合メタデータ・ファイルをホストできます。

Fusion WebアプリケーションへのADFワークブック・コンポーザの統合

ADFワークブック・コンポーザは、許可されたユーザーがFusion Webアプリケーションの実行時Webユーザー・インタフェースから統合ExcelワークブックをカスタマイズできるようにするADFタスク・フローです。

ADFワークブック・コンポーザを使用するには、カスタマイズ対応のワークブックをFusion Webアプリケーションに統合し、メタデータをMDSで管理する必要があります。カスタマイズ対応のワークブックの詳細は、「実行時のワークブック統合メタデータのカスタマイズ」を参照してください。

ADFワークブック・コンポーザを使用すると、エンド・ユーザーは実行時に次のアクションを実行できます。

  • 統合ExcelワークブックのADFコンポーネントの編集または削除

  • ワークシートでのコンポーネントの再配置

  • ADFコンポーネントのツールチップ、ラベルおよびソースの編集

  • ワークシートの削除

Fusion WebアプリケーションにADFワークブック・コンポーザを統合する方法

ADFワークブック・コンポーザのタスク・フローは、ADFライブラリとしてadf-workbook-composer.jarファイルにあります。jarファイルは、MWHOME/oracle_common/modules/oracle.adf.desktopintegrationディレクトリにあります。

ADFワークブック・コンポーザをFusion Webアプリケーションに統合する手順:

  1. JDeveloperでFusion Webアプリケーションを開きます。

  2. adf-workbook-composer.jarファイルをADFライブラリjarとしてFusion Webアプリケーションに追加します。

    1. 「アプリケーション」ウィンドウで、プロジェクト(ViewControllerなど)を選択して右クリックし、「プロジェクト・プロパティ」を選択します。

    2. 「プロジェクト・プロパティ」で、「ライブラリとクラスパス」を選択します。

    3. 「ライブラリとクラスパス」ページで「ライブラリの追加」をクリックします。

    4. 「ライブラリの追加」ダイアログで、「新規」をクリックします。

    5. 「ライブラリの作成」ダイアログで、ライブラリ名としてADF Workbook Composer Runtimeと入力します。

    6. 「エントリの追加」をクリックします。

    7. MWHOME/oracle_common/modules/oracle.adf.desktopintegrationディレクトリに移動して、adf-workbook-composer.jarファイルを選択し、「開く」をクリックします。

      注意:

      実行時にクラス・パスに表示されるadf-workbook-composer.jarファイルのコピーが重複しないように、「デフォルトでデプロイ済」チェック・ボックスの選択を解除してください。oracle.adf.desktopintegration共有ライブラリには、「実行時の処理: ADFワークブック・コンポーザの起動」に説明されているadf-workbook-composer.jarファイルが含まれます。

  3. 「アプリケーション」ウィンドウで、ADFワークブックコンポーザ・ランタイム・ライブラリを選択して展開します。

    ライブラリが表示されない場合は、「表示」→「アプリケーション・プロジェクト」→「ライブラリの表示」を選択します。

  4. WEB-INF\oracle\adf\workbookcomposer\view\taskflowsのworkbook-customization-task-flow.xmlファイルを特定し、ファイルをドラッグ・アンド・ドロップして、タスク・フローをホスト・ページ内にインポートします。

  5. 必要に応じて、目的のカスタマイズ・コンテキストを設定します。

  6. MDSリポジトリをadf-config.xmlに構成し、メタデータ・パスでワークブック・メタデータ・ファイルにアクセスできることを確認します。

  7. 必要なワークブック・メタデータ・パスおよびワークブック名パラメータをタスク・フローに指定します。

  8. Fusion Webアプリケーションの認可が有効の場合は、ワークブック・コンポーザjarファイルの/WEB-INF/oracle/adf/workbookcomposer/view/taskflows/ディレクトリにある、次のタスク・フローのリソース・アクセス権をユーザーに付与するためのセキュリティ・ポリシーを構成する必要があります。

    • button-customization-task-flow.xml

    • form-component-customization-task-flow.xml

    • image-customization-task-flow.xml

    • not-supported-task-flow.xml

    • read-only-table-customization-task-flow.xml

    • ribbon-command-customization-task-flow.xml

    • table-customization-task-flow.xml

    • workbook-customization-task-flow.xml

  9. ホストのWebページを実行して、ワークブック・コンポーザが正しくレンダリングされることを確認します。

実行時の処理: ADFワークブック・コンポーザの起動

ADFワークブック・コンポーザのタスク・フローは、ADFライブラリjarアフィルとしてadf-workbook-composer.jarファイルにあります。このjarは、oracle.adf.desktopintegration共有ライブラリに格納されています。oracle.adf.desktopintegration共有ライブラリは、Application Development Runtimeのインストール・プロセスの一部としてインストールされ、JRFドメイン拡張テンプレートに含まれています。Application Development Runtimeをインストールした場合、Fusion WebアプリケーションがWebLogic Serverで実行されると、実行時にADFワークブック・コンポーザのタスク・フローを使用できます。Application Development Runtimeのインストールの詳細は、『Oracle ADFアプリケーションの管理』の「ADFアプリケーションのデプロイ」を参照してください。

実行時に、ADFワークブック・コンポーザから行ったカスタマイズは、Fusion Webアプリケーションを再起動することなく即座に適用されます。ワークブックのカスタマイズに関連付けられているカスタマイズ・コンテキストを照合するエンド・ユーザーが、統合Excelワークブックの新しいコピーをダウンロードして開くか、初期化されたワークブックでClearAllDataワークブック・アクションを起動してからログインすると、そのカスタマイズが表示されます。

ADFワークブック・コンポーザに関する必知事項

ADFワークブック・コンポーザのタスク・フローには、次の2つのパラメータが必要です。

  • WorkbookName – 実行時にユーザーがカスタマイズする、公開されたワークブックの名前。名前はコンポーザに表示されます。

  • WorkookMetadataPath – ワークブック・メタデータ・ファイルのパス。これは、カスタマイズするワークブックのメタデータ・ファイルを特定するためにMDSで使用されるパスです。ワークブック・メタデータ・ファイルは、設計時ワークブックが公開されると生成されます。メタデータ・パスは、ワークブックの公開先の場所によって決定されます。