ナビゲーション・ヘッダーをスキップ
Oracle Help for the Web開発者ガイド Table of Contents
目次
Previous topic
前へ
Next topic
次へ

Webアプリケーションでの状況依存ヘルプの実装

Oracle Help for the Web(OHW)では、Webアプリケーションのユーザー・インタフェースでの特定の状況に関連付けられたヘルプ・トピックを起動する、状況依存ヘルプのメカニズムが提供されています。一般的には、ヘルプ・トピックではWebアプリケーションの特定のページ、表または入力フィールドの機能が説明されています。ユーザーが、ユーザー・インタフェースのコントロールに関するヘルプを要求する(たとえば、「ヘルプ」ボタンをクリックする)と、その状況(コントロール)に関する適切なトピックが表示されます。

状況依存ヘルプをWebアプリケーションに実装するには、ヘルプ・システムのソースに1つ以上のマップ・ファイルがあり、適切なヘルプ・コードをアプリケーションのコードに追加する必要があります。

次の各項では、OHWを使用して状況依存ヘルプを実装する方法を説明します。

ヘルプ・トピックへのトピックIDのマッピング

OHWの状況依存ヘルプ・システムは、トピックIDをヘルプ・トピックのHTMLファイルにマップする1つ以上のマップ・ファイルを使用します。HelpBookの場合、マップ・ファイルはOHTファイル形式であり、ヘルプセットの場合、マップ・ファイルはXMLファイル形式です。

マップ・ファイルは、多くの場合ヘルプの作成者によって作成されます。Webアプリケーションの開発において、Webアプリケーションのコントロールを状況依存ヘルプ・トピックに関連付ける際には、作成者の作成したマップ・ファイルで指定されたトピックIDを使用する必要があります。したがって、プログラミングにはヘルプの作成者との共同作業が必要です。

XML形式のマップ・ファイルの例

 <?xml version='1.0' ?>

 <map version="1.0">   
<mapID target="topic_1" url="file_1.html" />
<mapID target="topic_2" url="file_2.html#a1" />
<mapID target="topic_3" url="file_3.html" wintype="intro" /> </map>

target属性は、ヘルプ・セットの関連付けられたHTMLファイルに対して一意のIDを指定します。 url属性は、そのIDに関連付けるファイルの位置を指定します。 wintype属性はオプションです。トピックが表示されるウィンドウ・タイプの名前を指定します。 マップ・ファイルで使用される要素の詳細は、「ファイルについて」を参照してください。

ヘルプ・システムへの状況依存ヘルプのリンクの作成

OHWを使用して状況依存ヘルプを実装したアプリケーションは、特別に作成されたOHWサーブレットを指定するURLを介して状況依存ヘルプのトピックを要求します。URLの宛先(リンク、画像など)にリンクしているユーザー・インタフェースのコントロールは、状況依存ヘルプのトピックと関連付けることができます。

状況依存ヘルプを表示するためのOHWへのリンクを作成する場合、(目次、索引および検索ナビゲータのある)フロント・ページのURLの宛先、またはトピックIDを使用するトピックのURLの宛先のどちらかを使用できます。

フロント・ページへのリンク

フロント・ページのURLは、OHWサーブレットのURLです。


 http://<server>:<port>/<servlet mapping>

ここで<server>はサーブレット・エンジンの実行に使用されるサーバーの名前、<port>はサーブレット・エンジンに使用されるポートの名前、<servlet mapping>はOHWサーブレットを出力するweb.xmlファイルに設定されているサーブレット・マッピング(デフォルトではohw/help/)です。 次に例を示します。


 http://www.yourcompany.com:8888/ohw/help/

フロント・ページにリンクするユーザー・インタフェースのコントロールのヘルプをユーザーが要求する場合、OHWはユーザーが使用しているブラウザに表示され、ヘルプ・システムの最初のページ(通常は目次)が表示されます。

トピックへのリンク

トピックにリンクするURLを作成するには、topicパラメータをOHWサーブレットのURLに追加します。topicパラメータの値は、ヘルプ・トピックのトピックIDです。


 http://<server>:<port>/<servlet mapping>/?topic=<topic-id>

たとえば、次のURLはトピックID topic_1に関連付けられるトピックを要求します。


 http://www.yourcompany.com:8888/ohw/help/?topic=topic_1

状況依存ヘルプのリンクをOHWに実装する際、アプリケーションのメイン・ページを置き換えるのではなく、2番目のウィンドウのリンクを開くように記述されたJavaScriptを使用する場合もあります。

トピックIDにリンクするユーザー・インタフェースのコントロールのヘルプをユーザーが要求する場合、OHWは、そのトピックIDに関連付けられたファイルを、OHWナビゲータ(タブ)を含まないページに表示します。しかし、ユーザーがメイン・ページにアクセスしようとする場合には、トピック・ページにはヘルプ・システムのフロント・ページへのリンクが表示されます。

オラクル社のUIXをベースにしたアプリケーションでの状況依存ヘルプの実装

UIX(Oracle JDeveloperで使用可能)は、オラクル社が開発した、Webアプリケーションを作成するためのテクノロジです。UIXのメカニズムでは、OHWを介した状況依存ヘルプが簡単に提供できます。UIXでは、UIXのJava APIを使用するか、UIX言語(XML言語)を宣言的に使用して、プログラムによって状況依存ヘルプを実装できます。

UIXのHelpProviderアーキテクチャは、状況依存ヘルプを実装するための汎用メカニズムを提供します。OHWは、OracleHelpProviderと呼ばれるHelpProviderを明確に実装することで、UIXアプリケーションに状況依存ヘルプを提供します。

OracleHelpProviderを使用するには、OHWをアプリケーションに登録し、データ・バインディングを介して状況依存ヘルプへのリンクを指定する必要があります。

OracleHelpProviderへのOHWの登録

OracleHelpProviderを使用するには、まず、使用しているOracleHelpProviderインスタンス(つまりOHW)をUIXのConfigurationオブジェクトに登録します。HelpProviderは、UIXではデータ・バインディングに使用できるUIXの特別なDataProviderです。これが特別なのはUIXページで宣言する必要がないからであり、使用しているHelpProviderConfigurationオブジェクトに登録すれば、すべてのページで使用可能になります。

2.1.6より前のUIXのリリースでは、UIXのConfigurationを変更する通常の方法は、PageBrokerサブクラスを記述し、createDefaultConfigurationメソッドをオーバーライドすることです。UIX 2.1.6からは、uix-config.xmlファイルおよびApplicationConfiguration APIを使用して、コードを記述せずに一連のConfigurationオブジェクトを作成でき、コードをコンパイルせずにフィールドの構成プロパティを更新できます。(しかし、この機能はサーブレット2.1以上を使用している開発者のみ使用可能です。そのためApache JServで配布するアプリケーションは、引き続きJavaコードを使用する必要があります。) uix-config.xmlファイルの詳細は、JDeveloperのオンライン・ヘルプ(UIXのダウンロード・バンドルが用意されています)で閲覧できる「UIX開発者ガイド」の「構成」の章を参照してください。

OHWをアプリケーションに登録するには、UIXによってOHWサーブレットのインスタンスが指定されるようにuix-config.xmlファイルを変更します。

uix-config.xmlファイルの例

 <?xml version="1.0" encoding="ISO-8859-1"?>

 <configurations xmlns="http://xmlns.oracle.com/uix/config">
   ...

   <default-configuration>

     <help-provider>
       <ohw-servlet-url>http://www.yourcompany.com:8888/ohw</ohw-servlet-url>
     </help-provider>

   </default-configuration>

   ...
 </configurations>

<help-provider>要素は、ヘルプ・プロバイダの構成を可能にします。今回唯一サポートされている構文は、組込み<ohw-servlet-url>要素です。ohw-servlet-urlは、OHWのインストールを示すURLを組み込む必要があります。このプロパティを一度設定すると、すべてのuiXMLおよびUIXのJavaページは、2つのデータ・プロバイダ(ui:helpTopicsui:helpSystem)へのアクセス権を持ちます。 状況依存ヘルプを宣言的に指定する方法は、「宛先のデータ・バインド」を参照してください。

UIX 2.1.6以上では、引き続きJavaコードを使用してConfigurationオブジェクトを作成し、さらにuix-config.xmlファイルに定義されているデフォルトの構成を使用する必要がある場合、次のコードを使用します。


 ApplicationConfiguration appConfig =
   ApplicationConfiguration.getInstance(servletContext);
 configurationImpl impl =
   new ConfigurationImpl ("someName", appConfig.getDefault());
 impl.register(servletContext);

UIX2.1.6より前のリリースで、プログラムによってOHWをアプリケーションに登録する場合、次のサンプル・コードを参照してください。

UIX2.1.6より前のリリースでcreateDefaultConfiguration()メソッドを使用するためのサンプル・コード


 protected ConfigurationImpl createDefaultConfiguration()
 {
   ConfigurationImpl cfg = super.createDefaultConfiguration();
   //For your application you'd likely pull the location of the
   //OHW servlet out of a servlet init parameter

   OracleHelpProvider provider = new OracleHelpProvider("http://www.yourcompany.com:8888/ohw/help/")
   cfg.setProperty(Configuration.HELP_PROVIDER, provider);
   return cfg;
 }

HelpProviderは2つの特別なデータ・オブジェクト(UIXのUIコンポーネントのネームスペースにあるhelpTopicsおよびhelpSystem)を設定します。 状況依存ヘルプを宣言的に指定する方法は、「宛先のデータ・バインド」を参照してください。

宛先のデータ・バインド

HelpProviderは2つのデータ・プロバイダ(ui:helpTopicsおよびui:helpSystem)を設定します。(ここで、uiはUIXのUIのネームスペースの接頭辞として使用されています。)これらは、ヘルプ・システムに接続されるリンクまたはボタン(またはリンクのあるコントロール)のdestination属性のデータ・バインドに使用されます。

OHWを開発中のUIXベースのアプリケーションに登録した後、データ・オブジェクトのui:helpTopicsおよびui:helpSystemを使用して状況依存ヘルプを宣言的に指定できます。

宛先のフロント・ページへのデータ・バインド

宣言的なUIXでは、フロント・ページの宛先は、データ・オブジェクトのui:helpSystemに対する特別なfrontPageキーを使用して作成できます。 次に例を示します。


 <globalButton icon="globalhelp.gif" text="Help" data:destination="frontPage@ui:helpSystem"/>

フロント・ページにリンクするユーザー・インタフェースのコントロールのヘルプをユーザーが要求する場合、OHWはユーザーが使用しているブラウザに表示され、ヘルプ・システムの最初のページ(通常は目次)が表示されます。

宛先のトピックへのデータ・バインド

トピックを表示するには、データ・オブジェクトのui:helpTopicsに対するキーとして一意のトピックIDを使用します。 次に例を示します。


 <button text="Button To Help" data:destination="myTopicID@ui:helpTopics" />
 <link text="Link To Help" data:destination="someOtherTopicID@ui:helpTopics" />

実行時には、UIXではOracleHelpProviderインスタンスを使用してこれらの宛先の値を決定します。OracleHelpProviderは、別々の小さいウィンドウにヘルプを起動するJavaScriptを含む宛先を自動的に返します。ユーザーがメイン・ページにアクセスしようとする場合、ウィンドウにはヘルプ・システムのフロント・ページへのリンクが表示されます。