Oracle HelpをADFアプリケーションへ統合する方法

Oracle JDeveloper How-Toドキュメント
著者： Dana Singleterry、Georg Neumann - Oracle Corporation
2009年9月

はじめに

Oracle Helpテクノロジーは、JavaアプリケーションおよびWebアプリケーションに対して、HTMLベースのヘルプ・システムを開発および表示する手段を提供します。 1つのヘルプ・システムを作成するだけで、変更を加えることなく、Java環境（Oracle Help for Java（OHJ）を使用）とWeb環境（Oracle Help for the Web - Rich Client（OHW-RC）を使用）の両方でヘルプを表示できます。

OHW-RCは、OHW-UIXと同様に、HTMLベースのヘルプ・コンテンツをWeb環境で提供します。 OHW-RCは、Java Server Faces（JSF）テクノロジーに基づくOracle Application Development Framework（Oracle ADF）を使用してユーザー・インタフェースを構築しており、このユーザー・インタフェースは、オラクルのブラウザ・ルック・アンド・フィール・プラス（BLAF＋）の動作およびガイドラインに従います。 OHW-RCはモデル・レイヤーを使用して、ヘルプ・コンテンツの提供、目次の作成、インデックスの処理、検索を行います。 ヘルプ・コンテンツはサーバー側で処理されるため、ユーザーはOHW-RCの単一インスタンスへアクセスします。

OHW-RCは、次のようなさまざまなケースで使用できます。

  1. ヘルプ・システムとして、新規ブラウザ・ウィンドウ上のリッチ・クライアント・アプリケーションに対して状況依存ヘルプを提供する
  2. スタンドアロンのドキュメント・ビューアとして、公開Webサイト上のヘルプ・コンテンツを表示する
  3. 一般的な検索エンジンでユーザーが検索を実行すると、索引付けされたOHW-RCコンテンツへのリンクを表示する
  4. HelpProviderインタフェースを使用して、Oracle ADF Facesコンポーネントのランタイム実装から埋込みヘルプ情報（定義テキスト、指示テキスト、またはヘルプ全体）を取得する

このHow-Toドキュメントでは、ADFアプリケーションにOHW-RCを統合する方法について説明します。また、この統合をデモンストレーションするためのサンプル・アプリケーションを提供しています。 このドキュメントでは上記のケース1とケース4についてデモンストレーションを行い、ケース2とケース3については、はじめに簡単に説明します。

ソフトウェア要件

  • Oracle JDeveloper 11g Release 1（11.1.1.1.0）
  • OHW-RCのシック・デモEARを ダウンロードすること。 このデモにはすべてのADFライブラリとOHWライブラリが含まれているため、ADF向けの設定が行われていないOracle WebLogic Server（Oracle WLS）10.3のサーバー・ドメインに対してデプロイできます。 使用するOracle WLS 10.3サーバー・ドメインがすでにADF向けに設定されている場合、OHW-RCのシン・デモEARを ダウンロードしてください。
  • サンプル・アプリケーションをサポートするOHW-RCアプリケーション（ohw-links.ear）を ダウンロードすること。
  • 起動アプリケーション（MyAppUsingOHW.zip）を ダウンロードし、JDeveloperで使用できるようにアーカイブを解凍すること。 または、デプロイとテスト向けの設定が完了しているADFアプリケーションの、アプリケーションEAR（MyAppUsingOHW.ear）を ダウンロードすることもできます。
  •  

新規ブラウザ・ウィンドウ上のリッチ・クライアント・アプリケーションに対する、状況依存ヘルプの提供と、HelpProviderインタフェースを使用した、コンポーネントのランタイム実装に対する埋込みヘルプ情報の提供

このHow-Toドキュメントを実行する際、JDeveloperが統合されたOracle WLS 10.3サーバーとOracle ADF向けに設定されたスタンドアロン・サーバーのいずれを使用することもできます。 説明では、2つのサーバーを組み合わせて使用していますが、必ずしもこれに従う必要はありません。 このHow-Toドキュメントでは、スタンドアロン・アプリケーション・サーバーにohw-links.earファイルをデプロイし、統合サーバー上で起動アプリケーション（MyappUsingOHW.jws）を実行していますが、 いずれのサーバーを使用しても構いません。

このセクションでは、OHW-RCをADFアプリケーションに統合するための基本的な方法について詳しく説明します。 デモンストレーションでは、ヘルプ・システムを使用して、新規ブラウザ・インタフェース上のリッチ・クライアント・アプリケーションに状況依存ヘルプを提供する方法と、定義したHelpProviderインタフェースを使用して、ADF Facesコンポーネントのランタイム実装から埋込みヘルプ情報（定義テキスト、指示テキスト、またはヘルプ全体）を取得する方法について説明します。

  1. WebLogic Serverドメインの管理サーバーを起動します。
  2. 管理サーバー・コンソールを起動します。
  1. 「 Deployments」を選択します。
  2. 「 Install」を選択します。
  3. ohw-links.earファイルの場所へ移動します。 注：使用するドメインには、ADFアプリケーションをデプロイするための設定が実施されている必要があります。
  4. デプロイする対象を選択し、「 Next」を選択します。
  5. 「 Install this deployment as an application」を選択し、「 Next」を選択します。
  6. "Optional Settings"ページで、「 Next」を選択します。
  7. 選択した内容を確認したら、「 Finish」をクリックします。
  8. 最終ページ"Setting for ohw-link"で「 Save」を選択します。
  9. ohw-linksアプリケーションは、ヘルプセットが異なる点を除いて、ohw-rcf-demo-thick.earおよびohw-rcf-demo-thin.earと同じアプリケーションであり、URL（http://localhost:7001/ohw-links/newhelp）からアクセスできます。しかし、ここで重要なのは、これから開発するADFアプリケーションが、ohw-linksアプリケーションを使用してヘルプ・コンテンツを表示する点です。 注：実際のポートは、説明で使用するポートとは異なる場合があります。

次に、新しいブラウザ・ウィンドウと埋込みヘルプの両方でヘルプを表示するように、シンプルなADFアプリケーションにヘルプを追加します。 注：ヘルプセットのオーサリングは、このHow-Toドキュメントの範囲外です。詳しくは、 OTNのOracle Helpページにある『Oracle Fusion Middleware Developer's Guide for Oracle Help』の"Authoring Oracle Help Systems"セクションを参照してください。

次に説明する手順に従うと、簡単にADFアプリケーションにOHW-RCを追加できます。

  • アプリケーションにヘルプ・プロバイダを登録します。
  • ヘルプ・トピックごとにトピックIDとヘルプ・テキストを含むプロパティ・ファイルを作成します。
  • HelpTopicId属性を使用して、ヘルプ・トピックにUIコンポーネントを関連付けます。

ここからは、MyAppUsingOHW.jwsアプリケーションを使用して上記手順をデモンストレーションしていきます。

  1. ADF Facesコンポーネントにヘルプ・トピックを統合すると、このコンポーネントにヘルプ・アイコン（クエスチョン・マークの付いた青色の丸印）が表示されます。 このヘルプ・アイコンをクリックすると、次のスクリーンショットのように、関連するヘルプ・トピックが新規ウィンドウに表示されます。 また、Oracle Helpでは状況依存ヘルプを表示することもできます。ここで使用するアプリケーションでは、両方のヘルプを表示します。 具体的には、クエスチョン・マークの付いた青色のアイコンが表示されている場合、これを選択すると別のブラウザ・ウィンドウにヘルプが表示されます。 また、入力フィールドを選択すると状況依存ヘルプが表示されます。
Integrated Help provided in a separate browser window
  1. ここで使用するアプリケーションとヘルプ・コンテンツは、上に示したアプリケーションよりも大幅にシンプルなものです。 ここで、ダウンロードした起動アプリケーションMyAppUsingOHW.jwsのワークスペースを開きます。
Workspace

注： 前述のとおり、必要な場合を除いてヘルプセット・コンテンツ自体にはほとんど注目しません。 コンポーネントにヘルプを追加する場合、より重要な要素は、adf-setting.xml、ohwconfig.xml、およびトピックIDを提供するコンポーネント自体に含まれます。 ただし、必要な場合はヘルプセットについて詳しく説明します。

  1. ADFリッチ・クライアントのヘルプ・プロバイダとしてOHW-RCを登録します。
    1. すでにWebアプリケーション（ohw-links.ear）としてOHW-RCをデプロイしましたが、このデプロイについて注意すべき点がいくつかあります。
      1. OHW-RCアプリケーションをWebアプリケーション・サーバーにデプロイします。
      2. このデプロイメントのコンテキスト・ルートを書き留めます。
      3. このデプロイメントのweb.xmlファイルを開きます。
      4. OHW-RCサーブレット・インスタンスを探します。
  3. jspx Webページを作成します。
    1. ADF FacesベースのWebアプリケーションを作成します。 ここで提供されている起動アプリケーション（MyAppUsingOHW）は、ADF Faces Webアプリケーションです。
    2. jspx Webページを作成します。一部のコンポーネント（input*、select*など）にはhelpTopicIdという属性が含まれています。この属性に、OHW-RCインスタンスで表示したいIDを指定します。 下のスクリーンショットのHelpTopicIdには concise_expandedが指定されています。
JSF Page
  1. <アプリケーションのルート>/public_htmlフォルダ内のディレクトリにヘルプセットをコピーします。 ここでは、helpsetsという名前のディレクトリを使用することにします。 提供されている起動アプリケーションでは、この名前がすでに使用されています。
Helpset
  1. ohwconfig.xmlの内容を確認します。 ここで注目すべきは、brandings、locales、およびcustomProtocolRegistryの各要素です。 brandings要素は、サンプル・アプリケーションを実行する際に表示されるヘルプ・システムに付与されるラベルです。 locales要素は多言語のヘルプセットを指定するために使用され、locale要素内のhelpset要素は使用するヘルプセット・ファイルを指定するために使用されます。 このインスタンスのcustomProtocolRegistry要素は、先ほどデプロイしたOHW-RC（ohw-links）を指定するものであり、必要な場合（コンポーネントの横のアイコンが選択された場合）に別のブラウザ・ウィンドウを開き、要求されたヘルプ・コンテンツを表示します。
ohwconfig.xml
  1. adf-settings.xmlファイルの設定を行います。 アプリケーションのディレクトリへ移動し、.adf/META-INF/ディレクトリを探します。 このディレクトリに、adf-settings.xmlファイルがあります。 .adf/META-INF/ディレクトリが存在しない場合、ViewController/srcディレクトリ内にMETA-INFディレクトリを作成します。 以下に例を挙げます。
    1. <adf-settings xmlns="http://xmlns.oracle.com/adf/settings">
                                          


                                           


 <help-provider>
                                          


                                           


 <help-provider-class>oracle.help.web.
 rich.helpProvider.OHWHelpProvider</help-provider-class>
                                          


                                           


 <property>
                                          


 <property-name>ohwConfigFileURL</property-name>
                                          


 <value>/helpsets/ohwconfig.xml</value>
                                          


 </property>
                                          


                                           


 <!--property>
                                          


 <property-name>group</property-name>
                                          


 <value>null</value>
                                          


 </property-->
                                          


                                           


 <property>
                                          


 <property-name>baseURI</property-name>
                                          


 <value>http://localhost:8989/help-ohw-rcf-context-root/ohguide/</value>
                                          


 </property>
                                          


                                           


 </help-provider>
                                          


                                           


</adf-settings>

このadf-settings.xmlファイルで、次の設定を行います。

  • OHW-RCをヘルプ・プロバイダとして使用する場合、クラスとしてOHWHelpProviderを指定します。
  • ohwConfigFileURLプロパティの値に/helpsets/ohwconfig.xmlを指定します。
  • groupプロパティには、ohwconfig.xmlファイルのグループ名（ヘルプ・プロバイダで使用する名前）を指定します。
  • baseURIプロパティには、サーバー・ホスト、コンテキスト・ルート、および先ほどデプロイしたOHW-RCアプリケーション（ohw-links.ear）のOHW-RCサーブレット・インスタンスを指定します。
  1. adf-settings.xmlファイルは次のようになります。このインスタンスではgroupプロパティは必要ないため指定されていませんが、その他すべてのプロパティは指定されています。
adf-settings.xml
  1. 最後の手順として、先ほどJSFページに追加したInput Textコンポーネントにヘルプ・トピックを関連付けます。 すでに、HelpTopicId属性の値として、ヘルプ・トピックの一意のIDであるconsise_expandedが指定されています。この値は、Property InspectorのAppearanceセクションで確認できます。 前述の手順4を参照してください。 Input Textコンポーネントのヘルプを表示するため、次に示すとおり、map.xmlファイルのヘルプ・コンテンツに一意のトピックIDを関連付けます。
map.xml
  1. concise_expandedというトピックIDに対してアクセスされるヘルプ・ファイルのコンテンツは、次のようになります。
concise_expanded.html
  1. 次に、アプリケーションのテストを行います。
    1. この時点で、スタンドアロンのOracle WLSインスタンスが実行中であり、ohw-linksアプリケーションがデプロイされてアクティブ状態にあるとします。作成したJSFページ上を右クリックし、コンテキスト・メニューから「 run」を選択します。 これは、入力フィールドが1つだけあるシンプルなADFアプリケーションです。 HelpProviderのアーチファクトとして追加された青色のクエスチョン・マーク・アイコンが表示されています。また、このInput Textコンポーネントのヘルプ・コンテンツには、HelpTopicIdが関連付けられています。
untitled1.jspx
  1. テキスト・ボックス内にカーソルを置くと、期待したとおりに埋込みヘルプが表示されます。
embedded help
  1. 青色のクエスチョン・マークを選択すると、新規ウィンドウが開き、OHW-RCヘルプ・システムからこのコンポーネントのコンテンツが表示されます。
popup help

次のセクションでは、ヘルプ・コンテンツのスタンドアロン・ドキュメント・ビューアとしてOHW-RCを使用する方法について説明します。

ヘルプ・コンテンツのスタンドアロン・ドキュメント・ビューアとしてのOHW-RCの使用

このセクションでは、ヘルプ・コンテンツのスタンドアロン・ドキュメント・ビューアとしてOHW-RCを使用する方法について、簡単に概要を説明します。 必要な手順は、 OTNのOracle Helpページで提供されているOHW-RCのシン・デモまたはシック・デモのEARに含まれるヘルプセットを交換するだけです。

  1. WebLogic Serverドメインの管理サーバーを起動します。
  2. 管理サーバー・コンソールを起動します。
  1. 「 Deployments」を選択します。
  2. 「 Install」を選択します。
  3. ADF向けに設定されていないOracle WLSサーバー・ドメインにデプロイする場合、ohw-rcf-demo-thick.earがある場所へ移動します。 ドメインがADF向けに設定されている場合、ohw-rcf-demo-thin.earの場所へ移動します。
  4. 使用する環境に合わせてデプロイ対象を選択し、「 Next」を選択します。
  5. 「 Install this deployment as an application」を選択し、「 Next」を選択します。
  6. Optional Settingsページで、「 Next」を選択します。
  7. 選択した内容を確認したら、「 Finish」をクリックします。
  8. 最終ページ"Setting for ohw-rcf-demo-thick"で「 Save」を選択します。
  9. アプリケーションをテストするため、URL"http://localhost:7001/ohw-rcf-demo/faces/helppages/main.jspx?config=OHW+Servlet+1"を使用してアプリケーションにアクセスします。

注：このOHW-RCデモは、Oracle Technology Network（OTN）の Oracle Helpページでも提供されています。

このデモが提供する機能をすべて把握するには、実際に使用してみることをお勧めします。 このデモにはOracle Help Guideのすべてのコンテンツだけでなく、シェイクスピアの文章に関するヘルプセットも含まれています。 目次と索引に加えて、検索機能も利用できます。 その他の機能も提供されているため、是非ご自身で探してみてください。

  1. 追加でヘルプセットを作成するには、メニューから「 File」→「 Import」を選択してOHW-RCシック・デモEARをJDeveloperにインポートし、アプリケーション・ワークスペースを確認します。 次に、追加したい新規ヘルプセットを作成し、必要に応じて既存のヘルプセットと置き換えます。
  1. ファイル・タイプとしてEARを選択します。
  1. 「 Copy Files to Application」を選択します。
  1. ohwconfig.xmlファイルの内容と、helpsetsディレクトリを構成しているhtmlを確認します。

注：Oracle Help for the Web構成ファイルは、OHW構成を定義するXMLファイルです。 この構成ファイルにより、OHW-RCサーブレットとOHW-UIXサーブレットにおける調整可能な機能がコントロールされます。 このファイルには通常ohwconfig.xmlという名前が付けられていますが、サーブレットの初期化パラメータconfigFileNameの値として指定すればどのような名前を使用しても構いません。 このファイルについての詳しい説明は、前のセクションを参照してください。

  1. カスタム・ヘルプセットを追加するために必要な手順は、ohw-rcf-demo-thickアプリケーションのヘルプセットと同じような方法でhtmlを作成するだけです。 ヘルプセットの作成について詳しくは、OTN上の『 Oracle Fusion Middleware Developer's Guide for Oracle Help』を参照してください。

このHow-Toドキュメントでは、ADFアプリケーションへOHW-RCを統合する方法とスタンドアロンのヘルプ・システムとしてOHW-RCを使用する方法について説明しました。 ADFアプリケーションへのOHW-RCの統合について詳しくは、『 Oracle Fusion Middleware Developer's Guide for Oracle Help 11g Release 1 (5.0) 』を参照してください。