Oracle® Fusion Middleware

Oracle Helpによるヘルプ・システムの開発

12c (12.2.1.2.0)

E82760-01(原本部品番号:E76678-02)

2016年11月

JavaアプリケーションおよびWebアプリケーションのHTMLに基づくヘルプ・システムを開発、表示する方法について説明するOracle Help開発者用のドキュメントです。

Oracle Fusion Middleware Oracle Helpによるヘルプ・システムの開発 12c (12.2.1.2.0)

E82760-01

Copyright © 2015, 2016, Oracle and/or its affiliates.All rights reserved.

原本主著者: Ralph Gordon

このソフトウェアおよび関連ドキュメントの使用と開示は、ライセンス契約の制約条件に従うものとし、知的財産に関する法律により保護されています。ライセンス契約で明示的に許諾されている場合もしくは法律によって認められている場合を除き、形式、手段に関係なく、いかなる部分も使用、複写、複製、翻訳、放送、修正、ライセンス供与、送信、配布、発表、実行、公開または表示することはできません。このソフトウェアのリバース・エンジニアリング、逆アセンブル、逆コンパイルは互換性のために法律によって規定されている場合を除き、禁止されています。

ここに記載された情報は予告なしに変更される場合があります。また、誤りが無いことの保証はいたしかねます。誤りを見つけた場合は、オラクル社までご連絡ください。

このソフトウェアまたは関連ドキュメントを、米国政府機関もしくは米国政府機関に代わってこのソフトウェアまたは関連ドキュメントをライセンスされた者に提供する場合は、次の通知が適用されます。

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations.As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs.No other rights are granted to the U.S. Government.

このソフトウェアもしくはハードウェアは様々な情報管理アプリケーションでの一般的な使用のために開発されたものです。このソフトウェアもしくはハードウェアは、危険が伴うアプリケーション(人的傷害を発生させる可能性があるアプリケーションを含む)への用途を目的として開発されていません。このソフトウェアもしくはハードウェアを危険が伴うアプリケーションで使用する際、安全に使用するために、適切な安全装置、バックアップ、冗長性(redundancy)、その他の対策を講じることは使用者の責任となります。このソフトウェアもしくはハードウェアを危険が伴うアプリケーションで使用したことに起因して損害が発生しても、オラクル社およびその関連会社は一切の責任を負いかねます。

OracleおよびJavaはOracle Corporationおよびその関連企業の登録商標です。その他の名称は、それぞれの所有者の商標または登録商標です。

Intel、Intel Xeonは、Intel Corporationの商標または登録商標です。すべてのSPARCの商標はライセンスをもとに使用し、SPARC International, Inc.の商標または登録商標です。AMD、Opteron、AMDロゴ、AMD Opteronロゴは、Advanced Micro Devices, Inc.の商標または登録商標です。UNIXは、The Open Groupの登録商標です。

このソフトウェアまたはハードウェア、そしてドキュメントは、第三者のコンテンツ、製品、サービスへのアクセス、あるいはそれらに関する情報を提供することがあります。適用されるお客様とOracle Corporationとの間の契約に別段の定めがある場合を除いて、Oracle Corporationおよびその関連会社は、第三者のコンテンツ、製品、サービスに関して一切の責任を負わず、いかなる保証もいたしません。適用されるお客様とOracle Corporationとの間の契約に定めがある場合を除いて、Oracle Corporationおよびその関連会社は、第三者のコンテンツ、製品、サービスへのアクセスまたは使用によって損失、費用、あるいは損害が発生しても一切の責任を負いかねます。

目次

タイトルおよび著作権情報

はじめに

- 対象読者

- ドキュメントのアクセシビリティについて

- 関連ドキュメント

- 表記規則

第I部 Oracle Helpの概要

1 Oracle Helpの概要

- 1.1 Oracle Helpについて

- 1.2 Oracle Help for Java

- 1.3 Oracle Help for the Web

- 1.4 Oracle JDeveloperのOracle Help

- 1.5 Oracle Helpのライセンスおよびサポート

2 Oracle Help for Javaのユーザー・インタフェース

- 2.1 Oracle Help for Javaのユーザー・インタフェースについて

- 2.2 OHJのトピック・ウィンドウ

- 2.3 OHJのナビゲータ・ウィンドウ

- 2.3.1 「目次」タブ

- 2.3.2 「索引」タブ

- 2.3.3 「検索」タブ

- 2.3.4 「お気に入り」タブ

- 2.3.5 カスタム・ナビゲータ・タブ

- 2.4 ヘルプセットのマージ

- 2.4.1 目次のマージ

- 2.5 その他のOHJ機能

- 2.5.1 アクセシビリティ機能

- 2.5.2 国際化機能

- 2.5.3 Java Foundation Class (JFC)のSwingコンポーネント

- 2.5.4 オープンでプラガブルなアーキテクチャ

3 Oracle Help for the Webのユーザー・インタフェース

- 3.1 Oracle Help for the Webのユーザー・インタフェースについて

- 3.2 OHWのグローバル・ツールバー

- 3.3 OHWの「目次」ナビゲータ

- 3.4 OHWの「索引」ナビゲータ

- 3.5 OHWの「検索」ナビゲータ

- 3.6 OHWのトピック・ペイン

- 3.7 その他のOHW機能

- 3.7.1 OHWバージョン情報機能

- 3.7.2 ブックマーク機能

- 3.7.2.1 下位互換性

- 3.7.3 単一ペイン・レイアウト機能

第II部 Oracle Helpのファイル形式

4 Oracle Helpのファイル形式の概要

- 4.1 Oracle Helpのファイル形式について

- 4.2 ファイル名の拡張子

5 メタデータ・ファイル

- 5.1 メタデータ・ファイルについて

- 5.2 ヘルプセット・ファイル

- 5.2.1 <helpset>要素

- 5.2.2 <title>要素

- 5.2.3 <maps>要素

- 5.2.4 <wintype>要素

- 5.2.5 <links>要素

- 5.2.6 <view>要素

- 5.2.6.1 データ・ビュー・タイプおよびエンジン

- 5.2.7 <subhelpset>要素

- 5.2.8 サンプルのヘルプセット・ファイル

- 5.3 マップ・ファイル

- 5.3.1 マップ・ファイルの要素

6 ヘルプ情報ファイル

- 6.1 ヘルプ情報ファイルについて

- 6.2 目次ファイル

- 6.2.1 TOCの要素

- 6.3 マスター目次

- 6.3.1 マスター目次の構成方法

- 6.4 索引ファイル

- 6.4.1 索引の要素

- 6.5 検索索引ファイル

- 6.6 リンク・ファイル

- 6.6.1 リンク・ファイルの要素

7 トピック・ファイル

- 7.1 トピック・ファイルについて

- 7.2 トピックIDリンク

- 7.3 関連リンク

- 7.4 カスタム・プロトコル・リンク

- 7.5 ポップアップ

- 7.6 トピックID

- 7.7 ウィンドウ・タイプ

- 7.8 ファイルへのトピックIDの動的マッピング

- 7.8.1 oracle.help.engine.XMLMapFixedConventionEngineヘルプ・エンジン

- 7.8.2 oracle.help.engine.XMLMapConventionEngineヘルプ・エンジン

- 7.8.3 動的マッピングの最適化

第III部 Oracle Helpのオーサリング

8 Oracle Help for the Web構成ファイル

- 8.1 Oracle Help for the Web構成ファイルについて

- 8.2 <helpConfiguration>要素

- 8.2.1 debugMode属性

- 8.3 <brandings>要素

- 8.3.1 国際化のベスト・プラクティス

- 8.4 <locales>要素

- 8.4.1 <locale>の子要素<books>

- 8.4.2 <contentLocation>要素

- 8.4.3 サンプルの<locales>セクション

- 8.5 ヘルプセット間でのリソースの共有

- 8.6 <parameters>要素

- 8.7 <navigatorAliases>要素

- 8.8 カスタム・プロトコル・リンク

- 8.9 埋込みヘルプを含むヘルプセットの事前ロード

- 8.10 実行時のOracle Help for the Web構成ファイルのリロード

- 8.10.1 実行時のOracle Help for the Web構成ファイルのリロード方法

9 Oracle Helpシステムのオーサリング

- 9.1 Oracle Helpシステムのオーサリングについて

- 9.2 Oracle Help for Javaに付属のオーサリング・ユーティリティ

- 9.3 埋込みヘルプのオーサリング

- 9.3.1 HTMLファイル

10 ヘルプセット・オーサリング・ウィザード

- 10.1 ヘルプセット・オーサリング・ウィザードについて

- 10.2 ウィザードの起動

- 10.3 ヘルプセット・ファイルの作成

- 10.4 オーサリング・ツールとHTMLブラウザの指定

- 10.5 ソース・ディレクトリの指定

- 10.6 ビューの定義

- 10.6.1 新しいビューの定義

- 10.6.2 カスタム・ビュー・タイプの定義

- 10.6.3 カスタム・データ・エンジンの定義

- 10.7 全文検索ビューの定義

- 10.8 マップ・ファイルの定義

- 10.9 関連リンクの変換

- 10.10 ポップアップ・ウィンドウ・リンクの変換

- 10.11 ウィンドウ・タイプの定義

- 10.11.1 ウィンドウの識別情報

- 10.11.2 配置の属性

- 10.11.3 スタイルの属性

- 10.11.4 ツールバー・ボタン

- 10.12 ヘルプセットの作成

11 テキスト検索インデクサの使用方法

- 11.1 テキスト検索インデクサについて

- 11.2 Javaの要件

- 11.3 インデクサの実行

- 11.4 JapaneseIndexerの実行

第IV部 Oracle Help for Java

12 Oracle Help for Java Developer's Kitの概要

- 12.1 Oracle Help for Java Developer's Kitについて

- 12.2 JDeveloperのOracle Help for Javaランタイム

- 12.3 OHJDKを使用する前に

- 12.3.1 OHJDKのインストール

- 12.3.2 OHJDKリリースの内容

- 12.3.2.1 OHJエンジン

- 12.3.2.2 オーサリング・ツール

- 12.3.2.3 デモンストレーション・ファイル

- 12.3.2.4 ドキュメント

- 12.3.3 OHJDK開発のためのJava CLASSPATHの設定

13 アプリケーションへのOHJの追加

- 13.1 アプリケーションへのOHJの追加について

- 13.2 Helpオブジェクトの構成

- 13.3 ヘルプ・データの追加

- 13.3.1 HelpSetの構成

- 13.3.2 ヘルプへのブックの追加

- 13.4 「お気に入り」タブまたはカスタム・タブの追加

- 13.5 Helpオブジェクトをいつ作成するか

- 13.6 ナビゲータ・ウィンドウの表示

- 13.7 トピックの表示

- 13.7.1 TopicDisplayExceptionsのキャッチ

- 13.8 Helpオブジェクトの破棄

14 アプリケーションでの状況依存ヘルプの有効化

- 14.1 状況依存ヘルプについて

- 14.2 ヘルプ・トピックへのトピックIDのマップ

- 14.3 状況依存ヘルプをサポートするためのアプリケーションのプログラミング

- 14.4 CSHManagerを使用した状況依存ヘルプの実装

- 14.4.1 CSHManagerコンストラクタ

- 14.4.2 デフォルト・ブックの設定

- 14.4.3 トピックIDのユーザー・インタフェース・コンポーネントとの関連付け

- 14.4.4 コンポーネントのヘルプの明示的な表示

15 OHJヘルプ・システムのデプロイ

- 15.1 サポートされているJava仮想マシン

- 15.2 同梱する必要があるOHJ JARファイル

- 15.3 JARに含まれる圧縮ヘルプ・コンテンツのデプロイ

- 15.3.1 JARファイルの作成

- 15.3.2 使用するBookコンストラクタ

第V部 Oracle Help for the Web

16 OHWのデモ・ファイルのデプロイ

- 16.1 OHWのデモ・ファイルのデプロイについて

- 16.2 OHWのデモ・ファイルの理解

- 16.3 スタンドアロンOracle WebLogic ServerへのOHWデモEARファイルのデプロイ

- 16.4 JDeveloperが統合されたOracle WebLogic ServerへのOHWデモEARファイルのデプロイ

- 16.5 OHWのデモEARファイルの実行

17 OHWのデプロイメントの理解

- 17.1 OHWのデプロイメントについて

- 17.2 要件および依存性の検証

- 17.3 OHWライブラリ・ファイルの検証

- 17.4 OHWのアーティファクトのインストール

- 17.5 OHW構成ファイルの理解

- 17.6 OHWでのカスタム・ヘルプセットの表示の構成

- 17.7 OHWのアクセスURLの変更

- 17.7.1 アクセスURLの最後のURL要素の変更

- 17.7.2 アクセスURLの名前の変更

- 17.8 スタンドアロンWebアプリケーションとしてのOHWのデプロイ

- 17.8.1 OHWのアーティファクトのインストール

- 17.8.2 スタンドアロンWebアプリケーションとしてのOHWの構成

- 17.9 Webアプリケーションの一部としてのOHWのデプロイ

- 17.9.1 OHWのアーティファクトのインストール

- 17.9.2 Webアプリケーションの一部としてのOHWの構成

- 17.10 1つのWebアプリケーションへの複数ヘルプ・インスタンスのデプロイ

- 17.10.1 アプリケーションおよびOHWの構成ファイルの設定

- 17.10.2 アプリケーションの実行

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

- 18.1 Webアプリケーションでの状況依存ヘルプの実装について

- 18.2 ヘルプ・トピックへのトピックIDのマップ

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

- 18.3.1 フロント・メイン・ページへのリンク

- 18.3.2 トピックへのリンク

- 18.3.3 ロケールおよびグループの指定

19 ADFリッチ・クライアントのヘルプ・プロバイダ

- 19.1 ADFリッチ・クライアントのヘルプ・プロバイダについて

- 19.2 オンライン・ヘルプとADF Facesアプリケーションの統合

- 19.3 ADFリッチ・クライアントのヘルプ・プロバイダとしてのOHWの登録

- 19.4 HelpTopicId属性の使用

- 19.5 その他のヘルプ・プロバイダの使用

A Oracle HelpおよびJavaHelpのファイル形式

- A.1 ヘルプセット・ファイル

- A.2 マップ・ファイル

- A.3 目次ファイル

- A.4 索引ファイル

- A.5 検索索引ファイル

- A.6 リンク・ファイル

- A.7 OHW構成ファイル

B Javaモーダル・ウィンドウの問題への対処

- B.1 Javaモーダル・ウィンドウの問題について

- B.2 ウィンドウの登録

- B.3 ウィンドウの登録解除

C ヘルプ・ブックの処理

- C.1 ヘルプ・ブック・ファイル名の拡張子

- C.2 OHJへのHelpデータの追加

- C.2.1 ヘルプ・ブックの構築

- C.2.2 ヘルプへのブックの追加

- C.3 Oracle Help for the Web構成ファイルのロケール

- C.3.1 <locale>の子要素である<books>

- C.3.2 <contentLocation>要素

D Oracle Help for the Web-UIX

- D.1 Oracle Help for the Web-UIXについて

- D.2 OHW-UIXユーザー・インタフェース

- D.2.1 OHW-UIXの目次

- D.2.2 OHW-UIXの索引

- D.2.3 OHW-UIXの検索

- D.2.4 OHW-UIXのトピック

- D.3 OHW-UIXのデモ・ファイルのデプロイ

- D.3.1 OHW-UIXのデモ・ファイルの理解

- D.3.2 Oracle WebLogic ServerでのOHW-UIXのデモEARファイルのインストール

- D.3.3 Oracle JDeveloperを使用したOHW-UIXのデモEARファイルのインストール

- D.3.4 OHW-UIXのデモEARファイルの実行

- D.4 OHW-UIXのデプロイの理解

- D.4.1 要件および依存性の検証

- D.4.2 OHW-UIX構成ファイルの理解

- D.4.3 OHW-UIXでのカスタム・ヘルプセットの表示の構成

- D.4.4 OHW-UIXのアクセスURLの変更

- D.4.4.1 アクセスURLの最後のURL要素の変更

- D.4.4.2 アクセスURLの名前の変更

- D.4.5 OHW-UIXおよびUIXのアップグレード

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

- D.5.1 ヘルプ・トピックへのトピックIDのマップ

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

- D.5.2.1 フロント・ページへのリンク

- D.5.2.2 トピックへのリンク

- D.5.2.3 ロケールの指定

- D.5.3 Oracle UIXベースのアプリケーションでの状況依存ヘルプの実装

- D.5.3.1 OracleHelpProviderへのOHW-UIXの登録

- D.5.3.2 リンク先のデータ・バインディング

- D.6 OHW-UIXヘルプ・システムのOHWヘルプ・システムへのアップグレード

はじめに

このマニュアルでは、Oracle Helpを使用して、JavaアプリケーションおよびWebアプリケーションのHTMLに基づくヘルプ・システムを開発、表示する方法について説明します。

対象読者

このマニュアルは、Java環境とWeb環境の両方で表示可能な単一のヘルプ・システムの作成を検討している作成者を対象としています。

ドキュメントのアクセシビリティについて

オラクル社のアクセシビリティについての詳細情報は、Oracle Accessibility ProgramのWebサイトhttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=docaccを参照してください。

Oracleサポートへのアクセス

サポートをご購入のOracleのお客様は、My Oracle Supportにアクセスして電子サポートを受けることができます。詳細は、http://www.oracle.com/pls/topic/lookup?ctx=acc&id=infoまたはhttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs(聴覚障害者向け)を参照してください。

関連ドキュメント

関連情報の詳細は、Oracle Help Technologies(http://www.oracle.com/technetwork/topics/index-083946.html)を参照してください。

表記規則

このマニュアルでは次の表記規則を使用します。

規則

意味

太字

太字は、操作に関連するグラフィカル・ユーザー・インタフェース要素、または本文中で定義されている用語および用語集に記載されている用語を示します。

イタリック

イタリックは、ユーザーが特定の値を指定するプレースホルダ変数を示します。

固定幅フォント

固定幅フォントは、段落内のコマンド、URL、サンプル内のコード、画面に表示されるテキスト、または入力するテキストを示します。

第1部

Oracle Helpの概要

この部では、Oracle Helpの概要について説明します。次の章で構成されます。

- 第1章「Oracle Helpの概要」
この章では、Oracle Helpの概要について説明します。

- 第2章「Oracle Help for Javaのユーザー・インタフェース」
この章では、Oracle Help for Javaのユーザー・インタフェース・コンポーネントについて説明します。

- 第3章「Oracle Help for the Webのユーザー・インタフェース」
この章では、Oracle Help for the Webのユーザー・インタフェース・コンポーネントについて説明します。

1 Oracle Helpの概要

この章では、Oracle Helpのテクノロジ(Oracle Help for JavaおよびOracle Help for the Web)を紹介します。また、Javaベースの環境アプリケーションとWebアプリケーションについて、HTMLベースのヘルプ・システムを開発および表示する場合の概要についても説明します。

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

- Oracle Helpについて

- Oracle Help for Java

- Oracle Help for the Web

- Oracle JDeveloperのOracle Help

- Oracle Helpのライセンスおよびサポート

1.1 Oracle Helpについて

Oracle Helpテクノロジは、Oracle Help for JavaとOracle Help for the Webの2つのカテゴリに分けられます。作成者は、Oracle Help for Java (OHJ)を使用するJava環境とOracle Help for the Webを使用するWeb環境の両方で、変更なしで表示可能な1つのヘルプ・システムを作成できます。または、Oracle Help for Javaのみを使用してJava環境用アプリケーションのヘルプを作成し、Oracle Help for the Webのみを使用してWeb環境用アプリケーションのヘルプを作成することもできます。Oracle Help for the Webには、Oracle Help for the WebとOracle Help for the Web-UIXの2つのバージョンがあります。

このガイドでは、説明内容がOracle Help for JavaとOracle Help for the Webの両方に該当する場合は、Oracle Helpと表記します。OHJは、説明内容がOracle Help for Javaにのみ該当する場合に使用します。OHWは、説明内容がOracle Help for the Webにのみ該当する場合に使用します。

1.2 Oracle Help for Java

Oracle Help for Javaは、HTMLに基づくヘルプ・コンテンツをJava環境で開発して表示するためのJavaコンポーネント、Java API、ファイル形式の仕様のセットです。OHJは、基本的にJavaアプリケーションでヘルプを表示するように設計されていますが、Java環境で使用するスタンドアロン・ドキュメント・ビューアとして実装することもできます。

Oracle Help for Java Developer's Kit (OHJDK)には、OHJテクノロジとともにJavaアプレットおよびアプリケーションの状況依存ヘルプを開発するためのツールとドキュメントが含まれています。次のものが必要となります。

- Javaコンポーネント: OHJには、目次、索引、検索およびトピック・ウィンドウを持つ完全なヘルプ・システムを構成するデフォルトのJavaユーザー・インタフェース・コンポーネントが含まれます。

- API: OHJ APIには、状況依存ヘルプの実装、ヘルプの表示方法(サイズ、位置など)の制御、およびヘルプ・システムのカスタマイズと拡張を行う機能が含まれます。たとえば、デフォルトのコンポーネントを独自のコンポーネントと置き換えたり、カスタム・コントロールを作成したり、選択したコンポーネントをアプリケーションに埋め込むことができます。

- ドキュメント: ドキュメントには、この開発者ガイドおよびAPIリファレンス(JavaDocドキュメントとして提供されます)があります。

- ヘルプセット・オーサリング・ウィザード: ヘルプセット・オーサリング・ウィザードを使用すると、サード・パーティのオーサリング・ツールを使用することなく、Oracle Help制御ファイルを作成できます。

OHJ機能の詳細は、第2章「Oracle Help for Javaユーザー・インタフェース」を参照してください。

1.3 Oracle Help for the Web

Oracle Help for the Web(リッチ・インタフェースを備えているため、Oracle Help for the Web – Rich Client (OHW-RC)とも呼ばれる)は、Web環境でHTMLベースのヘルプ・コンテンツを配信します。これは、Java Server Faces (JSF)テクノロジに基づいたOracle Application Developer Framework (ADF)を使用して、オラクル社のBrowser Look And Feel Plus (BLAF+)動作とガイドラインに準拠したユーザー・インタフェースを構築します。

Oracle Help for the Webは、次のような様々な状況で使用できます。

- リッチ・クライアント・アプリケーションに状況依存ヘルプを新しいブラウザ・ウィンドウで提供するヘルプ・システムとして

- 公開Webサイト上のヘルプ・コンテンツのスタンドアロン・ドキュメント・ビューアとして

- ユーザーが一般的な検索エンジンで検索し、その結果が索引付けされたOracle Help for the Webコンテンツにリンクされている場合

- ADF Facesコンポーネントの実行時実装で、このコンポーネントが定義するHelpProviderインタフェースを使用して埋込みヘルプ情報(定義テキスト、方法テキストまたはフル・ヘルプ)を取得する必要がある場合

Oracle Help for the Webに含まれる内容は、次のとおりです。

- Oracle Help for the Webフロント・サーブレット: Webサーバーにインストールされます。これにより、Oracle Help for the Webは、状況依存ヘルプ・リクエストに対するURL構文をサポートできます。また、これを使用すると、単一のWebアプリケーションで複数のOracle Help for the Webヘルプセットをサポートする簡単な構成も可能になります。

- Oracle Help for the Webサーブレット・フィルタ: JSFサーブレットに送信されるリクエストの前処理に使用されます。

- ドキュメント: ドキュメントにはこの開発者ガイドも含まれます。

1.4 Oracle JDeveloperのOracle Help

JDeveloperには、内部のJDeveloperヘルプ・システム自体に使用するものに加えて、Oracle Help for Javaランタイム・ライブラリが含まれているため、JDeveloperを使用してJavaアプリケーションを開発している場合は、Javaヘルプ・システム・テクノロジとしてOHJを簡単に組み込むことができます。詳細は、第12章「Oracle Help for Java Developer's Kitの概要」を参照してください。

JDeveloperには、Oracle Help for the Webは含まれていません。これを含む完全なOracle Help for Java開発キットは、Oracle Technology Network (OTN)で入手できます。

1.5 Oracle Helpのライセンスおよびサポート

お客様とソフトウェア・コミュニティへのサービスの一環として、オラクル社ではOracle Helpのソフトウェアとサポートを無償で提供しています。Oracle Helpソフトウェアには、Oracle Help for JavaおよびOracle Help for the Webが含まれます。

Oracle Helpは無料で提供され、ご自身のアプリケーションのヘルプ・システムとして再配布できます。詳細は、このリリースのライセンス情報を参照してください。

ご質問は、Oracle Technology NetworkのOracle Help Technologies Forumに投稿してください。

2 Oracle Help for Javaのユーザー・インタフェース

この章では、Oracle Help for Javaのユーザー・インタフェース・コンポーネントについて説明します。このコンポーネントには、ナビゲータ・ウィンドウ、トピック・ウィンドウ、索引タブ、検索タブ、お気に入りタブなどがあります。

この章には、次のセクションがあります。

- Oracle Help for Javaのユーザー・インタフェースについて

- OHJのトピック・ウィンドウ

- OHJのナビゲータ・ウィンドウ

- ヘルプセットのマージ

- その他のOHJ機能

2.1 Oracle Help for Javaのユーザー・インタフェースについて

Oracle Help for Java (OHJ)のユーザー・インタフェースは、「ヘルプ・ナビゲータ」ウィンドウとヘルプ・トピック・ウィンドウの2つの主要部分で構成されます。「ヘルプ・ナビゲータ」ウィンドウには、トピックを検索するためのコントロールが用意され、ヘルプ・トピック・ウィンドウにはHTMLコンテンツが表示されます。

図2-1 「ヘルプ・ナビゲータ」ウィンドウとヘルプ・トピック・ウィンドウ

ユーザーは、図2-1に示すようにウィンドウのドッキングを解除してペインを別個のウィンドウとして表示したり、図2-2に示すようにウィンドウをドッキングして1つのウィンドウ内に表示したりできます。

図2-2 ドッキングされたウィンドウ

2.2 OHJのトピック・ウィンドウ

OHJのヘルプ・トピック・ウィンドウ(ドッキングされている場合はトピック・ペイン)は、HTMLコンテンツを表示します。図2-3に、様々なタイプのHTMLコンテンツが表示されたトピック・ウィンドウを示します。

図2-3 トピック・ウィンドウ

OHJDKに含まれるデフォルトのHTML表示コンポーネントは、ICEsoft Technologies社製のICEbrowserを特別に実装したものです。ブラウザとそのサポート対象テクノロジの詳細は、http://www.icesoft.comを参照してください。このコンポーネントは、OHJを使用するヘルプ・システムの一環で使用される場合は無償で使用および再配布が可能です。このHTML表示コンポーネントでは、次の内容をサポートします。

- HTML 4.0

- Cascading Style Sheets (CSS) 1およびほとんどのCSS 2。CSS 3はサポートされません。

- Javaアプレット

- Java Media Framework 2.0がサポートするマルチメディア。

- JavaScript

- スクリーン・リーダー・ソフトウェアのサポート

- 単一トピックおよび複数トピックの印刷

- GIFアニメーション

- HTMLを使用したポップアップのサポート

- 関連リンク。単一の索引語またはフレーズを複数のトピックと関連付けることができます。ユーザーがこのようなリンクのいずれかを選択すると、そのリンクに関連付けられているトピックの一覧が表示され、ユーザーはそのリストからトピックを選択できます。

- 作成者定義のウィンドウ・タイプ。作成者は背景、テキスト、リンクなどの色、ウィンドウのサイズと位置、ウィンドウのタイトル、ツールバー・ボタンを指定できます。

- トピックIDリンク。ハイパーリンク・ターゲットは、URLではなくIDで指定されます。

- 目次の項目との同期

デフォルトのHTML表示の使用は必須ではありません。別のHTML表示コンポーネントに置き換えることが可能です。また、アプリケーションとヘルプ・システムをWebブラウザのアプレットとして実行する場合は、トピック・ウィンドウとしてブラウザのウィンドウを使用できます。このように、実装されたOHJの表示機能は、作成者が選択してシステムに埋め込むHTML表示に依存します。

2.3 OHJのナビゲータ・ウィンドウ

ナビゲータ・ウィンドウは、ヘルプ・システムのトピックを移動および検索するためのタブで構成されるコントロールです。デフォルトでは、ナビゲータ・ウィンドウには、「目次」、「索引」および「検索」のタブがあります。作成者は、ヘルプ・システムにパラメータを設定することで、ナビゲータ・ウィンドウの複数の特徴を簡単に制御できます。たとえば、タブのラベルの変更やアイコンの追加が可能です。また、複数の目次(製品ヘルプの目次やチュートリアルの目次など)を表示することもできます。より複雑なシステムの場合、Javaプログラマはカスタム・タブを作成でき、作成者はそれらをナビゲータ・ウィンドウに追加できます。

この節の内容は以下のとおりです。

- 第2.3.1項「「目次」タブ」

- 第2.3.2項「「索引」タブ」

- 第2.3.3項「「検索」タブ」

- 第2.3.4項「「お気に入り」タブ」

- 第2.3.5項「カスタム・ナビゲータ・タブ」

2.3.1 「目次」タブ

「目次」タブには、トピックが階層ツリー形式で表示されます。ツリーのコンテンツと構造は、作成者が指定します。ツリーの定義には、複数のファイル形式がサポートされています。

図2-4 ナビゲータ・ウィンドウの「目次」タブ

ユーザーが目次のトピック・タイトルをダブルクリックすると、そのトピックがトピック・ウィンドウに表示されます。また、ツールバーのボタンを選択するか、右クリックすると表示されるポップアップ・メニューでコマンドを選択することにより、ユーザーはトピックを新しい別のトピック・ウィンドウに表示できます。

目次ビューには次の機能があります。

- 目次で選択される(ハイライトされた)項目は、トピック・ウィンドウに表示されたトピックに自動的に同期されます。たとえば、トピックでハイパーリンクをクリックして新しいトピックにジャンプすると、目次での選択項目が前のトピックから新しいトピックに変わります。

- 階層レベルの数に制限はありません。

- ナビゲータ・ウィンドウの項目リストは印刷できます。

2.3.2 「索引」タブ

「索引」タブには、トピックの関連キーワードのアルファベット順リストが表示されます。キーワードはヘルプの作成者が定義し、目次と同様、リストの指定に複数のファイル形式がサポートされています。

図2-5 ナビゲータ・ウィンドウの「索引」タブ

図2-5の数字のコールアウトは、次のユーザー・インタフェース・コンポーネントを示します。

1. テキスト入力フィールド: ユーザーは単語または句をこのフィールドに入力します。

2. キーワード・リスト: ユーザーが入力すると、リスト内のキーワードのうち、入力された文字列に一致する最初のキーワードが選択されます。入力する文字が多いほど、より正確な選択が行われます。リストからキーワードを選択することもできます。

3. トピック・リスト: このリストには、キーワード・リストで選択されたキーワードに関連付けられているすべてのトピックのタイトルが表示されます。表示されたタイトルのいずれかをユーザーがダブルクリックすると、そのトピックがトピック・ウィンドウに表示されます。トピックを選択して「開く」をクリックしても表示されます。

索引には次のような便利な機能が用意されています。

- 1つのキーワードを複数のトピックに関連付けたり、複数のキーワードを1つのトピックに関連付けできます。

- 索引の階層は2レベルまでサポートされます。

- ヘルプセットをマージすると、統合された1つの索引が作成され、索引全体がアルファベット順にソートされます。つまり、エントリは単に結合されるのではなく、マージされ、再ソートされます。

- 作成に使用された言語以外の言語に変換された索引は、適切なアルファベット順にソートされます。

- まったく同じエントリは縮小され、1つのみが表示されます。

2.3.3 「検索」タブ

「検索」タブには、ユーザーがテキストを入力して「検索」を選択できるテキスト・フィールドが表示されます。コンテンツに該当の語やフレーズが含まれるトピックのタイトルは、タブの下部にある結果リストに表示されます。ユーザーがタイトルをダブルクリックすると、そのトピックがトピック・ウィンドウに表示されます。

図2-6 ナビゲータ・ウィンドウの「検索」タブ

図2-6の数字のコールアウトは、次のユーザー・インタフェース・コンポーネントを示します。

1. 検索テキスト: ユーザーは単語(複数可)をこのフィールドに入力します。完全一致する句を検索する場合は、検索対象の句を二重引用符で囲みます。

2. 大/小文字の区別: このチェック・ボックスを選択すると、ユーザーが入力した語と大/小文字が一致する語を検索できます。

3. 検索: 入力したすべての語を含むか、いずれかの語を含むか、ブール式(AND、OR)を使用した検索を行うかを指定するためのオプション・ボタンが用意されています。

4. トピック・リスト: 検索条件に一致する各トピックの「ランク」、「トピック・タイトル」および「ソース」を表示する検索結果領域です。「ランク」列には、検索条件にどの程度よく一致したかに基づくトピックのランキングが示されます。すべての列をアルファベットの昇順または降順にソートできます。デフォルトでは、すべてのトピックが「ランク」でソートされます。ユーザーが特定の結果を選択すると、関連付けられているトピックがトピック・ペインに表示されます。

ユーザーは検索時に次のオプションを設定できます。

- 検索キーワードの大文字と小文字の区別を有効または無効にします。

- 検索語をすべて含むトピックまたは1つでも含んでいるトピックを表示します。

- ブール式(AND、OR)に基づいて検索します。

「検索」タブには次のような便利な機能が用意されています。

- 結果は、検索条件にどの程度よく一致したかに基づいてランク付けされます。

- 前に入力した検索条件は保存され、ドロップダウン・リストに表示されます。

- 結果には、トピックのタイトルとそのソースが表示されます。

- ユーザーは、ランク、トピック・タイトルまたはトピック・ソースで結果をソートできます。

検索データベースは、ヘルプ・システムのオーサリング時に生成されます。OHJDKおよびOHJをサポートするその他のオーサリング・ツールには、このデータベースを生成するテキスト検索インデクサと呼ばれるユーティリティが付属しています。検索データベースは、Oracle定義のファイル形式を使用します。検索をクライアントに実装すると、この検索データベースが常に使用されます。独自の検索をサーバーに実装することもできます。たとえば、トピックをOracleデータベースに格納した場合、検索の実行にデータベースのテキスト処理機能を使用できます。

テキスト検索インデクサの詳細は、第11章「テキスト検索インデクサの使用方法」を参照してください。

注意:
OHJの使用にOracleデータベースは必須ではありません。

2.3.4 「お気に入り」タブ

ユーザーは「お気に入り」ナビゲータを使用すると、Webブラウザのお気に入り機能のように、ヘルプセットのトピックをお気に入りとしてマークできます。

図2-7 ナビゲータ・ウィンドウの「お気に入り」タブ

ユーザーはヘルプセットのお気に入りのトピックを指定して管理できます。

- お気に入りのトピックの追加と削除

- フォルダやサブフォルダの作成

- 現在のトピック名のデフォルト・トピック・タイトル名からの変更

ユーザーは「お気に入り」ナビゲータ機能にヘルプ・トピック・ウィンドウの「ツール」メニューからアクセスできます。この場合、お気に入りの追加ダイアログ・ボックスが表示されます。また、「お気に入り」ナビゲータでお気に入りを右クリックしてもアクセスできます。

注意:
「目次」、「検索」または「索引」とは異なり、「お気に入り」ナビゲータを表示するにはメソッドenableFavoritesNavigator() URLを呼び出し、URLにお気に入り情報を格納するファイルfavorites.xmlを指定します。詳細は、第13.4項「「お気に入り」タブまたはカスタム・タブの追加」を参照してください。

2.3.5 カスタム・ナビゲータ・タブ

OHJ APIには数多くの機能が用意されていますが、その1つとして、デフォルトのOHJユーザー・インタフェースをカスタマイズできます。たとえば、ナビゲータとも呼ばれるカスタム・タブをJavaでプログラムし、それをナビゲータ・ウィンドウに追加できます。図2-8に、カスタム・タブ「Product Education」を示します。

図2-8 ナビゲータ・ウィンドウのカスタム・ナビゲータ・タブ

2.4 ヘルプセットのマージ

ヘルプ・トピックとそれに関連付けられている制御ファイルのコレクションをヘルプセットと呼びます。ヘルプセットは実行時にマージできます。つまり、複数の作成者が、作成の完了後にシームレスにマージされる複数のヘルプセットを作成できます。同様に、システム全体を変更せずに、新しいコンポーネントをユーザーのヘルプ・システムに追加できます。

ヘルプセットのマージをサポートする機能は次のとおりです。

- 「目次」ナビゲータは、マージされたすべてのヘルプセットのコンテンツを含む1つのツリーにヘルプセットをマージします。現時点のOracle Help for JavaおよびOracle Help for the Webでは、「目次」ナビゲータは、ラベルが同じでターゲットが競合しないツリー・ノードをすべてマージします。

- 索引には、すべてのヘルプセットの索引エントリが、適切にソートされて表示されます。

- テキスト検索では、マージされたすべてのヘルプセットが検索対象になります。

- 作成者は、選択したヘルプセットをツールバーのドロップダウン・リストに表示することを選択できます。これにより、複雑なヘルプ・システムのユーザー表示が簡素化されます。

図2-9 選択リストに表示されるマージされたヘルプセット

この実装を使用すると、「目次」タブと「索引」タブには、リストで選択されているヘルプセットの項目のみ表示されます。「検索」でのテキスト検索では、選択したヘルプセットの項目のみ検索されます。

- 作成者が関連リンクを指定した場合、リンクに関連付けられたトピックのリストには、マージされたヘルプセットの項目が含まれます。

2.4.1 目次のマージ

Oracle Help for JavaおよびOracle Help for the Webは、どちらも複数のヘルプセットのTOCファイルをマージして1つのツリーを作成する処理をサポートします。複数のテーブルをマージしてできるTOCは、すべてのツリーを重ね合せた結果に相当します。複数のTOCに同じノード(テキストとターゲット・トピックIDが同じノード)が含まれている場合、そのようなノードは組み合され、元のノードの子をすべて持つ1つのノードになります。

次に示すtoc1.xmlおよびtoc2.xmlを使用する2つのヘルプセットがある場合のシナリオについて考えてみます。

toc1.xml

<?xml version='1.0'?>
<toc version="1.0">
<tocitem text="1" target="1_topic" />
<tocitem text="2" target="2_topic" >
<tocitem text="2.1" target="2.1_topic" />
<tocitem text="2.2" target="2.2_topic" />
</tocitem>
<tocitem text="3" target="3_topic" />
</toc>

toc2.xml

<?xml version='1.0'?>
<toc version="1.0">
<tocitem text="2" target="2_topic" >
<tocitem text="2.2" target="2.2_topic">
<tocitem text="2.2.1" target="2.2.1_topic" />
<tocitem text="2.2.2" target="2.2.2_topic" />
</tocitem>
</tocitem>
</toc>

図2-10に、toc1.xmlとtoc2.xmlをマージした結果のTOCを示します。どちらにおいても、text=2である<tocitem>項目のターゲットが2_topicであるため、2のノードは1つしかありません。text=2.2であるノードについても同様です。

図2-10 マージの結果

この例では、ヘルプセットの「目次」ナビゲータを定義する<view>要素にタイトルがないと想定しています。「目次」ナビゲータの<view>に<title>が含まれている場合、toc.xmlファイルで定義されたすべての<tocitem>項目の親ノードとしてそのタイトルが使用されます。詳細は、第5章「メタデータ・ファイル」を参照してください。

2.5 その他のOHJ機能

このマニュアルの他では触れられていないOracle Help for Java (OHJ)機能には次のようなものがあります。

- アクセシビリティ機能

- 国際化機能

- Java Foundation Class (JFC)のSwingコンポーネント

- オープンでプラガブルなアーキテクチャ

2.5.1 アクセシビリティ機能

OHJのアクセシビリティ機能は次のとおりです。

- デフォルトHTML表示コンポーネント(ICEbrowser)も含め、すべてのユーザー・インタフェース機能にキーボードでアクセスできます。このアクセシビリティ機能をサポートするため、OHJに付属のICEbrowserにはOracleによる変更が加えられています。

- OHJおよびICEbrowserの最新バージョンは、Freedom Scientific社のJAWS for Windows Screen Readerを使用して動作確認されています。このソフトウェアの詳細は、http://www.freedomscientific.comを参照してください。

2.5.2 国際化機能

OHJの国際化機能は次のとおりです。

- ユーザー・インタフェースのすべてのテキスト文字列はリソース・ファイルに格納されており、翻訳が容易になっています。

- ロケールおよびエンコーディングはプログラムで設定できます。

- デフォルトのHTML表示コンポーネント(ICEbrowser)は、空白区切りでない言語の折返しをサポートしています。

- ヘルプ作成者は、(デフォルトのICEbrowser HTML表示コンポーネントを使用する場合に)HTMLファイルのcharsetをIANAキャラクタ・セット・エンコーディング名を使用して設定できます。

- OHJユーザー・インタフェースは、Oracleによっていくつかの言語に翻訳されています。

2.5.3 Java Foundation Class (JFC)のSwingコンポーネント

OHJ Helpシステムの実装には、Java Foundation Class (JFC)のSwingコンポーネントが使用されています。

2.5.4 オープンでプラガブルなアーキテクチャ

OHJのアーキテクチャは、オープンでプラガブルです。つまり、検索機能やHTML表示コンポーネントなどのデフォルト・コンポーネントを独自のコンポーネントに置き換えることができます。また、ナビゲータ・タブやHTML表示などのコンポーネントをアプリケーションのユーザー・インタフェースに埋め込み、完全に統合されたヘルプを構成できます。

OHJアプリケーションのクラス・ファイル、制御ファイルおよび目次ファイルはすべてカプセル化して、JAR (Java Archive)ファイルに圧縮できます。ヘルプ・システムを実行する場合、これらのファイルをJARから取り出す必要はありません。

3 Oracle Help for the Webのユーザー・インタフェース

この章では、Oracle Help for the Webのユーザー・インタフェース・コンポーネントについて説明します。このコンポーネントには、グローバル・ツールバーやトピック・ナビゲータ、索引ナビゲータ、検索ナビゲータなどがあります。

この章には、次のセクションがあります。

- Oracle Help for the Webのユーザー・インタフェースについて

- OHWのグローバル・ツールバー

- OHWの「目次」ナビゲータ

- OHWの「索引」ナビゲータ

- OHWの「検索」ナビゲータ

- OHWのトピック・ペイン

- その他のOHW機能

3.1 Oracle Help for the Webのユーザー・インタフェースについて

Oracle Help for the Web (OHW)のユーザー・インタフェースは、OHJと同じ機能を提供します。ただし、OHWはWebアプリケーションであるため、外観および動作の一部に違いがあります。

図3-1に、Webブラウザに表示されたOHWを示します。

図3-1 Oracle Help for the Webのユーザー・インタフェース

図3-1の番号付きコールアウトは、次のユーザー・インタフェース・コンポーネントを示しています。

1. ナビゲータ領域: ページの左端にある領域で、アコーディオン方式が使用されます。各アコーディオン・パネルが1つのナビゲータを表します。OHWフレームワークには、3つの標準ナビゲータ(「目次」、「索引」および「検索」)があります。OHWインスタンスのナビゲータの正確なセットは、ヘルプセット定義ファイル(.hsファイルなど)によって動的に決まります。

2. ブランド領域: リッチ・クライアント・インタフェースの上部にある領域で、テキスト、イメージまたはその両方を追加できます。通常、この領域では、ヘルプ・コンテンツが特定されるか、または社名やロゴなどの会社情報が表示されます。

3. ツールバー領域: ブランド領域の下に位置します。メイン・メニュー項目、ヘルプセット・スイッチャ(該当する場合)およびクイック検索コントロールを表示します。

4. トピック表示領域: ナビゲータ領域のいずれかのタブでトピックを選択すると、そのトピックのコンテンツがこの領域に表示されます。

ブランド領域を除いて、これらの要素はヘルプセット・ファイルで構成されています。OHWとOHJは、ヘルプセット・ファイルを含め、まったく同じファイル形式を使用します。そのため、既存の制御ファイルを変更することなく、既存のOHJヘルプ・システムをOHWシステムとしてデプロイできます。

OHWシステムのデプロイの詳細は、第16章「OHWデモ・ファイルのデプロイ」を参照してください。

3.2 OHWのグローバル・ツールバー

リッチ・クライアントの上部領域には、ヘルプセット・スイッチャ(該当する場合)、クイック検索コントロール、ページの領域を操作する「表示」メニューおよびツールバーがあります。

図3-2 OHWのグローバル・ツールバー

図3-2の番号付きコールアウトは、次のユーザー・インタフェース・コンポーネントを示しています。

1. ヘルプセット・スイッチャ: OHWアプリケーションで定義されるすべてのヘルプセットを含むドロップダウン・リスト。現在開いているヘルプセットがドロップダウン・ボックスに表示され、ユーザーはこのリストを使用して別のヘルプセットに切り替えることができます。ヘルプセット・スイッチャは、複数の独立したコンテンツのセットがあり、ohwconfig.xmlファイルのcombineBooksパラメータがfalseに設定されている場合のみ表示されます。

2. ヘルプセット内検索: 検索ナビゲータに切り替えることなくクイック検索を実行するためのクイック検索コントロールです。この検索のデフォルトの検索オプションは、大文字/小文字の区別なし、すべての語およびすべてのソースに設定されています。検索ナビゲータが複数ある場合、クイック検索コントロールは表示されません。ヘルプセット・ファイルに、oracle.help.navigator.searchNavigator.SearchNavigatorタイプのナビゲータのビューが複数含まれている場合、複数の検索ナビゲータが存在することがあります。

3. 表示: このメニューには、ヘルプセットの表示および移動を制御するためのコマンド・メニュー項目のリストが表示されます。コマンド項目は、次のように類似した機能ごとにグループ化されています。

- 「読取りペインの最大化」は、ナビゲータ・ペインの展開または縮小を切り替えます。

- 「デフォルトのウィンドウ・レイアウトの復元」は、ペインをデフォルトのレイアウトで再配置します。

- ナビゲータ項目セクションには、使用可能なすべてのナビゲータ・ペイン(「目次」、「索引」、「検索」およびカスタム・ナビゲータ(該当する場合))に移動するためのコマンド項目が含まれます。

- このトピック・ページのブックマーク可能なリンクの表示は、現在のトピックの永続リンクを含むポップアップを表示します。これを使用してブックマークを作成できます。

4. ツールバーには次のボタンが含まれています。

1. 前のトピックに戻る: 以前表示したトピックを再度開きます。

2. 次のトピックに進む: このトピックの前に表示していたトピックを再表示します。

3. このトピック・ページの印刷: 現在のトピックを印刷します。

4. このトピック・ページへのEメール・リンク: デフォルトの電子メール・アプリケーションを開き、現在のトピックのURLをメッセージ本文に、トピック・タイトルを件名フィールドにコピーします。

5. このトピック・ページの永続リンクの表示は、現在のトピックの永続リンクを含むポップアップを表示します。これを使用してブックマークを作成できます。

また、ペインの縮小ボタンを使用すると、ツールバーを非表示にしてトピック・ペインを最大化します。

3.3 OHWの「目次」ナビゲータ

「目次」ナビゲータには、トピックが階層ツリー形式で表示されます。ツリーのコンテンツと構造により、ロードされたヘルプセットに目次ビューのマージされたデータが表示されます。ユーザーは、ツリーのブランチの展開や折りたたみを行い、リーフ(およびトピックが関連付けられているブランチ)を選択できます。リーフや、トピックが関連付けられているブランチを選択すると、トピックが右側のトピック・ペインに表示されます。必要に応じてスクロール・バーが表示されます。「目次」ナビゲータに目次が表示されない場合、グローバル・ツールバーの「表示」メニューを使用してタブに移動します。

図3-3 OHWの「目次」ナビゲータ

「目次」ナビゲータは、トピック・ペインに表示されるトピックと常に同期します。たとえば、トピック内のリンクをクリックして別のトピックにジャンプすると、新しいトピックが「目次」タブで自動的に強調表示されます。ユーザーがナビゲータを切り替えた場合でも、「目次」タブの状態は維持されます。たとえば、ユーザーがトピックを選択して「索引」ナビゲータに切り替えてから再度戻した場合(他のトピックは開かない)、選択したトピック、スクロール位置、およびツリーの展開状態は変わりません。これは、自動同期化機能で有効になります。ポップアップ・メニューには、ヘルプセットの表示および移動を制御するためのコマンド・メニュー項目のリストが表示されます。選択できる項目は次のとおりです。

- このページの印刷: 選択されたトピックのコンテンツを印刷します。

- このページをEメールで送信: デフォルトの電子メール・アプリケーションを開き、現在のトピックのURLをメッセージ本文に、トピック・タイトルを件名フィールドにコピーします(グローバル・ツールバーからも使用できます)。

- このページへのリンク: 選択されたトピックの永続リンクを含むポップアップを表示します。これを使用してブックマークを作成できます(グローバル・ツールバーからも使用できます)。

- 展開: ツリーを展開し、選択されたノードの子トピックを表示します。

- 縮小: ツリーを縮小し、選択されたノードの子トピックを非表示にします。

- 下をすべて展開: 選択されたノードの下にあるすべてのノードを開いて関連する子トピックを表示します。

- 下をすべて縮小: 選択されたノードの下にあるすべてのノードを閉じて関連する子トピックを非表示にします。

- 先頭として表示: 現在のノードをツリーのルートとして表示します。

注意:
コンテキスト・メニューの最初の3項目の機能は、グローバル・ツールバーからも使用できます。詳細は、第3.2項「OHWのグローバル・ツールバー」を参照してください。

3.4 OHWの「索引」ナビゲータ

「索引」ナビゲータには、ソートされたキーワード・リストが、2レベルの階層で表示されます。1つのキーワードを複数のトピックに関連付けることができます。階層では、子項目はインデント表示されます。

図3-4 OHWの「索引」ナビゲータ

図3-4の番号付きコールアウトは、次のユーザー・インタフェース・コンポーネントを示しています。

1. キーワードに移動: このフィールドに単語(複数可)を入力します。ユーザーが入力すると、リスト内のキーワードのうち、入力された文字列に一致する最初のキーワードが選択されます。入力する文字が多いほど、より正確な選択が行われます。または、単にキーワードのリストからキーワードを選択できます。

2. キーワード・リスト: 2レベルのリストに、キーワードがロケール依存の順序で表示されます。リスト内のキーワードを選択すると、関連付けられているトピックがトピックのリストに表示されます。

3. トピック・リスト: このリストには、キーワード・リストで選択されたキーワードに関連付けられている各トピックのタイトルおよびソースが表示されます。タイトルの1つを選択すると、トピック・ペインにそのトピックが表示されます。「トピック」列および「ソース」列の両方をアルファベットの昇順または降順にソートできます。

3.5 OHWの「検索」ナビゲータ

「検索」ナビゲータには、全文検索の問合せを実行するユーザー・インタフェースが用意されています。検索文字列として複数の語を入力できます。

図3-5 OHWの「検索」ナビゲータ

図3-5の番号付きコールアウトは、次のユーザー・インタフェース・コンポーネントを示しています。

1. 検索テキスト: ユーザーは単語(複数可)をこのフィールドに入力します。完全一致する句を検索する場合は、検索対象の句を二重引用符で囲みます。
また、検索文字列内にワイルドカード文字(*)を使用することもできます。ワイルドカード文字(*)は、文字列の間や文字列の末尾に使用することはできますが、文字列の先頭に使用することはできません。たとえば、John*DoeとJohn*は有効な検索文字列ですが、*Doeは無効な検索文字列です。

2. ソース: 検索対象のソース・トピックのセットを指定するドロップダウン・リストです。

3. 検索オプション: このドロップダウンで、指定された語のいずれか、またはすべてを含むトピックを表示するように指定できます。また、ブール式(AND、OR)を使用して検索を実行するように指定できます。

4. 大/小文字の区別: このチェック・ボックスを選択すると、ユーザーが入力した語と大/小文字が一致する語を検索できます。

5. トピック・リスト: 検索条件に一致する各トピックの「トピック・タイトル」、「スコア」および「ソース」を表示する検索結果領域です。「スコア」列には、検索条件との一致率に応じたトピックのランキングが表示されます。すべての列をアルファベットの昇順または降順にソートできます。デフォルトでは、すべてのトピックが「スコア」でソートされています。項目の上にマウスを置くとツールチップが表示され、関連するフォルダ、トピックおよびソース・データのフルネームが示されます。ユーザーが特定の結果を選択すると、関連付けられているトピックがトピック・ペインに表示されます。

Oracle Help for the Webには、単語の位置情報をIDXファイルに追加する、Oracle Help全文検索インデクサが組み込まれています。Oracle Help全文検索インデクサにより、完全一致する句の検索が可能になり、検索結果のランキング・メカニズムが向上します(相互に類似した検索語が検出された場合は高いポイントが与えられます)。完全一致する句を検索する場合は、その句を二重引用符で囲みます。たとえば、"John Doe"のようにします。

Oracle Help for the Webは、以前のバージョンのOracle Help Indexerで作成されたIDXファイルも読み取ることができます。また、古いIDXファイルと新しいIDXファイルの両方を必要に応じて一緒に使用できます。以前のリリースのOHJまたはOHWの新しいインデクサで作成されたIDXファイルの使用はサポートされません。使用すると、IDXバージョンがサポートされないことを示すSearchException例外のログが記録されます。

注意:
Oracle Help全文検索インデクサで作成したIDXファイルには、下位互換性がありません。現在のインデクサで作成したIDXファイルを、古いバージョンのOracle Help for the Webで使用すると、インデクサでエラーが発生します。

3.6 OHWのトピック・ペイン

トピック・ペインには、HTMLヘルプ・コンテンツが表示されます。

図3-6 OHWのトピック・ペイン

トピック・ペインには、現在表示されているトピックを操作するための固有のツールバーがあります。図3-6の番号付きコールアウトは、次のユーザー・インタフェース・コンポーネントを示しています。

1. ページ内で検索: このフィールドに、トピック・コンテンツ内で検索する特定のテキストを入力します。

2. 次へ: ユーザーが指定したテキストと一致する次の出現箇所を検索します。見つかった場合は、一致する箇所が選択されます。

3. 前へ: ユーザーが指定したテキストと一致する前の出現箇所を検索します。見つかった場合は、一致する箇所が選択されます。

4. トピック・ペイン: このペインにヘルプ・コンテンツが表示されます。

3.7 その他のOHW機能

このマニュアル以外では説明されていないOHW機能には次のようなものがあります。

3.7.1 OHWバージョン情報機能

OHWバージョン情報機能では、OHWヘルプ・システムについての情報、オラクル社のコピーライト情報および使用するOHWのビルド情報が表示されます。

注意:
Oracle Help for Javaでは、request問合せパラメータaboutOHWを使用することで、OHWバージョン情報機能をサポートします。

OHWバージョン情報ページを表示するには、次のURLに移動します。

http://localhost:<port_number>/<help ohw-rcf context-root>/faces/helppages/main.jspx?config=OHW+Servlet+1&aboutOHW=true

このURLに移動すると、トピック・ペインに、現在使用しているOHWのビルド情報と、コピーライト情報が表示されます。

図3-7 OHWバージョン情報ウィンドウ

3.7.2 ブックマーク機能

ブックマークにページを登録すると、そのブックマークに移動したときに同じトピックが表示されます。また、URLリンクを保存して、そのリンクを電子メールで送信することもできます。ブックマーク機能については、次の点に注意してください。

- ページをブックマークに登録するには、グローバル・ツールバーの「このトピック・ページの永続リンクの表示」ボタンを使用する必要があります。これにより、リッチ・クライアントのURLがブックマーク可能なURLにリフレッシュされます。ユーザーは、ブラウザのブックマーク登録機能を使用してURLを保存できます。

- 「索引」および「検索」ナビゲータの状態は、ブックマーク情報に含まれません。「目次」ナビゲータは、表示されるトピックと自動的に連動します。

3.7.2.1 下位互換性

OHWのブックマークでは、トピックID、グループおよびロケールを指定した場合と同じトピック・ビューをOHWに表示できます。ただし、OHWのブックマークには、サポートされるパラメータに加えて他の多数のパラメータも含まれるため、すべてのナビゲータの状態をリストアできるわけではありません。

検索エンジンによって索引付けされたOHWのURLは、有効なヘルプ・コンテンツにリンクします。

3.7.3 単一ペイン・レイアウト機能

ユーザーは、URLを変更すると、現在のトピックを単一ペイン・レイアウトで表示できます。

次に例を示します。

topicId

http://localhost:7101/help-ohw-rcf-context-root/ohguide/?topic=ohg_about_about_html&linkHelp=false

vtTopicFile

http://localhost:7101/help-ohw-rcf-context-root/ohguide/?vtTopicFile=ohguide/ohg_about_about.html&linkHelp=false

第II部

Oracle Helpのファイル形式

この部では、Oracle Helpのファイル形式について説明します。次の章で構成されます。

- 第4章「Oracle Helpのファイル形式の概要」
この章では、Oracle Helpのファイル形式の概要について説明します。

- 第5章「メタデータ・ファイル」
この章では、Oracle Helpで使用されるメタデータ・ファイルについて説明します。これにはヘルプセット・ファイルおよびマップ・ファイルが含まれます。

- 第6章「ヘルプ情報ファイル」
この章では、Oracle Helpで使用される情報ファイルについて説明します。これには目次ファイル、索引ファイル、検索索引ファイルおよびリンク・ファイルが含まれます。

- 第7章「トピック・ファイル」
この章では、Oracle Helpで使用されるトピック・ファイルについて説明します。

- 第8章「Oracle Help for the Web構成ファイル」
この章では、Oracle Help for the Web構成ファイルについて説明します。

4 Oracle Helpのファイル形式の概要

この章では、Oracle Help for Java (OHJ)およびOracle Help for the Web (OHW)で使用する、各種のファイル形式(メタデータ・ファイル、情報ファイル、トピック・ファイルなど)について説明します。

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

- Oracle Helpのファイル形式について

- ファイル名の拡張子

4.1 Oracle Helpのファイル形式について

次のヘルプ・ファイル形式がOHJとOHWで使用されます。

- メタデータ・ファイル: ヘルプ・システムの構造および動作に関する情報が含まれます。詳細は、第5章「メタデータ・ファイル」を参照してください。

- ヘルプ情報ファイル: ヘルプ・システムのコンテンツに関する情報が含まれます。詳細は、第6章「ヘルプ情報ファイル」を参照してください。

- トピック・ファイル: ヘルプ・システムのコンテンツが含まれるHTMLファイルです。詳細は、第7章「トピック・ファイル」を参照してください。

OHWでは、これらのファイルに加えて、サーブレット・フィルタを構成する構成ファイルも使用します。詳細は、第8章「Oracle Help for the Web構成ファイル」を参照してください。

Oracle Helpのファイル形式は、JavaHelp (tm)の仕様に基づいています。Java HelpとOracle Helpのファイル形式の相違点については、付録A「Oracle HelpおよびJavaHelpのファイル形式」を参照してください。

4.2 ファイル名の拡張子

ヘルプセットを使用する場合、関連する制御ファイルの名前に、指定された拡張子を使用する必要はありません。ただし、ファイルの参照時には、正しいファイル名と拡張子が使用されていることを確認する必要があります。

表4-1に、ヘルプセット関連ファイル形式の従来の(ただし必須ではない)拡張子を示します。また、これらのファイルの参照先も示されるため、正しい名称と拡張子が使用されているかどうかを確認します。

表4-1 OHJおよびOHWのファイル

ファイルのタイプ

標準的な拡張子

参照元

ヘルプセット

.hs

OHJの場合: ヘルプを起動するJavaプログラムからのコール。

OHWの場合: 構成ファイルの次の場所

<books>
<helpSet location="filename.hs" />
</books>

サブヘルプセットとして使用されるヘルプセット

.hs

次の場所にあるマスター・ヘルプセット・ファイル

<subhelpset location="filename.hs"/>

マップ

.xml

次の場所にあるヘルプセット・ファイル

<maps>
<mapref>filename.xml</mapref>
</maps>

TOC

.xml

次の場所にあるヘルプセット・ファイル

<maps>
<view>
<data engine="oracle.help.engine.XMLTOCEngine">filename.xml</data>
</view>

キーワード索引

.xml

次の場所にあるヘルプセット・ファイル

<view>
<data engine="oracle.help.engine.XMLIndexEngine">filename.xml</data>
</view>

リンク

.xml

次の場所にあるヘルプセット・ファイル

<links>
<linkref>filename.xml</linkref>
</links>

検索索引

.idx

次の場所にあるヘルプセット・ファイル

<view>
<data engine="oracle.help.engine.SeearchEngine">filename.idx</data>
</view>

5 メタデータ・ファイル

この章では、OHJおよびOHWで使用する、メタデータ・ファイル(ヘルプセット・ファイルとマップ・ファイル)について説明します。メタデータ・ファイルには、ヘルプ・システムの構造および操作に関する情報が含まれます。

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

- メタデータ・ファイルについて

- ヘルプセット・ファイル

- マップ・ファイル

5.1 メタデータ・ファイルについて

メタデータ・ファイルは、ヘルプセット・ファイルとマップ・ファイルの2つのタイプにカテゴリ分けできます。どちらのファイルも、XMLファイルです。

5.2 ヘルプセット・ファイル

ヘルプセット・ファイルは、拡張子.hsのXMLファイルで、ヘルプセットに関するプロジェクトレベルの情報で構成されています。たとえば、ヘルプセットに使用される他の制御ファイル(マップ、目次、索引、関連リンクおよび検索など)を指し示します。これらの参照は、Oracle Helpがユーザー・インタフェースの構築に使用するナビゲーション・ビューのセットの定義に一部使用されます。

ヘルプセット・ファイルは、次の要素とその子要素で構成されています。

- 第5.2.1項「<helpset>要素」

- 第5.2.2項「<title>要素」

- 第5.2.3項「<maps>要素」

- 第5.2.4項「<wintype>要素」

- 第5.2.5項「<links>要素」

- 第5.2.6項「<view>要素」

- 第5.2.7項「<subhelpset>要素」

- 第5.2.8項「サンプルのヘルプセット・ファイル」

5.2.1 <helpset>要素

ヘルプセット・ファイルのコンテンツ全体は、単一の<helpset>要素内に含まれます。つまり、ヘルプセット・ファイルは<helpset>で開始し、</helpset>で終了する必要があります。ヘルプセット・ファイルで許可される<helpset>要素は1つのみです。

5.2.2 <title>要素

<title>要素は、ヘルプセットに名前を割り当てます。次に例を示します。

<title>API Reference</title>

特定の条件下では、このタイトルは、ヘルプセットの名前としてOracle Helpユーザー・インタフェースに表示されます。たとえば、ヘルプセットを連結するのではなく、マージされたヘルプセットのリストを表示するようにOracle Helpを実装した場合、ヘルプセットのドロップダウン・リストにタイトルが表示されます。

5.2.3 <maps>要素

<maps>要素は1つ以上のマップ・ファイルを指し示します。これらのファイルは、トピックIDとトピック・ファイルのマッピングに使用されます。<maps>要素には、次の子要素があります。

表5-1 <maps>の子要素

要素の子要素を示します。" title="<maps>の子要素" width="100%">

要素

説明

<mapref>

このブックのマップ・ファイルの場所。複数のマップ・ファイルが指定されている場合、これらのファイルはマージされます。各<mapref>項目が順に検索され、マージされたマップが構築されます。<mapref>要素の属性は、次のとおりです。

- location: ヘルプセットを基準にしたマップ・ファイルの相対URL。

- class: (オプション)その場所がマップ・ファイルのベースの場所となるクラス。location属性のすべてのパス情報は、このベースの場所を基準とした相対パスとなっています。

<homeID>

一部の状況でヘルプセットのデフォルト・トピックとして使用されるトピックのID(マップ・ファイルで定義されています)。つまり、OHJの起動時にトピックが指定されていない場合、デフォルトでこのトピックが表示されます。<homeID>要素は、次のOHJ実装の場合にのみ機能します。

- OHJドキュメント・ビューア(OHJとともにインストールされます)。

- ナビゲータ・ウィンドウとトピック・ウィンドウがデフォルトでドッキングされるようOHJが実装されている場合。

<homeID>要素は、OHWでは使用しません。

次に例を示します。

<maps>
<mapref location="main_map.xml"/>
<mapref location="tutorial/tut_map.xml"/>
</maps>

5.2.4 <wintype>要素

<wintype>要素は、トピック(サイズ、画面の配置、テキストの色、背景色など)を表示する際にOHJで使用可能な1つ以上のウィンドウの特徴を定義します。OHJユーザー・インタフェースでのこの表示については、第2.2項「OHJのトピック・ウィンドウ」を参照してください。

注意:
OHWでは、<wintype>要素が認識されません。また、トピックがWebブラウザに直接表示される場合にもこの情報は無視されます。

ヘルプセット・ファイルには、任意の数(ウィンドウ・タイプごとに1つ)の<wintype>セクションを含めることができます。<wintype>タグの有効な属性は、次のとおりです。

- default: trueの場合、現在のウィンドウ・タイプが、トピック・ファイルでウィンドウ・タイプが指定されていないときに使用されるデフォルトのウィンドウ・タイプになります。falseの場合、現在のウィンドウ・タイプはデフォルトではないため、マップ・ファイルに明示的にリストしていない場合は使用されません。デフォルトの属性がない場合、この値はfalseとみなされます。

<wintype>要素の子要素は、次のとおりです。

表5-2 <wintype>の子要素

要素のすべての子要素を示します。" title="<wintype>の子要素" width="100%">

要素

説明

<name>

このウィンドウ・タイプの名前。この名前は、トピックをウィンドウ・タイプに関連付ける場合に使用されます。ヘルプセットに複数のウィンドウが定義されている場合は、各ウィンドウが一意の名前を持っている必要があります。

<height>

ウィンドウの高さ。数値はピクセル単位の長さを示します。数値の後にパーセント記号(%)が続く場合は、表示される画面における割合を示します。

<width>

ウィンドウのピクセル単位の幅。数値はピクセル単位の長さを示します。数値の後にパーセント記号(%)が続く場合は、表示される画面における割合を示します。

<x>

ウィンドウの水平位置。数値はピクセル単位の長さを示します。負の値はウィンドウの右端から画面の右端までの距離を示します。数値の後にパーセント記号(%)が続く場合は、表示される画面における割合を示します。

<y>

ウィンドウのピクセル単位の垂直位置。数値はピクセル単位の長さを示します。負の値はウィンドウの下端から画面の最下部までの距離を示します。数値の後にパーセント記号(%)が続く場合は、表示される画面における割合を示します。

<textfg>

ウィンドウのテキストの前景色を示す6桁の16進数RGB値。値の前に#がある場合がありますが、無視されます。すべてのトピックについて、HTMLトピック・ファイルまたはCSSで指定されている前景色が、この値より優先されます。

<linkfg>

ウィンドウのリンクの前景色を示す6桁の16進数RGB値。値の前に#がある場合がありますが、無視されます。すべてのトピックについて、HTMLトピック・ファイルまたはCSSで指定されているリンクの色が、この値より優先されます。

<bg>

ウィンドウの背景色を示す6桁の16進数RGB値。値の前に#がある場合がありますが、無視されます。すべてのトピックについて、HTMLトピック・ファイルまたはCSSで指定されている背景色が、この値より優先されます。

<title>

ウィンドウのタイトル・バーに表示されるテキスト。

<toolbar>

ウィンドウのツールバーに表示されるボタンを定義します。次のいずれか1つ以上の合計である5桁の16進数値。

- 00004: ツールバーのデフォルト・ボタンを無効にします。

- 00040: 現在のURLを表示するURLアドレス・フィールドを追加します。

- 00400: 「ナビゲータ」ボタンを追加します。

- 02000: 「印刷」ボタンを追加します。

- 04000: 「戻る」ボタンおよび「進む」ボタンを追加します。

- 08000: 「検索」ボタンを追加します。

- 10000 –: 「ドッキング」ボタンおよび「ドッキング解除」ボタンを追加します。

値の前に#がある場合がありますが、無視されます。

HTMLトピック・コンテンツ・ファイルで指定される属性は、常に、ヘルプセットの<wintype>セクションで指定される属性よりも優先されます。

次の<wintype>要素は、チュートリアル・トピックに使用されるウィンドウを定義しています。

<wintype default=false>
<name>Tutorial</name>
<height>50%</height>
<width>200</width>
<x>10</x>
<y>10</y>
<textfg>000000</textfg>
<linkfg>0000cc</linkfg>
<bg>ffffff</bg>
<title>Tutorial</title>
<toolbar>06004</toolbar>
</wintype>

この例の定義内容は、次のとおりです。

- ウィンドウ・タイプの名前は、Tutorialです。このウィンドウは、デフォルトの高さが画面の高さの50%で、デフォルトの幅が200ピクセルです。

- ウィンドウは、画面の上部と左側から10ピクセルずつ離れたところに表示されます。

- ウィンドウの背景色は白、テキスト色は黒、リンクの色は青で表示されます。

- ウィンドウのタイトル・バーには、Tutorialと表示されます。

- ウィンドウのツールバーには、「印刷」ボタン、「戻る」ボタンおよび「進む」ボタンが表示されます。

5.2.5 <links>要素

<links>要素は、複数のターゲットをリンクIDに関連付けるために使用されるリンク・ファイルを1つ以上ポイントします。リンク・ファイルの詳細は、第6.6項「リンク・ファイル」を参照してください。

<links>要素の子要素は、次のとおりです。

表5-3 <links>の子要素

要素のすべての子要素を示します。" title="<links>の子要素" width="100%">

要素

説明

<linkref>

このブックのマップ・ファイルの場所。複数のマップ・ファイルが指定されている場合、これらのファイルはマージされます。各<linkref>項目は順番に検索され、マージされたリンク・データベースが構築されます。<linkref>には次の属性があります。

- location: ヘルプセットを基準にしたリンク・ファイルの相対URL。

- class: (オプション)その場所がマップ・ファイルのベースの場所となるクラス。location属性のすべてのパス情報は、このベースの場所を基準とした相対パスとなっています。

次に例を示します。

<links>
<linkref location="linkfile1.xml"/>
<linkref location="linkfile2.xml"/>
</links>

5.2.6 <view>要素

<view>要素は、Oracle Helpでナビゲーション・ビューをレンダリングする方法を指定します。ナビゲーション・ビューとは、ナビゲーション制御ファイルのデータ(TOC、索引および検索など)に加えて、それらのファイルを検索するためのユーザー・インタフェース制御を表すものです。Oracle Helpには、標準タイプのビューをレンダリングするJavaクラスが含まれています。各タイプのビューは、その独自のアコーディオン・パネル(デフォルトでは「目次」、「索引」および「検索」パネル)で表示されます。

ヘルプセットには、各タイプのビューを複数含めることができます。つまり、ユーザー・インタフェースは、複数のTOCタブ、索引タブなどを表示できます。Oracle Helpでは、同じタイプのビューをマージすることもできます。これを行うには、同じラベルで同じタイプのビューをすべてマージします。タイプとラベルが同じビューは次のようにマージされます。

- TOCビューはまとめて追加されます。

- 索引ビューは、ソート順にマージされます。

- 索引ビューは、順不同でマージされます。すべての検索結果がユーザー・インタフェースでソートされるため、順序は関係ありません。

<view>要素の子要素は、次のとおりです。

表5-4 <view>の子要素

要素のすべての子要素を示します。" title="<view>の子要素" width="100%">

要素

説明

<label>

ユーザー・インタフェースのナビゲータ・タブに表示されるラベル。このラベルはオプションです。ラベルが指定されていない場合、Oracle Helpでは、該当するタブに「目次」、「索引」および「検索」が使用されます。<label>要素の属性は、次のとおりです。

- image: (オプション)イメージ・ファイルに関連付けられているマップ・ファイル内のID。イメージは、ナビゲータ・タブのラベル・テキストの横に表示されます。

<title>

ビューのタイトル。タイトルは、ナビゲーション・ビューごとに異なる場所に表示されます。

- TOCのタイトルは、トップレベル・ノードのタイトルとして表示されます。TOCファイル(またはマージされている場合は複数のTOCファイル)のすべてのトップレベル・ノードは、このタイトル・ノードの下に配置されます。TOCビューのタイトルが指定されていない場合、TOC定義のすべてのトップレベル・ノードがTOCビューのトップレベル・ノードとして表示されます。

- 検索ビューおよび索引ビューのタイトルは、検索の結果として、または索引項目の選択によってリストされたトピックのソースの場所として表示されます。検索ビューまたは索引ビューのタイトルが指定されていない場合、ソースの場所は空白になります。

titleタグの属性は、次のとおりです。

- image: (オプション)イメージ・ファイルに関連付けられているマップ・ファイル内のID。目次ビューに対して指定すると、イメージは、トップレベル・ノードのテキストの横に表示されます。索引ビューまたは検索ビューに対して指定すると、イメージは無視されます。

<type>

このビューのユーザー・インタフェースとして使用されるJavaクラスの名前。デフォルトの実装では、次のタイプが提供されます。

oracle.help.navigator.tocNavigator.TOCNavigator
oracle.help.navigator.keywordNavigator.KeywordNavigator
oracle.help.navigator.searchNavigator.SearchNavigator

JavaHelpタイプを指定すると、Oracle HelpはJavaHelpタイプをOracle Helpタイプに適切にマッピングします。

<data>

このビューで使用されるデータのパス。つまり、関連するナビゲーション制御ファイル(目次ファイル、索引ファイルまたは検索ファイルなど)のパス。この要素のコンテンツは、ファイル名またはURLになります。<data>要素では、次の属性をサポートします。

- class: (オプション)その場所がデータ・ファイルのベースの場所となるクラス。HTMLファイルへの参照を含むすべてのパス情報は、このベースの場所を基準とした相対パスとなっています。

- engine: データ・ファイルを処理するJavaクラスの名前を指定します。Oracle HelpのXML形式(JavaHelp形式に基づく)、MS HTML HelpのHHC/HHKファイル形式、旧バージョンのOHJでサポートされているTOC/TOK形式など、Oracle Helpでサポートされているファイル・タイプごとに異なるエンジンが必要です。サポートされているエンジンおよびビュー・タイプの詳細は、第5.2.6.1項「データ・ビュー・タイプおよびエンジン」を参照してください。

次の例では、TOCタブを2つ作成し、それぞれ「User's Guide」および「Reference」とラベル付けします。両方のタブで目次にXMLファイル形式が使用されます(<data>要素で指定されます)が、<label>要素の値が異なります。両方のタブのラベルが同じ場合、TOCファイルug_toc.xmlおよびref_toc.xmlは1つのTOCに結合され、1つのタブとして表示されます。

<view>
<label>User's Guide</label>
<type>oracle.help.navigator.tocNavigator.TOCNavigator</type>
<data engine="oracle.help.engine.XMLTOCEngine">ug_toc.xml</data>
</view>
<view>
<label>Reference</label>
<type>oracle.help.navigator.tocNavigator.TOCNavigator</type>
<data engine="oracle.help.engine.XMLTOCEngine">ref_toc.xml</data>
</view>

次のコード例では、異なるファイル形式(XMLとHHC)およびデータ・エンジンを使用する2つのビューから「目次」タブを1つのみ作成します。これは、ラベルとタイプが同であるためです。この機能の利点として、タブの表示方法を損なうことなく、古い形式を使用するヘルプ・システムを新しい形式を使用するヘルプ・システムにマージできる点をあげることができます。

<view>
<label>Table of Contents</label>
<type>oracle.help.navigator.tocNavigator.TOCNavigator</type>
<data engine="oracle.help.engine.XMLTOCEngine">new_toc.xml</data>
</view>
<view>
<label>Table of Contents</label>
<type>oracle.help.navigator.tocNavigator.TOCNavigator</type>
<data engine="oracle.help.engine.HHCEngine"old_toc.hhc</data>
</view>

次に、目次、索引および検索のビューの例を1つずつ示します。ビューにはラベルがないため、Oracle Helpでは、デフォルトのラベル「目次」、「索引」および「検索」を使用して3つのタブが作成されます。各ビューには、値User's Guideが指定された<title>要素が含まれます。この結果、次のように作成されます。

- 「目次」タブには、目次ファイルug_toc.xmlの項目が1つのトップレベル・ノード「User's Guide」の下に表示されます。

- ユーザーが「索引」タブのキーワード・リストから項目を選択すると、関連トピックのリストが表示されます。このヘルプセットのすべてのトピックのソースとして「User's Guide」が表示されます。

- ユーザーが「検索」タブで検索を実行すると、このヘルプセットのすべてのトピックのソースとして「User's Guide」が結果のリストに表示されます。

この機能は、複数のヘルプセットをマージする場合に役立ちます。また、目次のトップレベル・ノードの数を削減し、索引および検索を使用して見つかったトピックのソースを表示することによって、ユーザーは指向性を保つことができます。

<view>
<title>User's Guide</title>
<type>oracle.help.navigator.tocNavigator.TOCNavigator</type>
<data engine="oracle.help.engine.XMLTOCEngine">ug_toc.xml</data>
</view>
<view>
<title>User's Guide</title>
<type>oracle.help.navigator.keywordNavigator.KeywordNavigator</type>
<data engine="oracle.help.engine.XMLIndexEngine">ugindex.xml</data>
</view>
<view>
<title>User's Guide</title>
<type>oracle.help.navigator.searchNavigator.SearchNavigator</type>
<data engine="oracle.help.engine.SearchEngine">search.idx</data>
</view>

5.2.6.1 データ・ビュー・タイプおよびエンジン

次の表に、各ビュー・タイプの有効なエンジン値を示します。

表5-5 ビュー・タイプ: oracle.help.navigator.tocNavigator.TOCNavigator

エンジン

説明

oracle.help.engine.XMLTOCEngine (デフォルト)

Oracle HelpのXML目次(JavaHelp TOCの拡張)

oracle.help.engine.HHCEngine

Microsoft HTMLHelp 1.xの目次

oracle.help.engine.TOCEngine

旧バージョンのOHJの目次

表5-6 ビュー・タイプ: oracle.help.navigator.keywordNavigator.KeywordNavigator

エンジン

説明

oracle.help.engine.XMLIndexEngine (デフォルト)

Oracle HelpのXMLキーワード索引(JavaHelpキーワード索引の拡張)

oracle.help.engine.HHKEngine

Microsoft HTMLHelpのキーワード索引

oracle.help.engine.TOKEngine

旧バージョンのOHJのキーワード索引

表5-7 ビュー・タイプ: oracle.help.navigator.searchNavigator.SearchNavigator

エンジン

説明

oracle.help.engine.SearchEngine (デフォルト)

Oracle Helpのテキスト検索データベース

5.2.7 <subhelpset>要素

<subhelpset>要素を使用して、このヘルプセット・ファイルに定義されているヘルプセットとともに他のヘルプセットを含めます。結合されたサブヘルプセットのビューは、複数のビューが1つのヘルプセットにマージされるのと同じ方法でマージされます。つまり、同じ<type>と<label>を持つサブヘルプセット・ビューがマージされます。詳細は、第5.2.6項「<view>要素」を参照してください。

<subhelpset>要素の属性は、次のとおりです。

- location: マージされるヘルプセットのURLを指定します。

- class: (オプション)その場所がサブヘルプセット・ファイルのベースの場所となるクラス。location属性のすべてのパス情報は、このベースの場所を基準とした相対パスとなっています。

Oracle Helpでは、サブヘルプセットは常に存在しないことが前提になります。たとえば、製品スイートのマスター・ヘルプセットには、スイートの各製品(製品A、製品Bおよび製品C)のサブヘルプセットがあります。ユーザーは、製品Aのみを最初にインストールできます。後から、製品Cをインストールできます。この状況ではサブヘルプセットが役立ちます。サブヘルプセットは、見つかった場合はロードされ、見つからない場合は無視されるように指定できるためです。

5.2.8 サンプルのヘルプセット・ファイル

次に、5つのビュー、2つの目次、2つのキーワード索引、1つのテキスト検索など、前述のセクションをすべて含むサンプル・ヘルプセットを示します。

<?xml version='1.0'?>
<helpset version="1.1">

<maps>
<mapref location="topics.xml"/>
</maps>

<wintype>
<name>Tutorial</name>
<height>50%</height>
<width>200</width>
<x>10</x>
<y>10</y>
<title>Tutorial</title>
<toolbar>06004</toolbar>
</wintype>

<links>
<linkref location="linkfile1.xml"/>
<linkref location="linkfile2.xml"/>
</links>

<view>
<label image="tocgif">Table of Contents</label>
<title image="uggif">Forms User's Guide</title>
<type>oracle.help.navigator.tocNavigator.TOCNavigator</type>
<data engine="oracle.help.engine.XMLTOCEngine">ugcontents.xml</data>
</view>

<view>
<label>Keyword Index</label>
<type>oracle.help.navigator.keywordNavigator.KeywordNavigator</type>
<data engine="oracle.help.engine.XMLIndexEngine">ugindex.xml</data>
</view>

<view>
<label image="tocgif">Table of Contents</label>
<title image="dggif">Forms Developer's Guide</title>
<type>oracle.help.navigator.tocNavigator.TOCNavigator</type>
<data engine="oracle.help.engine.HHCEngine"
class="oracle.forms.documentation.dev">
dgcontents.hhc
</data>
</view>

<view>
<label>Keyword Index</label>
<type>oracle.help.navigator.keywordNavigator.KeywordNavigator</type>
<data engine="oracle.help.engine.HHKEngine"
class="oracle.forms.documentation.dev">
dgindex.hhk</data>
</view>

<view>
<label>Search</label>
<title>Forms Documentation</title>
<type>oracle.help.navigator.searchNavigator.SearchNavigator</type>
<data engine="oracle.help.engine.SearchEngine"
class="oracle.forms.documentation.dev">
search.idx</data>
</view>

<subhelpset location="prodsup.hs"/>
<subhelpset location="advanced.hs"/>

</helpset>

5.3 マップ・ファイル

マップ・ファイルは、IDをファイルに関連付けるXMLファイルです。マップ・ファイルの主要な目的は、トピックIDを定義し、トピック・ファイルに関連付けることです。また、トピックID(トピック)をヘルプセット・ファイルの<wintype>要素で定義されている任意のウィンドウ・タイプに関連付けることもできます。このIDは、目次ファイル、索引ファイルおよび状況依存コールのAPIで使用されます。

また、マップ・ファイルを使用して、イメージIDを定義し、イメージ・ファイルに関連付けることもできます。イメージIDを使用すると、タブ・ラベル(ヘルプセット・ファイルの<view>要素で指定されています)の横にイメージを表示できます。また、目次ファイルの<tocitem>要素で定義されている目次の項目の横にイメージを表示することもできます。

5.3.1 マップ・ファイルの要素

次の表に、マップ・ファイルで使用される要素を示します。

表5-8 マップ・ファイルの要素

要素

説明

<map>

マッピングを定義します。<map>要素には、<mapID>要素のみが含まれます。

<mapID>

IDおよびその関連付け。<mapID>要素の属性は、次のとおりです。

- target: 関連付けられているファイルのID。有効な文字は、英数字と等号(=)以外の句読記号です。IDは該当するヘルプ・インスタンスのすべてのヘルプセットで一意である必要があります。ただし、1つのファイルに複数のIDを割り当てることはできます。たとえば、トピック・ファイルのIDを割り当てて1つのウィンドウ・タイプで表示されるようにし、同じトピック・ファイルの別のIDを割り当てて別のウィンドウ・タイプで表示されるようにすることができます。

- url: このIDに関連付けるファイルの場所(ターゲット)。相対URLは、マップ・ファイルの絶対URLに対して解決されます。アンカー・リンクを使用すると、ファイルのセクションを指定することもできます。

- wintype: (オプション)ヘルプセット・ファイルの<wintype>要素を使用して定義されたウィンドウ・タイプの名前。ウィンドウ・タイプが指定されていない場合は、このIDに関連付けられいているトピックが、ヘルプセットに定義されているデフォルト・ウィンドウに表示されます。ネイティブ・ブラウザ・ウィンドウでトピック・リンクを開くには、map.xmlファイルで、関連するすべてのトピックにwintype="external"を指定します。この属性は、OHJにのみ適用されます。

次の例では、topic_1およびtopic_2というマップIDにはウィンドウ・タイプが関連付けられていないため、ヘルプセットのデフォルトのウィンドウ・タイプが使用されます。マップID topic_3およびtopic_4は、introウィンドウ・タイプで定義されているウィンドウに表示されるトピック・ファイルにマッピングされます。マップIDtopic_5.tskでは、taskウィンドウ・タイプで定義されているウィンドウ内に、File_5.htmlが表示されます。マップIDtopic_5.cncptでは、別のウィンドウ・タイプ(concept)に、同じトピック・ファイル(File_5.html)が表示されます。URLとwintypeの関連付けは、トピックIDではなくURLを使用してトピック間のリンクを作成する場合に使用します。たとえば、File_5.htmlに対してハードコード化されたターゲットがトピックにある場合、リンクをクリックすると、taskウィンドウ・タイプにHTMLコンテンツが表示されます。File_6.htmlに対してハードコード化されたターゲットがトピックにある場合、リンクをクリックすると、ネイティブ・ブラウザ・ウィンドウにHTMLコンテンツが表示されます。

<?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" />
<mapID target="topic_4" url="file_4.html#a2" wintype="intro" />
<mapID target="topic_5.tsk" url="file_5.html" wintype="task" />
<mapID target="topic_5.cncpt" url="file_5.html" wintype="concept" />
<mapID target="topic_6" url="file_6.html" wintype="external" />
</map>

このスキームによって作成者は、ウィンドウ・タイプをHTMLファイルに割り当てたり、代替のトピックIDへのリンクによってこれらの関連付けを上書きできます。たとえば、作成者は、トピック間リンク、TOCリンク、索引リンクおよびFile_5.htmlへのハードコードされたリンクの場合はtopic_5.tskを使用し、チュートリアルからのリンクの場合はtopic_5.cncptを使用できます。この情報をマップ・ファイル内に保持することによって、このマップ・ファイルを、これらの割当てを管理するための集中リポジトリにすることができます。

url属性で外部の場所(外部URL)を指定する場合、ターゲット・ファイルは新しいブラウザ・ウィンドウで開きます。たとえば、TOCリンクでtopic_extをトピックIDとして使用する場合、リンクは新しいブラウザ・ウィンドウでOTNページを開きます。

<mapID target="topic_ext" url="http://www.oracle.com/technetwork/index.html" />

6 ヘルプ情報ファイル

この章では、OHJおよびOHWで使用する、ヘルプ情報ファイル(目次ファイル、索引ファイル、およびリンク・ファイル)について説明します。ヘルプ情報ファイルには、ヘルプ・システムのコンテンツに関する情報が含まれます。

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

- ヘルプ情報ファイルについて

- 目次ファイル

- マスター目次

- 索引ファイル

- 検索索引ファイル

- リンク・ファイル

6.1 ヘルプ情報ファイルについて

ヘルプ情報ファイルは、目次ファイル、索引ファイル、およびリンク・ファイルの3つのタイプにカテゴリ分けできます。これらのファイルは、すべてXMLファイルです。

6.2 目次ファイル

目次(TOC)ファイルは、目次のコンテンツおよびレイアウトを記述するXMLファイルです。このファイルは、通常、「目次」タブとしてレンダリングされます。各ヘルプセットjarファイルには1つの目次ファイルが必要になることに注意してください。

ヘルプセットのjarファイルに、複数の子ヘルプセットが含まれている場合は、親ヘルプセットの目次のコンテンツとレイアウトを制御するためにマスター目次ファイルを使用します。

6.2.1 TOCの要素

表6-1に、目次ファイルで使用される要素を示します。

表6-1 TOCファイルの要素

要素

説明

<toc>

目次を定義します。この要素には、<tocitem>要素が含まれます。<toc>要素の属性は、次のとおりです。

- version: 目次ファイル形式の仕様のバージョン。例に示されるバージョン1.0です。

<tocitem>

目次のエントリを定義します。<tocitem>要素に他の<tocitem>要素を含め、トピックの階層を作成できます。tocitem_2内にtocitem_1をネストすると、tocitem_1がtocitem_2内の階層に含まれるよう定義されます。<tocitem>要素でサポートされる属性は、次のとおりです。

- target: ユーザーが項目を選択したときに表示されるトピックのトピックID。トピックIDは、マップ・ファイルに保持されます。親ノード(階層で、自身の下に他の項目を含む項目)には、ターゲットが含まれる場合と含まれない場合があります。ノードにターゲットが含まれていないときに、そのノードを選択すると、そのノードの子項目および子ノードが表示されます。
目次エントリから外部URLを開くには、url属性が目的の外部URLに設定されたトピックIDを使用します。すべての外部URLが新しいブラウザ・ウィンドウで自動的に開くことに注意してください。詳細は、第5.3.1項「マップ・ファイル要素」を参照してください。

- text: この項目の目次に表示されるテキスト。

- image: この項目の横に表示されるイメージ。この属性の値は、マップ・ファイルに指定されているイメージIDとなります。

次に、簡単な目次ファイルの例を示します。

<?xml version='1.0'?>
<toc version="1.0">
<tocitem text="Introduction to My Product" image="prodIcon">
<tocitem target="aboutmyp" text="About My Product" />
<tocitem target="architec" text="My Product Architecture" />
<tocitem target="feature1" text="About Feature One" />
<tocitem target="feature2" text="About Feature Two" />
<tocitem target="feature3" text="About Feature Three" />
<tocitem text="Learning My product">
<tocitem target="qtour" text="Quick Tour" />
<tocitem target="docguide" text="Guide to Documentation" />
</tocitem>
</tocitem>
<tocitem text="Step-by-step Procedures" image="prodIcon">
<tocitem text="Basic Tasks">
<tocitem target="task1" text="To..." />
<tocitem target="task2" text="To..." />
<tocitem target="task3" text="To..." />
</tocitem>
<tocitem text="Working with ...">
<tocitem target="task4" text="To..." />
<tocitem target="task5" text="To..." />
</tocitem>
</tocitem>
</toc>

この定義で作成されるTOC階層は、次のとおりです。

- Introduction to My Product

- About My Product

- My Product Architecture

- About Feature One

- About Feature Two

- About Feature Three

- Learning My Product

- Quick Tour

- Guide to Documentation

- Step-by-step Procedures

- Basic Tasks

- To...

- To...

- To...

- Working with ...

- To ...

- To ...

6.3 マスター目次

マスター目次ファイルは、すべての子ヘルプセットのTOC構造を制御し、他の目次ファイルを管理します。ヘルプセット・ファイルを宣言する前に、マスター目次を宣言する必要があります。

6.3.1 マスター目次の構成方法

マスター目次を使用する場合は、最初にOracle Help for the Web構成ファイルを構成しておく必要があります。

1. マスター目次ヘルプセット・ファイルは、Oracle Help for the Web構成ファイル内で宣言します。
次の例は、構成ファイルから抜粋したコードを示しています。

<books>
<helpSet id="master" location="master/src/helpset/master.hs"/>
<helpSet id="ohguide" location="ohguide/src/helpset/ohguide.hs"/>
<helpSet id="blafdoc" location="blafdoc/src/helpset/blafdoc.hs"/>
<helpSet id="shake" location="shakespeare/src/helpset/shakespeare.hs"/>
</books>

前述の例では、マスター目次ヘルプセット・ファイルを次のコードで宣言しています。

<helpSet id="master" location="master/src/helpset/master.hs"/>

マスター目次ヘルプセット・ファイルは、最初に宣言する必要があります。その他のヘルプセット・ファイルは、その後に宣言します。

2. マスター・ヘルプセット・ファイルを作成します。
マスター目次ヘルプセットのエントリは、次に示すmaster.hsファイルから抜粋したコード例のように、その他のTOCエントリに似ています。

<view>
<type>oracle.help.navigator.tocNavigator.TOCNavigator</type>
<data engine="oracle.help.engine.XMLTOCEngine">toc.xml</data>
</view>

3. すべての目次構造を定義する、マスター目次のXMLファイルを作成します。
このマスター目次のXMLファイルは、その他のtoc.xmlファイルと似ていますが、このファイルには<tocfile>要素が含まれています。<tocfile>要素では、次の例で示すように、子目次のXMLファイルの場所を定義します。

<toc version="1.0">
<tocitem text="Root">
<tocitem text="Some random node">
<tocfile location="ohguide/toc.xml" />
<tocfile location="javadoc/toc.xml" />
</tocitem>
<tocfile location="blafdoc/toc.xml;shakespeare/shakespeare.hhc" />
</tocitem>
<!-- All helpset toc files not explicitly declared in this file will be
inserted under the following node. This includes toc files that are
located in a subhelpset. -->
<tocitem text="Extension Help Content">
<tocfile location="*" />
</tocitem>
</toc>

マスター目次ファイルでは、コンテンツの構造を制御しますが、そのコンテンツはヘルプセット・ファイルで定義する必要があります。

6.4 索引ファイル

索引ファイルは、索引のコンテンツとレイアウトを記述するXMLファイルです。通常は、「索引」タブとしてレンダリングされます。

6.4.1 索引の要素

表6-2に、索引ファイルで使用される要素を示します。

表6-2 索引ファイルの要素

要素

説明

<index>

索引を定義します。この中には、<indexitem>タグと<indexentry>タグを含めることができます。

<indexitem>

キーワード・リストに表示される索引項目を定義します。index_item_2内にindex_item_1をネストすると、index_item_1がindex_item_2の階層に含まれ、索引でindex_item_2の下にインデントされて表示されるよう定義されます。Oracle Helpでは、現在2レベルのキーワードのみがサポートされています。索引ビューでは、2レベルを超えるネストは縮小されます。

索引項目に複数のトピックが関連付けられている場合、各トピックは、<indexentry>要素で定義された索引エントリとしてリストする必要があります。

<indexitem>要素の属性は、次のとおりです。

- target: ユーザーがエントリを選択したときに表示されるトピックのトピックID(マップ・ファイルで定義されています)。

<indexentry>

索引リストで親索引項目が選択されたときにトピック・リストに表示される索引エントリを定義します。このタグで使用される属性は、次のとおりです。

- target: ユーザーがエントリを選択したときに表示されるトピックのトピックID(マップ・ファイルで定義されています)。

次に、簡単な索引ファイルの例を示します。

<?xml version='1.0' ?>
<index version="1.0">

<indexitem target="Add_Icon"
text="Add Icon Command">
<indexitem target="addtosheet"
text="Adding an icon to a sheet />
<indexitem target="addtoworkbook"
text="Adding an icon to a workbook" />
</indexitem>

<indexitem target="Sheet_Background"
text="Adding a background to a sheet" />

<indexitem text="Adding a new sheet to a workbook">
<indexentry target="New_Sheet_command"
text="New Sheet Command />
<indexentry target="Add_new_sheet"
text="To add a new sheet to a workbook" />
</indexitem>

<indexitem target="Add_item_to_sheet"
text="Adding an item to a sheet" />
</index>

この例のファイルでは、次の索引リストが作成されます。

Add Icon Command
Adding an icon to a sheet
Adding an icon to a workbook
Adding a background to a sheet
Adding a new sheet to a workbook
Adding an item to a sheet

ユーザーがリストからAdding a new sheet to a workbookを選択すると、次のトピックのリストが表示されます。

New Sheet Command
To add a new sheet to a workbook

「索引」ペインの最上位のキーワード・リストに表示されるインデントされたトピックAdding an icon to a sheetおよびAdding an icon to a workbookとは対照的に、このトピック・リストは「索引」ペインの下部に表示されます。

索引エントリがなく、直接関連付けられたターゲットがあるキーワード(Adding an item to a sheetなど)を選択すると、キーワード・リストと同じテキストがトピック・リストに表示されます。Oracle Helpでの索引の表示方法を考慮すると、<indexitem>タグでターゲットを使用しないことをお薦めします。かわりに、キーワードのターゲットが1つのみの場合でも、常に<indexentry>タグを使用して<indexitem>に関連付けられているトピックを指定するようにします。

つまり、次のコードを使用します。

<indexitem text="sheet backgrounds">
<indexentry target="Sheet_Background" text="adding a background to a sheet" />
</indexitem>

次のコードは使用しないでください。

<indexitem target="Sheet_Background" text="adding a background to a sheet" />

6.5 検索索引ファイル

検索索引ファイルは、ユーザーがOracle Helpで(通常は「検索」タブから)テキスト検索を実行する場合に使用されます。このファイルでは、固有のバイナリ形式が使用されます。Oracle Helpをサポートするサード・パーティのヘルプ・オーサリング・ツールでは、このファイルを生成できます。さらに、OHJDKには、検索索引ファイルを生成する2つのユーティリティが含まれます。

- ヘルプセット・オーサリング・ウィザード: 検索索引の生成などの限定的なオーサリング・サポートが提供されます。詳細は、第9章「Oracle Helpシステムのオーサリング」を参照してください。

- テキスト検索インデクサ: 検索索引を生成するJavaコマンドライン・ツールです。詳細は、第11章「テキスト検索インデクサの使用方法」を参照してください。

6.6 リンク・ファイル

リンク・ファイルは、リンクIDを定義し、複数のトピックID(マップ・ファイルで定義されます)にリンクIDを関連付けるXMLファイルです。リンクID(リンク・キーワード)は、IDに関連付けられているトピックへのリンクのリストを表示するために、トピック・ファイルのalinkプロトコルで使用できます。つまり、関連リンクによって、1つのHTMLリンクを複数のターゲットに関連付けることができます。これにより、ユーザーは目的のターゲットを選択できるようになります。

6.6.1 リンク・ファイルの要素

表6-3に、リンク・ファイルで使用される要素を示します。

表6-3 リンク・ファイルの要素

要素

説明

<link>

リンク・ファイルを定義します。<link>要素には、<linkitem>要素およびその子要素の<linkentry>のみを含めることができます。

<linkitem>

関連リンクを定義します。<linkitem>要素には、<linkentry>要素のみを含めることができます。次の必須属性があります。

- topicid: リンクIDを定義します。

<linkentry>

関連リンクをクリックしたときに表示されるリンク・リスト内のエントリを定義します。この要素でサポートされる属性は、次のとおりです。

- target: ユーザーがエントリを選択したときに表示されるトピックのトピックID(マップ・ファイルで定義されています)を指定します。

- text: リンク・リストに表示されるテキスト。

次の例では、2つの関連リンクを定義しています。

<?xml version='1.0' ?>
<link version="1.0">

<linkitem topic="dog_links">
<linkentry target="about_dogs" text="About Dogs" />
<linkentry target="dog_species" text="A List of Dog Species" />
<linkentry target="dog_stories" text="Dog Stories" />
<linkentry target="dog_lore" text="Dog Lore" />
</linkitem>

<linkitem topic="cat_links">
<linkentry target="about_cats" text="About Cats" />
<linkentry target="cat_species" text="A List of Cat Species" />
<linkentry target="cat_stories" text="Cat Stories" />
</linkitem>
</link>

この例の最初のリンクIDを使用すると、リンク<a href="alink:dog_links">dogs</a>を定義できます。ユーザーがdogsリンクを選択すると、次のリンク・リストが表示されます。

About Dogs
A List of Dog Species
Dog Stories
Dog Lore

About Dogsをクリックすると、マップ・ファイルのabout_dogs IDにマップされているトピックが表示されます。

7 トピック・ファイル

この章では、OHJとOHWで使用する、トピック・ファイル、トピックIDと関連リンク、ポップアップ、ウィンドウ・タイプおよびカスタム・プロトコル・リンクについて説明します。

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

- トピック・ファイルについて

- トピックIDリンク

- 関連リンク

- カスタム・プロトコル・リンク

- ポップアップ

- トピックID

- ウィンドウ・タイプ

- ファイルへのトピックIDの動的マッピング

7.1 トピック・ファイルについて

トピック・ファイルは、ヘルプ・システムのコンテンツが含まれるHTMLファイルです。このHTMLファイルでサポートされる機能は、ファイルの表示に使用されるブラウザ(またはHTML表示コンポーネント)によって異なります。

OHJに付属のHTML表示コンポーネントは、ICEsoft Technologies社製のICEbrowserを、Oracle用に変更したものです。バージョン5.01以降のICEbrowserは、HTML 4.0標準に準拠しているため、表とフレームの表示や、Javaアプレットの実行も可能です。ただし、標準のICEbrowserでは、すべての機能を備えたヘルプ・システムにとっていくつかの重要な機能がサポートされません。そのため、オラクル社では、ICEsoft Technologies社の許可を得て、Oracleで開発された規則に対応して次の機能を提供するようにICEbrowserを改良しています。

これらの機能をOHJで使用するには、OHJのデフォルト・バージョンのICEbrowserを使用する必要があります。別のHTML表示コンポーネントを使用すると、これらの機能が動作しません。また、HTMLトピック・ファイルを直接Webブラウザで表示すると、このページに記載されているプロトコルおよびメタデータがブラウザで認識されず、機能が動作しません。

OHWはこれらの機能をサポートします。ただし、プロセスはOHJとは異なります。Oracle Help for the Webヘルプ・システムは、最新のどのWebブラウザでも表示できますが、これらのブラウザでは、このような規則は直接サポートされません。そのため、これらのカスタム機能は、WebサーバーのOHWサーブレットで処理され、標準HTMLリンクやブラウザに固有のJavaScriptとしてユーザーのブラウザに渡されます。

7.2 トピックIDリンク

HTMLの<a href="target">リンクのターゲットを指定するには、URL(標準HTMLリンクと同様)、アンカー・リンクまたはヘルプセットのマップ・ファイルで指定されているトピックIDとともにOracle Help topicidプロトコルを使用します。次に例を示します。

<a href="topicid:getting_started">Getting Started</a>

Getting Startedリンクをクリックすると、Oracle Helpはマップ・ファイルを参照し、リンクのトピックIDに関連付けられているHTMLファイルが表示されます。

topicidプロトコルは、アンカー・リンクもサポートします。次に例を示します。

<a href="topicid:getting_started#advanced">Getting Started</a>

Getting Startedリンクをクリックすると、Oracle Helpはマップ・ファイルを参照し、そのリンクのトピックIDに関連付けられているHTMLファイル内のadvancedアンカーの位置にジャンプします。

7.3 関連リンク

関連リンクは、複数のターゲットに関連付けられているリンクです。ユーザーがトピックの関連リンクを選択すると、そのリンクに関連付けられているすべてのトピックのリストが表示され、ユーザーはリストからトピックを選択できます。

Oracle Helpでは、Oracle Helpのalinkプロトコルおよびヘルプセットの関連リンクを指定するリンク・ファイルによって関連リンクがサポートされています。たとえば、キーワードworksheetに関連付けられているすべてのトピックを表示する関連リンクは、次のように指定します。

<a href="alink:worksheet">Related Topics</a>

Oracle Helpでは、関連リンクのキーワードを使用して1つまたは複数のリンク・ファイルが検索され、関連トピックのリストがポップアップ・ウィンドウで表示されます。この機能は、複数のヘルプセットのリンク・ファイルをマージする場合に特に役立ちます。

たとえば、次のように定義して、this linkを選択すると関連リンクのリストが表示されるようにすることができます。

<a href="alink:alinkexamples">this link</a>

リンク・ファイルの詳細は、第6.6項「リンク・ファイル」を参照してください。

7.4 カスタム・プロトコル・リンク

Oracle Help for Javaでは、Oracle Helpのcustomプロトコルによって、カスタム・プロトコルのリンクがサポートされています。たとえば、myProtocolというカスタム・プロトコルを使用するリンクは次のように指定します。

<a href="custom:myProtocol:myValue">Link to activate custom protocol</a>

カスタム・プロトコルを定義することは、ヘルプ・システムがアプリケーションにコールバックできる強力な方法です。HelpインスタンスにCustomProtocolHandlerを登録すると、アプリケーションでカスタム・プロトコル・リンクを処理できます。oracle.help.CustomProtocolHandlerの実装を作成し、registerCustomProtocolHandlerメソッドを使用してoracle.help.Helpインスタンスに登録します。このリンクの例では、registerCustomProtocolHandlerメソッドの最初の引数として文字列myProtocolを使用して、CustomProtocolHandlerのインスタンスを登録します。

Oracle Help for Javaは、カスタム・プロトコル・リンクを見つけると、識別子myProtocolを使用して、Helpオブジェクトに登録されているCustomProtocolHandlerを検索します。CustomProtocolHandlerが見つかると、そのhandleValue(String value)メソッドが起動し、値としてmyValueを渡します。

注意:
外部URLのリンクを指定する場合、カスタム・プロトコル・ハンドラの登録は必要ありません。OHJには、これに相当する、登録済カスタム・プロトコルexternalがあります。
たとえば、次のコードでは、OHJブラウザではなくデフォルトのインターネット・ブラウザでOTNページに移動するリンクが作成されます。

<a href="custom:external:http://www.oracle.com/technetwork/index.html">Oracle Technology Network</a>

7.5 ポップアップ

ポップアップは、Oracle Helpのpopupプロトコルによってサポートされます。次に例を示します。

<a href="popup:sheetdefinition">Sheet Definition</a>

popupプロトコルの後のキーワードは、ヘルプセットのマップ・ファイルで指定されているトピックIDです。ポップアップ・リンクをクリックすると、トピックIDに関連付けられているファイルのコンテンツが軽量ポップアップ・ウィンドウに表示されます。

次に例を示します。

<a href="popup:ohff_popupdemo_html">this link</a>

7.6 トピックID

Oracle HelpトピックIDはマップ・ファイルで保持されているため、Oracle Helpは、トピックIDを参照する必要がある場合にマップ・ファイルのデータを使用します。ただし、トピック・ファイルにトピックIDを指定し、ヘルプセット・オーサリング・ウィザードを使用してトピック・ファイルの情報からマップ・ファイルを生成できます。トピック・ファイルでトピックIDを定義するには、次の構文を使用してMETAタグを挿入します。

<META name="topic-id" content="topic_id_name">

topic_id_nameは、マップ・ファイルで使用されるトピックIDを指定します。

注意:
サード・パーティのヘルプ・オーサリング・ツールには、マップ・ファイルの生成にMETAタグを使用するものもあります。

ヘルプセット・オーサリング・ウィザードの詳細は、第10章「ヘルプセット・オーサリング・ウィザード」を参照してください。

7.7 ウィンドウ・タイプ

ヘルプセット・ファイルには、サイズ、位置および背景色などの特徴を含む1つ以上の指定ウィンドウを定義できるWinTypeセクションを含めることができます。トピック(およびトピックID)とこれらのウィンドウ・タイプは、マップ・ファイルで関連付けることができるため、トピックが表示される場合は、常に指定したウィンドウに表示されます。

注意:
ウィンドウ・タイプは、OHJでのみ使用可能です。

ヘルプセット・オーサリング・ウィザードを使用する場合は、トピック・ファイル内に含まれるトピックにウィンドウ・タイプを関連付けできますが、それと同時にトピックのtopic-id METAタグでトピックIDも指定する必要があります。ウィザードでは、両方のMETAタグの情報を使用してマップ・ファイルが生成されます。

ウィンドウをトピック・ファイル内のトピックに関連付けるには、次の構文を使用してMETAタグを挿入します。

<META name="window-type" content="window_name">

window_nameは、ヘルプセット・ファイルで定義されているウィンドウの名前です。

注意:

- トピックとウィンドウ・タイプの関連付けにこのメソッドを使用する必要はありません。マップ・ファイルで直接関連付ける方が簡単です。

- サード・パーティのヘルプ・オーサリング・ツールでこのMETAタグを使用して、トピックをウィンドウ・タイプに関連付けることができます。

- 旧バージョンのOHJでは、このMETAタグはOHJ表示エンジンによって直接読み取られ使用されていました。現行バージョンでは、これにかわり、マップ・ファイルがこの情報の集中リポジトリとなります。

7.8 ファイルへのトピックIDの動的マッピング

ヘルプセットで単純な表記規則を使用してトピックIDとマップ・ファイルをマッピングしている場合は、動的マッピングによって、Oracle Helpのメモリー使用量と起動時間を大幅に改善できます。

Oracle Helpは、ヘルプセットの<maps>領域の<mapref>サブ要素でエンジン属性をサポートします。エンジン属性を設定することにより、カスタム・エンジンを使用して、マップ・ファイルを解析したり、トピックIDとファイルとのマッピングに使用されるオブジェクトを作成したりできます。つまり、特定のエンジンを使用することで、マップ・ファイルをまとめて実際に排除できます。エンジン属性はオプションであるため、指定しない場合、Oracle Helpは、<mapref>で設定される場所属性を予測します。マップ・ファイルは、旧バージョンのOracle Helpと同様に解析されて格納されます。ただし、Oracle Helpは、トピックIDとファイル間で調停するための特定の共通規則に対応する2つのエンジンをサポートします。

- oracle.help.engine.XMLMapFixedConventionEngine

- oracle.help.engine.XMLMapConventionEngine

この2つのエンジンで動的マッピングのニーズが満たされない場合は、oracle.help.engine.DataEngineのカスタム実装を記述できます。

7.8.1 oracle.help.engine.XMLMapFixedConventionEngineヘルプ・エンジン

多くの場合、ファイル名myfile.htmlに対応するトピックIDはmyfile_htmlです。マップ・ファイルが、このような明白なトピック・マッピングの長く冗長なリストである場合、<mapref>のエンジン属性をoracle.help.engine.XMLMapFixedConventionEngineに設定する必要があります。

Oracle Helpの使用時に、エンジンをこの値に設定すると、旧マップ・ファイルを使用する必要がなくなります。ただし、ヘルプ・コンテンツが旧バージョンのOracle Helpを使用して参照される可能性がある場合は、旧バージョンのOracle Helpをトピック・マッピングの標準メカニズムに戻すことができるように、旧マップ・ファイルを保存しておく必要があります。

ヘルプ・システムのメモリー使用量と起動時間に問題がある場合は、この新しいエンジンを使用することをお薦めします。これにより、マップ・ファイルが読み取られないため、そのコンテンツはメモリーに格納されません。ただし、エンジンの使用について注意事項が1つあります。

すべてのヘルプ・コンテンツ(HTMLファイル)は、ヘルプセット・ファイルと同じディレクトリに存在する必要があります。さらに、サブヘルプセットも、マスター・ヘルプセット・ファイルと同じディレクトリに存在する必要があります。サブヘルプセットのサブディレクトリは、サブヘルプセットがマスター・ヘルプセットと同じディレクトリにない場合、ヘルプ・システムでコンテンツを見つけられないため、許可されません。ただし、異なるヘルプセットは別のディレクトリに存在できます。

次の例では、topic_1およびtopic_2というマップIDにはウィンドウ・タイプが関連付けられていないため、ヘルプセットのデフォルトのウィンドウ・タイプが使用されます。マップID topic_3およびtopic_4は、introウィンドウ・タイプで定義されているウィンドウに表示されるトピック・ファイルにマッピングされます。マップIDtopic_5.tskでは、taskウィンドウ・タイプで定義されているウィンドウ内に、File_5.htmlが表示されます。マップIDtopic_5.cncptでは、別のウィンドウ・タイプ(concept)に、同じトピック・ファイル(File_5.html)が表示されます。また、URLとwintypeの関連付けは、トピックIDではなくURLを使用してトピック間のリンクを作成する場合に使用されることにも注意してください。たとえば、トピックにFile_5.htmlへのハードコードされたターゲットがある場合、リンクをクリックすると、taskウィンドウ・タイプにHTMLコンテンツが表示されます。

<?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" />
<mapID target="topic_4" url="file_4.html#a2" wintype="intro" />
<mapID target="topic_5.tsk" url="file_5.html" wintype="task" />
<mapID target="topic_5.cncpt" url="file_5.html" wintype="concept" />
</map>

このスキームによって作成者は、ウィンドウ・タイプをHTMLファイルに割り当てたり、代替のトピックIDへのリンクによってこれらの関連付けを上書きできます。たとえば、作成者は、トピック間リンク、TOCリンク、索引リンクおよびFile_5.htmlへのハードコードされたリンクの場合はtopic_5.tskを使用し、チュートリアルからのリンクの場合はtopic_5.cncptを使用できます。この情報をマップ・ファイル内に保持することによって、このマップ・ファイルを、これらの割当てを管理するための集中リポジトリにすることができます。

7.8.2 oracle.help.engine.XMLMapConventionEngineヘルプ・エンジン

<mapref>要素でエンジンをoracle.help.engine.XMLMapConventionEngineに設定すると、マップ・ファイルで独自のトピック名の表記規則を定義できます。たとえば、ヘルプセットに次の<maps>定義があるとします。

<maps>
<mapref location="map.xml" engine="oracle.help.engine.XMLMapConventionEngine"/>
</maps>

XMLMapConventionEngineでは、トピックIDとウィンドウ・タイプのマッピングを設定する標準メカニズムがサポートされています。ただし、このエンジンでは、新しい<topicNameConvention>要素もサポートされています。

XMLMapConventionEngineを使用すると、map.xmlは次のようになります。

<map version="1.1">
<topicNameConvention urlbase="http://www.example.org/help">
<text>beginningText</text>
<filename/>
<text>_</text>
<extension/>
<text>endingText</text>
</topicNameConvention>
</map>

<topicNameConvention>では、単に、トピックIDの構造を指定します。<topicNameConvention>にurlBase属性を設定すると、すべてのヘルプ・コンテンツ・ファイルがそのURLにあるとみなされます。すべてのトピックIDの先頭がファイル名または拡張子の一部ではない文字列である場合、表記規則の先頭に<text>の値を指定できます。その後、<filename/>または<extension/>を指定して、ファイル名または拡張子が最初にトピック名の表記規則に表示されるかどうかを示す必要があります。これにより、ファイル名と拡張子を区切る<text>を指定できます。<filename/>または<extension/>では、次に、ファイル名または拡張子が表記規則の2番目に表示されるかどうかを示す必要があります。すべてのトピックIDの最後がファイル名または拡張子の一部ではないテキストである場合に、最後の<text>を指定できます。

このトピック名の表記規則に従って、beginningTextmyfile_htmlendingTextのトピックIDはファイルhttp://www.example.org/help/myfile.htmlに解決されます。urlBase属性が指定されていない場合、myfile.htmlは、ヘルプセット・ファイルと同じディレクトリにあるとみなされます。

マップ・ファイルに標準トピック・マッピングおよびウィンドウ・タイプを設定する場合にXMLMapFixedConventionEngineで提供されているトピック名の表記規則を使用すると、次のようにマップ・ファイルでtopicNameConventionを定義できます。

<map version="1.1">
<topicNameConvention>
<filename/>
<text>_</text>
<extension/>
</topicNameConvention>
<mapID .../>
</map>

この表記規則およびXMLMapFixedConventionEngineでは、ファイル名と拡張子を区切るテキストをトピックIDに複数回表示できます。たとえば、トピックmy_file_htmlの場合を考えてみます。エンジンでは、ファイル名と拡張子のセパレータをトピックIDの最後に表示される「_」文字とみなします。このため、トピックはmy_file.htmlに解決されます。

7.8.3 動的マッピングの最適化

トピックIDからファイルへの動的マッピングによって、ヘルプ・システムのパフォーマンスを大幅に向上できます。ただし、ライブラリに数多くのヘルプセットが含まれている場合、特定のトピックに対する状況依存ヘルプの呼出しを解決するには時間がかかることがあります。

この根本的な原因は、表記規則に基づくマッピング・エンジンが、URLが解決されていない場合でもトピックIDのURLを返すことです。このため、状況依存ヘルプの呼出しでは、ライブラリ内の各ヘルプセットを調査し、エンジンによって生成されたURLが実際に解決されるかどうかをチェックします。

最悪の場合では、1つの状況依存ヘルプの呼出しのために、ヘルプ・システムがライブラリ内のヘルプセットと同じ数のURLへの接続を試みます。ただし、Oracle Helpでは、この問題を解決するための簡単な改善策が提供されています。<mapref>要素にengineを設定する場合、engineParams属性も設定できます。

XMLMapConventionEngineまたはXMLMapFixedConventionEngineを使用する場合、engineParamsをヘルプセット内のトピックの接頭辞のスペース区切りリストになるよう設定できます。たとえば、ヘルプセット内のすべてのトピックの先頭がohまたはhelpの場合、maprefは次のようになります。

<mapref engine="XMLMap..." engineParams="oh help">

表記規則に基づくいずれかのエンジンにengineParamsを設定すると、ヘルプセットは、先頭が有効な接頭辞のトピックのみを解決するため、URLへの接続試行を回避できます。engineParamsを設定しなくてもヘルプ・システムは破損しませんが、パフォーマンスは低下します。

第III部

Oracle Helpのオーサリング

この部では、Oracle Helpシステムのオーサリングについて説明します。次の章で構成されます。

- 第9章「Oracle Helpシステムのオーサリング」
この章では、Oracle Helpのオーサリングの概要について説明します。

- 第10章「ヘルプセット・オーサリング・ウィザード」
この章では、Oracle Help for Javaのオーサリング・ウィザードを使用して、他の形式を使用して作成されたヘルプ・システムを変換する方法について説明します。

- 第11章「テキスト検索インデクサの使用方法」
この章では、テキスト検索インデクサの使用方法について説明します。

8 Oracle Help for the Web構成ファイル

この章では、Oracle Help for the Web構成ファイルと、このファイルの各種要素(helpConfiguration、brandings、locales、parameters、navigatorAliasesなど)について説明します。

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

- Oracle Help for the Web構成ファイルについて

- <helpConfiguration>要素

- <brandings>要素

- <locales>要素

- ヘルプセット間でのリソースの共有

- <parameters>要素

- <navigatorAliases>要素

- カスタム・プロトコル・リンク

- 埋込みヘルプを含むヘルプセットの事前ロード

- 実行時のOracle Help for the Web構成ファイルのリロード

8.1 Oracle Help for the Web構成ファイルについて

Oracle Help for the Web構成ファイルは、OHW構成を定義するXMLファイルです。この構成により、OHWサーブレットの調整可能なすべての機能を制御します。通常、このファイルの名前はohwconfig.xmlですが、サーブレットの初期化パラメータconfigFileNameの値として名前を指定することで、任意の名前を付けることができます。OHWのデモンストレーション・ファイルでは、ohwconfig.xmlを使用します。

8.2 <helpConfiguration>要素

<helpConfiguration>要素は、ヘルプ構成ファイルのトップレベル要素です。次で説明する構成の要素はすべて、<helpConfiguration>タグと</helpConfiguration>タグの間にある必要があります。helpConfiguration要素には、versionとdebugModeという2つの属性があります。

helpConfiguration要素のversion属性は、常に設定する必要があります。Oracle Help for the Webの場合、この属性の値は2.0になります。

次に例を示します。

<helpConfiguration version="2.0">

8.2.1 debugMode属性

ohwconfig.xmlの<helpConfiguration>要素でdebugMode="true"を設定してデバッグ・モードを有効にします。これにより、ヘルプセットをデバッグ・モードでロードできます。このモードでは、不正なヘルプセットがスキップされます。デバッグ・テキストは、画面の左上端およびブラウザのタイトル・バーに、ブランド情報とともに表示されます。デバッグ・テキストは、アプリケーションの実行中にスキップされた不正なヘルプセットの数を示します。

不正なヘルプセットが存在しないときには、ブランド表示領域に次のメッセージが表示されます。図8-1も参照してください。

Debug Mode: 0 Missing Helpsets".

図8-1 デバッグ・モードでのヘルプセット情報

1つの不正なヘルプセットに、複数の原因が含まれていることがあります。次に、いくつかの一般的な原因を挙げます。

- id属性が見つからない

- id属性が重複idである

- location属性が見つからない

- locationが無効な場所を指している

ヘルプ・システムをデプロイすると、デバッグ・モードを使用していることを示す警告メッセージがログに記録されます。ヘルプセットがスキップされるたびに、例外をスローするのではなく重大メッセージがログに記録され、そのログ・メッセージにはスキップされたヘルプセットのid属性とlocation属性が示されます。デフォルトでは、このログ・メッセージはSystem.errストリームを通じてログ出力され、開発者環境のコンソール・ウィンドウに表示されます。JDeveloperを使用している場合、このメッセージは「ログ」ウィンドウにログ出力され、ログ・ファイルは<JDEV_HOME>\jdeveloper\systemversion\DefaultDomain\servers\DefaultServer\logs\DefaultDomain.logに作成されます。

次に例を示します。

次のようにして、debugModeを有効にしたと仮定します。

<helpConfiguration version="2.0"
xmlns="http://xmlns.oracle.com/help/web/config" debugMode="true" >

その後、ohguideヘルプセットの場所をohguide_newディレクトリに変更し、それに対応するパスをohwconfig.xmlで更新することを忘れていたとします。

<books>
<helpSet id="ohguide" location="ohguide/ohguide.hs"/>
<helpSet id="shake" location="shakespeare/shakespeare.hs"/>
</books>

次のメッセージがブランド表示領域に表示されます。図8-2も参照してください。

Debug Mode: 1 Missing Helpsets

図8-2 デバッグ・モードでの欠落したヘルプセット情報

8.3 <brandings>要素

<brandings>要素は、タブ・バー上に表示される製品のブランド・テキストまたはイメージを指定します。<brandings>に属性はありません。すべてのブランド情報のプレースホルダになります。

<brandings>要素には、次の表に示す要素のいずれか1つのみを含めることができます。ブランド情報が指定されていない場合は、デフォルトのブランド・テキストが使用されます。

表8-1 <brandings>の子要素

要素の子要素を示します。" title="<brandings>の子要素" width="100%">

要素

説明

<branding>

属性情報からブランド情報をレンダリングします。また、特定のロケールを使用するようにこの要素を指定できます。この要素でサポートされる属性は、次のとおりです。

- text: レンダリングされるテキスト。エンティティと呼ばれる特殊文字を使用して、イタリックなどの単純なHTML属性を指定できます。たとえば、MyItalicsという名前でイタリックを保存する場合、ブランド・テキスト行は次のようになります。

<branding text="My&lt;i&gt;Italics&lt;/i&gt;" />

- imageHeight: ブランド・イメージのイメージの高さ。これを省略すると、イメージはデフォルトの高さの25ピクセルで表示されます。

- imageSource: ブランド・イメージのイメージ・ソース。この属性とtextが設定されている場合は、この属性が優先されます。
イメージの場所の宣言は、変換されたパスと必ずしも同じであるとはかぎりません。

- /foo/myImage.jpgのようなサーブレット・パスの場合:
変換パスは/<context-root>/foo/myImage.jpgです。

- http://mydomain.com/myImage.jpgのような絶対パスの場合:
変換パスはhttp://mydomain.com/myImage.jpgです。

- //foo/myImage.jpgのようなサーバー・ルート・パスの場合:
変換パスは/foo/myImage.jpgです。

- imageShortDesc: イメージについての短い説明。このテキストは、HTMLでのALT説明の処理方法と同じ方法で表示されます。たとえば、イメージの上にマウス・ポインタを置くとこのテキストが表示されます。

- locales: このブランドの指定対象となるロケールのスペース区切りリスト。このリストがない場合は、登録済ロケールすべてに対してブランド情報が適用されます。

OHWは、使用されるロケールを絞り込みますが、拡張はしません。たとえば、ロケールnlを指定し、ブラウザがロケールnl_NLを使用するように設定された場合、OHWはまずnl_NLの検索を試みますが見つからず、nlを見つけることができます。そのため、OHWでより具体的なロケール(nl_NL)を指定し、あまり具体的ではないロケール(nl)をブラウザで指定すると、リソース・バンドルなどの他の標準ロケール・メカニズムに合致してその指定は無視されます。

<brandingFromResource>

ResourceBundleからブランド情報をレンダリングします。この要素でサポートされる属性は、次のとおりです。

- resource: 使用するResourceBundleのJavaクラス名。

- textKey: ResourceBundleへのブランド・テキストのキー。

- imageSourceKey: ResourceBundleへのブランド・テキストのキー。この属性とtextKeyが設定されている場合は、この属性が優先されます。

- imageShortDescKey: ResourceBundleへのブランド・イメージの説明のキー。このテキストは、HTMLでのalt説明の処理方法と同じ方法で表示されます。たとえば、イメージの上にマウス・ポインタを置くとこのテキストが表示されます。

- locales: このブランドの指定対象となるロケールのスペース区切りリスト。このリストがない場合は、登録済ロケールすべてに対してブランド情報が適用されます。

OHWは、使用されるロケールを絞り込みますが、拡張はしません。たとえば、ロケールnlを指定し、ブラウザがロケールnl_NLを使用するように設定された場合、OHWはまずnl_NLの検索を試みますが見つからず、nlを見つけることができます。この結果、OHWでより具体的なロケール(nl_NL)を指定し、あまり具体的ではないロケール(nl)をブラウザで指定すると、リソース・バンドルなどの他の標準ロケール・メカニズムに合致してその指定は無視されます。

注意:
XLIFFリソース・バンドルを使用する場合、リソース・バンドル・サポート(resourcebundle.jar)ライブラリをクラスパスで追加します。
resourcebundle.jarファイルは、<MW_HOME>\oracle_common\modules\oracle.javatools_11.1.1\ディレクトリ(MW_HOMEはミドルウェア・ホーム)で入手できます。

次に例を示します。

<brandings>
<branding text="Oracle Help" />
</branding>

または

<brandings>
<branding text="Help" locales="en en_US" />
<branding text="Ayuda" locales="es" />
</brandings>

または

<brandings>
<brandingFromResource resource="myApp.resource.MyBundle" textKey="title" />
</brandings>

8.3.1 国際化のベスト・プラクティス

国際化を実装する場合、変換が必要になるヘルプセットに対して次のベスト・プラクティスを使用すると、ohwconfig.xmlを変換する必要がなくなります。

1. ohwconfig.xmlにブランド情報を直接入力せずに、<brandingFromResource>を使用して、すべてのロケール用に変換されたバンドルを参照します。ブランド情報は標準のJavaリソース・バンドルにあるため、このバンドルは、通常の変換プロセスで変換されます。

2. すべてのヘルプ制御ファイル(マップ、TOC、索引およびヘルプセット・ファイル)の先頭にXML宣言を入力します。この場合、<controlFileEncoding>を使用しないでください。指定されたローカライズ済ヘルプセット内のすべての制御ファイルには、同じエンコーディングを使用します。ヘルプセット・ファイルで指定したエンコーディングは、すべての制御ファイルでの読取りに使用されます。

注意:
旧バージョンのOHJを使用している場合は、ヘルプセットでXML宣言が認識されず、<controlFileEncoding>の設定が必要となることがあります。

3. ファイルは変換する必要がないため、ロケールごとに個別のファイルを使用する必要がなくなります。一部のサイトでは、別の理由から、個別のファイルを使用することがあります。

8.4 <locales>要素

ohwconfig.xmlファイルの<locales>セクションには、1つまたは複数のロケールを指定できます。localesセクションには、システムの1つのロケールを指定するタグが1つ以上あります。これらのタグのタイプは、<locale>要素または<localeFromFile>要素のいずれかです。要素名が示すとおり、<locale>要素はロケール・インラインを指定し、<localeFromFile>要素はロケールの宣言を外部ファイルに委譲します。外部ファイルには、1つの<locale>要素が含まれます。

表8-2 <locales>の子要素

要素の子要素を示します。" title="<locales>の子要素" width="100%">

要素

説明

<localeFromFile>

<localeFromFile>要素には、1つの属性が含まれ、子要素はありません。事実上、<localeFromFile>要素の機能は、外部ファイルの<locale>要素に置き換えられます。この要素でサポートされる属性は、次のとおりです。

- source: このロケールの<locale>要素を含むファイルのソース。このファイル名は構成ファイルを基準にしています。

<locale>

ロケールに依存する操作に対応するJava Localeを構築するために使用されるISO言語、国および(オプション)バリアント・コードを指定します。また、Oracle Help制御ファイルのキャラクタ・セット・エンコーディングのJavaでサポートされるエンコーディング名(ISO8859_1など)を指定します。

リストされる最初の<locale>要素がデフォルト・ロケールとなります。デフォルト・ロケールは、要求されたロケールに対応するコンテンツが存在しない場合に使用されます。特定の言語に対応するコンテンツが定義されている場合、その言語に対応するすべてのロケールに、そのコンテンツが使用されます。たとえば、<locale>タグにlanguage="en"を指定して英語のブックを定義すると、米国英語(en-US)、英国英語(en-GB)、および英語を使用するその他のユーザー(en-*)に同じコンテンツが提供されます。

この要素でサポートされる属性は、次のとおりです。

- language: ISO-639で定義されている小文字2文字の言語コード(英語のenなど)。

- country: ISO-3166で定義されている大文字2文字の国コード(米国のUSなど)。
この値は、言語のバリエーションを区別する必要がある場合に指定します。たとえば、簡体字中国語(zh-CN)と繁体字中国語(zh-TW)などです。

- variant: ブラウザまたはプラットフォームに固有のロケールのオプションのバリアント・コード。

- group: ロケールが関連付けられているオプションのグループ。グループの選択は、特別なグループ・パラメータが指定されたURLで行われます。

<locale>セクションでは、子要素<book>がサポートされます。

次に例を示します。

<locales>
<locale language="en">
... set of books for this locale ...
</locale>
</locales>

8.4.1 <locale>の子要素<books>

<books>要素は、Oracle Help for the Webで表示されるコンテンツを指定します。<books>要素には、任意の数のヘルプセットを含めることができます。ヘルプセットはブックとも呼ばれます。

<books>要素には、次の要素を含めることができます。

表8-3 <books>の子要素

の子要素である<books>の子要素を示します。" title="<books>の子要素" width="100%">

要素

説明

<helpSet>

OHWのこのインスタンスに含めるヘルプセット。この要素には、次の属性があります。

- id: このブックの一意のID。この属性は必須です。

- jar: ヘルプセットがJAR (Java Archive)ファイル内にある場合、そのJARファイルの場所。この属性を使用する場合は、location属性も使用してJARファイル内のヘルプセット・ファイルの場所を指定する必要があります。

- location: ヘルプセット・ファイルの場所。ヘルプセットのJARファイルが作成されていない場合、この属性は適切なパス情報を持つヘルプセット・ファイルの名前になります。パスには、構成ファイルの場所を基準とした絶対パスまたは相対パスのいずれかを使用できます。jar属性とともにこの属性を使用する場合、locationは、JARファイル内のヘルプセット・ファイルの場所になります。

- controlFileencoding: Javaでサポートされるエンコーディング名。サポートされるエンコーディングのセットは、JDKのバージョンに応じて異なります。Java SEでサポートされるエンコーディングのリストについては、http://download.oracle.com/javase/1.5.0/docs/guide/intl/encoding.doc.htmlを参照してください。

次に例を示します。

<books>
<helpSet id="shakre" location="shakespeare/shakespeare.hs" />
<helpSet id="myproduct" location="myProduct/myProductHelp.hs" />
<helpSet id="myhelpset" jar="myJar.jar" location="myHelpset.hs" />
</books>

ヘルプ・トピック・ファイルがOracle Helpで予期していない場所にある場合、<helpSet>要素には、<contentLocation>要素を0(ゼロ)個以上含めることができます。

8.4.2 <contentLocation>要素

デフォルトでは、OHWは、ヘルプセット(.hs)ファイルと同じ場所にあるヘルプ・トピック・ファイルを自動的に処理します。

ヘルプセットでは、OHWは、次の場所にあるヘルプ・トピックのHTMLファイルを処理します。

- .hsファイルと同じディレクトリおよびその場所のサブディレクトリ

- ヘルプセットがJARファイル内にある場合は、そのJAR内のすべてのヘルプ・トピック・ファイル

ヘルプ・トピック・ファイルが別の場所にある場合は、<contentLocation>要素を使用してその場所を指す必要があります。

<contentLocation>要素には属性baseURIがあります。これは、絶対パスまたは相対パスのいずれかを使用して、ヘルプ・コンテンツのセットのルートの場所を示すURIを表します。

<contentLocation>要素は、<helpSet>の子要素にできます(helpSetは<books>の子要素)。<helpSet>要素には、<contentLocation>要素を0(ゼロ)個以上含めることができます。

プレーンHTMLファイルとは異なり、Oracle Helpのヘルプ・トピック・ファイルは、表示されるためにサーブレットによって処理される必要があるため、この要素が必要になります。そのため、ヘルプセットで参照されるヘルプ・トピック・ファイルがデフォルトの場所にない場合、それらが存在する場所を明示的にリスト表示する必要があります。これは、別の場所または別のWebサーバーにあるサブヘルプセットがヘルプセットに含まれる場合、あるいは状況依存マップ・ファイルに、同じサーバーまたは別のサーバーの他の場所にあるヘルプ・トピック・ファイルの参照が含まれる場合に生じます。

絶対パスのコンテンツの場所

コンテンツの場所の絶対パスがわかっている場合は、絶対パスを指定してください。

たとえば、OHWが、別のサーバーhttp://www.myCompany.com/help/remoteHelpSet.hsにあるサブヘルプセットを参照するローカル・ヘルプセットmyHelpSet.hsで構成されている場合、構成ファイルには次が含まれます。

<books>
<helpSet id="myhelpset" location="myHelpSet.hs">
<contentLocation baseURI="http://www.myCompany.com/help/" />
</helpSet>
</books>

この構成は、ローカルのmyHelpSet.hsファイルがサーバーのヘルプ・コンテンツを参照していることをOHWに通知しています。たとえば、http://www.myCompany.com/help/remoteHelpSet.hsのようになります。

このため、OHWは自動的に、myHelpSet.hsと同じ場所およびリモートの場所にあるヘルプ・トピック・ファイルを処理します。

相対パスのコンテンツの場所

コンテンツの場所の絶対パスがわからない場合は、コンテンツの相対パスを指定してください。場所はヘルプセット・ファイルではなく構成ファイルを基準とした相対パスとなり、末尾にスラッシュを付ける必要があります。

たとえば、構成ファイルと同じディレクトリに配置されたimagesディレクトリにあるコンテンツの場所を指定するには、次のように宣言します。

<contentLocation baseURI="images/" />

構成ファイルより1つ下のディレクトリに配置されたimagesディレクトリを指すコンテンツの場所を指定するには、次のように宣言します。

<contentLocation baseURI="../images/" />

場所はヘルプセットを基準とした相対パスになります。ヘルプセットがJARファイル内にある場合は、相対パスの解決時にJARファイルがディレクトリとして評価されます。たとえば、次のディレクトリ・パスがあるとします。

/myhelpsets/myhs.jar
/myhelpsets/myhs.jar!myhelpset.xml
/common_images

<baseURI>の値は、次のようになります。

../../common_images

8.4.3 サンプルの<locales>セクション

構成ファイルのこのセクションのサンプルでは、英語と日本語の構成ファイルを指定しています。

<locales>

<!-- An English locale -->
<locale language="en" country="US" controlFileEncoding="UTF-8">
<books>
<helpSet id="hs1" location="ohguide/ohguide.hs"/>
<helpSet id="hs2" location="shakespeare/shakespeare.hs"/>
</books>
</locale>

<!-- A Japanese locale from an external file -->
<localeFromFile source="jp_config.xml" />

</locales>

8.5 ヘルプセット間でのリソースの共有

同じイメージ、CSSスタイルシートまたはその他のリソースすべてを使用したローカライズ済ヘルプセットが多数ある場合、OHWは、ヘルプセット間でのこれらのリソースの共有に対応できます。一般的に共有リソースは個別のディレクトリ(通常は、ローカライズ済ヘルプセット情報を保持するサブディレクトリの下)にあります。たとえば、次に、共有リソースを使用する場合の典型的なディレクトリ構造を示します。

<main directory>
ohwconfig.xml
/en
- owh_helpset_en.hs
- English helpset files
/es
- ohw_helpset_es.hs
- Spanish helpset files
/shared
/images
- shared images
/css
- shared stylesheets

デフォルトでは、OHWは、.hsファイルの下のディレクトリにのみアクセスできます。このため、OHWで共有ディレクトリを使用できるようにするには、コンテンツの場所を、このディレクトリに定義する必要があります。この場合、相対パスのコンテンツの場所を使用することをお薦めします。

OHWは、リソースに対応する場合に相対パスをサポートし、実行時にこれらのパスを正しいパスに適宜変換します。共有リソースを利用するために、HTMLファイルは、相対パスを使用してリソースを指し示すことができます。たとえば、共有イメージ・リソースを指し示す./enディレクトリにHTMLファイルがある場合、そのHTMLファイルには、次のコードが含まれます。

<img alt="Image of cat" src="../shared/images/cat.gif />

コンテンツの場所が定義されていると、OHWは、実行時に動作するようこのパスを修正します。また、ヘルプセットの制御ファイル内で相対パスを使用することもできます。たとえば、./enディレクトリにあるマップ・ファイルに次のコードを定義できます。

<mapID target="someDescriptor" url="../shared/html_files/theContent.html" />

また、ローカライズ済ヘルプセットがJARファイル内にある場合は、相対パスを指定するとJARファイルがディレクトリとみなされます。このため、すべてのヘルプセット・ファイルが./enディレクトリのJARに含まれているときに、共有イメージ・リソースを参照する場合は、HTMLファイルに次のコードを含める必要があります。

<img alt="Image of cat" src="../../shared/images/cat.gif />

前述のコードでは、JARファイルがディレクトリとみなされるため、追加の..が必要になります。

8.6 <parameters>要素

<parameters>要素は、その他の様々なOHWパラメータの値を指定します。すべてのパラメータで、大/小文字が区別されます。

表8-4 <parameters>の子要素

要素の子要素を示します。" title="<parameters>の子要素" width="100%">

要素

説明

<combineBooks>

trueの場合、すべてのブックのビューが1つのナビゲータ・セット(タブ)に表示されます。falseの場合、各ブックには、そのブックの情報のみを表示する独自のナビゲータ・セットが表示されます。

<useLabelInfo>

trueの場合、マージされたヘルプセットのナビゲータに作成者定義のラベルが使用されます。falseの場合、タブ・ラベル「目次」、「索引」、「検索」など、デフォルトのラベルが使用されます。

<displaySiteNavigation>

trueの場合、サポートされるすべてのナビゲータ間のサイト・ナビゲーション・リンクが有効になります。サイト・ナビゲーションがサポートされているブラウザの場合、OHWで処理されるページのメタ・コンテンツに適切なリンクが生成されます。

combineBooksがtrueの場合、「索引」タブのように、同じラベルを持つ同じタイプのナビゲータのみが1つのナビゲータにマージされます。useLabelInfoをtrueに設定している場合は、予期しない結果が発生することがあります。たとえば、1つのヘルプセットにキーワード索引で上書きされたデフォルトの「索引」ラベルとデフォルトのままの他のラベルがある場合、索引は同じタブにマージされません。これを変更するには、ヘルプセットを同じ(ヘルプセットのヘルプセット・ファイルで)になるように設定するか、または構成ファイルのuseLabelInfoをfalseに設定します。

次に例を示します。

<parameters>
<combineBooks>true</combineBooks>
<useLabelInfo>false</useLabelInfo>
</parameters>

他に、次のような重要なパラメータがあります。

表8-5 <parameters>キーワード子要素

要素のキーワード子要素を示します。" title="<parameters>キーワード子要素" width="100%">

要素

説明

<keywordBlockSize>

1ページに表示されるキーワードの数。デフォルト値は10です。

<keywordTopicsBlockSize>

1ページに表示されるトピックの数。デフォルト値は10です。

<searchBlockSize>

1ページに表示される検索結果の数。デフォルト値は10です。

これらの要素は、パフォーマンス・チューニングをサポートしたり、デフォルト以外のエラー、状態、ロケール処理を指定する場合に使用します。

表8-6 <parameters>パフォーマンス子要素

要素のパフォーマンス子要素を示します。" title="<parameters>パフォーマンス子要素" width="100%">

要素

説明

<maxSearchThreads>

OHWで検索を実行するために使用できるスレッドの最大数。デフォルト値は10です。

多数のユーザーがヘルプ・システムに接続して、同時に検索機能を使用すると予測できる場合は、maxSearchThreadsの値を10よりも大きくしてもかまいませんが、お薦めはできません。ヘルプ・システムが検索中に応答しない場合は、maxSearchThreads値を変更する前に、索引ファイル(.idxファイル)が破損していないかどうかを調べてください。

<errorPage>

トピックが見つからない場合に、OHWでは、このトピックがかわりに表示されます。このパラメータの値はトピックIDです。値が設定されていない場合、OHWでは、標準のエラー・ページが提供されます。

<stateManager>

OHWが使用する必要がある状態マネージャを指定します。cookieに設定すると、ユーザーの状態は1か月保存されます。sessionに設定すると、ユーザーの状態は1つのリクエストを通して保存されます。デフォルトは'session'です。

<localeDeterminer>

OHWでは、特定のロケール限定子を使用して、ユーザー・リクエストに基づきローカライズ済ヘルプセットを選択します。OHWには、値が設定されていない場合にブラウザ設定を使用してロケールを決定する、デフォルトのロケール限定子があります。

<cacheSize>

メモリーに同時に保存されるアクティブなローカライズ済ヘルプセットの数。デフォルト値は3です。

8.7 <navigatorAliases>要素

オプションの<navigatorAliases>要素を使用すると、OHWのナビゲータのクラス名と一致しないクラス名をヘルプセット・ファイルで使用できるようになります。別名の登録は、<alias>要素を使用して行われます。<alias>要素は、1つの<navigatorAliases>要素内に含まれ、次の属性を持ちます。

- name: 別名として使用する名前。

- value: 別名をマップする必要がある値。

次に例を示します。

<navigatorAliases>
<alias name="oracle.help.navigator.tocNavigator.TOCNavigator" value="oracle.help.web.navigator.tocNavigator.TOCTreeNavigator" />
</navigatorAliases>

注意:
OHWのツリーベースのTOCナビゲータでは、oracle.help.web.navigator.tocNavigator.TOCTreeNavigatorクラス名が使用されます。

8.8 カスタム・プロトコル・リンク

OHWでは、Oracle Helpのcustomプロトコルによる、カスタム・プロトコル・リンクがサポートされています。OHJのカスタム・プロトコル・リンクの詳細は、第7.4項「カスタム・プロトコル・リンク」を参照してください。

OHWでカスタム・プロトコル・リンクを処理するために、クライアントは、ヘルプ・コンテンツで使用されている各カスタム・プロトコルのohwconfig.xmlファイルにカスタム・プロトコル・コンバータを登録する必要があります。ohwconfig.xmlファイル内の構文は、次のようになります。

<customProtocolRegistry>
<customProtocol name="xlink" class="oracle.help.web.converter.ConfigurableCustomProtocolConverter">
<parameters>
<prepend>http://www.myserver.com/index.jsp?someParam=</prepend>
<targetFrame>_blank</targetFrame>
</parameters>
</customProtocol>
</customProtocolRegistry>

ユーザーは、CustomProtocolConverterの独自の実装を書き込むことができます。ただし、OHWには、ohwconfig.xmlに設定されたパラメータを使用して構成可能なConfigurableCustomProtocolConverterが含まれます。サポートされているパラメータは、次のとおりです。

<prepend>optional string to be prepended to the value</prepend>
<append>optional string to be appended to the value</append>
<targetFrame>optional target frame</targetFrame>

HTMLトピック・ファイルでは、作成者は標準のOracle Helpカスタム・プロトコル構文を使用できます。次に例を示します。

<a href="custom:xlink:someXLINKID">An Example Custom Protocol Link</a>

OHWでは、すべてのcustom:リンクが処理され、そのカスタム・プロトコル名に対して登録されているカスタム・プロトコル・コンバータを通じてリンクが実行されます。

前述の例のリンクは、次で置き換えられます。

<a href="http://www.myserver.com/index.jsp?someParam=someXLINKID" target="_blank" />

OHJでは、新しいブラウザ・ウィンドウでリンクを起動するためにcustom:external:を使用することが一般的になっています。OHWでは、外部プロトコルの組込みCustomProtocolConverterによって、ユーザーが明示的にコンバータを登録しなくても、リンクが作動します。

8.9 埋込みヘルプを含むヘルプセットの事前ロード

OHWは、OHW構成ファイルの<locale>タグをサポートします。このファイルは、OHWがサポートするロケールの単一インスタンスを定義します。<locale>タグは、ロケールが影響する操作のJava Localeの構築に使用されるISO言語、国およびバリアント・コード(オプション)を指定します。また、Oracle Help制御ファイルのキャラクタ・セット・エンコーディングのJava対応エンコーディング名(ISO8859_1など)を指定します。リストされる最初の<locale>要素がデフォルト・ロケールとなります。

OHWでは、ヘルプセットは別の方法でロードされます。RCFアプリケーションとしてのOHWでは、ヘルプセット内の単一ファイルに指定された定義テキスト・コンテンツとともに、50のコンポーネントが画面に表示されることがあります。すべてのヘルプセットがロードされないようにして、ユーザーが画面を開いたときにヘルプセットのロードにより発生するラグを削減するには、選択したヘルプセットの事前ロードを有効にします。

このため、OHWの場合、構成ファイルでは、<locale>タグのオプションの属性preloadがサポートされています。この属性の可能な値は、NONE、ALLおよびTOPICMAPです。値が指定されていない場合、デフォルト値はNONEです。

各値の動作は、次のとおりです。

表8-7 preloadの値の動作

preloadの値

OHWの初期起動

トピックにアクセスしたときの動作

UIにアクセスしたときの動作

NONE

処理は必要ありません。

要求されたトピックが見つかるまでトピック・マップがロードされます。

選択されたヘルプセット内のすべてのビューおよびナビゲータがロードされます。

ALL

ロケールのすべてのヘルプセットがロードされ(すべてのビューおよびナビゲータが起動します)、トピック・マップもすべてロードされます。

キャッシュからのアクセス。

キャッシュからのアクセス。

TOPICMAP

ロケールのすべてのヘルプセットのトピック・マップのみがロードされます。

キャッシュからのアクセス。

選択されたヘルプセット内のすべてのビューおよびナビゲータがロードされます。

構成ファイルは、次のようになります。

<?xml version='1.0' ?>
<helpConfiguration>
...
<locales>
<locale language="en" preload="ALL">
<books>
<helpset id="helpset1" location=" helpset1.hs"/>
<helpset id=" helpset2" location=" helpset2.hs"/>
</books>
...
</locale>
</locales>
...
</helpConfiguration>

8.10 実行時のOracle Help for the Web構成ファイルのリロード

OHWには、ヘルプ・システムの実行中にファイルの変更を含めるように、Oracle Help for the Web構成ファイルを実行時にリロードするメソッドがあります。この変更の例として、ヘルプ・システムを再デプロイせずに、将来パッチを適用するヘルプセットなどがあります。構成ファイルをリロードすると、キャッシュが空になり再構築されます。

8.10.1 実行時のOracle Help for the Web構成ファイルのリロード方法

ユーザーが実行時に構成ファイルリロードできるようにする場合、web.xmlで新規パラメータohwConfigAutoUpdateを追加します。

実行時にOracle Help for the Web構成ファイルをリロードするには:

1. web.xmlで新規パラメータohwConfigAutoUpdateを作成し、それをtrueに設定します。
たとえば、web.xmlファイルは、次のようになります。

<?xml version = '1.0' encoding = 'UTF-8'?>
...
<init-param>
<param-name>ohwConfigAutoUpdate</param-name>
<param-value>true</param-value>
</init-param>

2. 構成ファイルを必要に応じて更新します。

3. 構成ファイルの更新後に、ヘルプ・アプリケーションのデフォルトのホーム・ページを開きます。
ヘルプ・アプリケーションのホーム・ページを開くと、古い構成設定が消去され、新しい設定が有効になります。

9 Oracle Helpシステムのオーサリング

この章では、Oracle Helpシステムのオーサリング・ユーティリティとプロセスについて説明します。

この節の内容は以下のとおりです。

- Oracle Helpシステムのオーサリングについて

- Oracle Help for Javaに付属のオーサリング・ユーティリティ

- 埋込みヘルプのオーサリング

9.1 Oracle Helpシステムのオーサリングについて

Oracle Helpにフル機能のオーサリング環境はありません。オーサリング・ツールを使用しないでヘルプ・システムをオーサリングすることは難しくありませんが、Oracle Helpを直接サポートするAdobe RoboHelp、Quadralay WebWorks、AuthorIT Software CorporationのAuthorITなどのツールを使用する方が簡単です。

Oracle Helpのファイル形式はJavaHelpファイル形式に基づいているため、JavaHelpシステムを作成するオーサリング・ツールも使用できます。ただし、Oracle Help固有の機能は手動で追加する必要があります。Oracle HelpはMicrosoft社のHTML Helpの制御ファイル形式もサポートしているため、HTML Helpをサポートするオーサリング・ツールも使用できます。ただしこの場合も、Oracle Help固有の機能は手動で追加する必要があります。

OHJおよびOHWでは同じファイル形式を使用するため、作成したヘルプ・システムは変更なしで表示できます。

Oracle Helpヘルプ・システムの基本的なオーサリング手順は次のとおりです。

1. ヘルプ・システムのトピックを構成するHTMLページを記述します。

2. ヘルプセット・ファイルを作成します。このXMLファイルは、ヘルプ・システムを識別し、ユーザー・インタフェースの様々な側面を始めとする数多くのプロパティを指定します。たとえば、表示するナビゲータ(通常はタブとして表示される)はこのファイルに指定します。標準のナビゲータは「目次」、「索引」および「検索」です。このファイルはOracle Helpのメイン制御ファイルであり、必須です。

3. マップ・ファイルを作成します。このXMLファイルは、トピックIDをHTMLページにマップします。トピックIDは、状況依存コールのためのAPI、目次ファイル、索引ファイル、リンク・ファイルおよびトピック・ファイル内のトピックIDリンクで使用されます。このファイルは必須です。

4. 索引ファイルを作成します。このXMLファイルは、「索引」タブに表示されるキーワードの索引を定義します。ヘルプ・システムで索引を使用しない場合、このファイルは不要です。ただし、索引を使用しない場合は、ヘルプセット・ファイルに「索引」タブを定義しないでください。

5. 目次ファイルを作成します。このXMLファイルは、「目次」タブに表示される目次を定義します。ヘルプ・システムで目次を使用しない場合、このファイルは不要です。ただし、目次を使用しない場合は、ヘルプセット・ファイルに「目次」タブを定義しないでください。

6. 検索索引を生成します。このファイルには、ユーザーが「検索」タブで単語または句を検索するときに使用されるデータが含まれます。このファイルはオプションです。ただし、検索索引を使用しない場合は、ヘルプセット・ファイルに「検索」タブを定義しないでください。ヘルプ・システムの作成にオーサリング・ツールを使用していない場合は、Oracle Helpに付属の索引作成ツールを使用できます。「テキスト検索インデクサの使用方法」を参照してください。

7. 関連リンクを使用する場合は、リンク・ファイルを作成します。このXMLファイルは、トピックを関連リンク・キーワードに関連付けます。このファイルはオプションです。

9.2 Oracle Help for Javaに付属のオーサリング・ユーティリティ

Oracle Help for Javaには2つのオーサリング・ユーティリティが付属しています。Oracle Helpをサポートするオーサリング・ツールがない場合は、Oracle Helpシステムのオーサリングにこの2つのユーティリティを使用できます。それぞれの詳細は、該当するリンクを参照してください。

- ヘルプセット・オーサリング・ウィザード: このウィザードは、特定の互換性のないヘルプ・コンテンツおよび制御ファイルをOracle Helpで使用できるファイルに変換します。たとえば、このウィザードを使用すると、RoboHelp 2000 for Microsoft HTML Helpで生成されたファイルからOracle Helpシステムを作成できます。

- テキスト検索インデクサ: このユーティリティは、ユーザーが「検索」タブで単語または句を検索するときにOracle Helpで使用される検索索引ファイルを生成します。

9.3 埋込みヘルプのオーサリング

OHWの埋込みヘルプ機能の一部として、アプリケーションの各コンポーネントに複数のレベルのヘルプを関連付け、各レベルが特定のユーザー動作によってトリガーされるようにできます。ヘルプのレベルは次のとおりです。

- 定義テキスト

- 方法テキスト

- フル・ヘルプ

どのレベルとも、どのようなHTMLコンテンツでもかまいません。定義テキストおよび方法テキストは、集合的に埋込みヘルプ・コンテンツと呼ばれます。フル・ヘルプ・コンテンツは、ヘルプのウィンドウに単独のトピックとして表示されるコンテンツです。

- 定義テキストは、ハードコード化されたスタイル・クラス名definitionを使用して<div>内で指定されます。title属性がある場合は、定義テキストのトピックIDを表します。ここではプレーン・テキストのみを入力でき、この<div>タグではHTMLコンテンツは処理されないことに注意してください。次に例を示します。

<div title="topicId" class="definition"> Any plain text </div>

- 方法テキストは、ハードコードされたスタイル・クラス名instructionsを使用して<div>内に指定されます。title属性がある場合は、方法テキストのトピックIDを表します。次に例を示します。

<div title="topicId" class="instructions"> Any HTML content </div>

トピックの定義テキストおよび方法テキストは、一般的なHTMLを使用してトピック・ファイルに次のように指定します。

9.3.1 HTMLファイル

定義テキストと指示テキストの<div>タグは、HTML本文内に表示されます。いずれのレベルのHelpのコンテンツも同じファイルで指定する必要があります。いずれかのレベルが同じファイルで使用できない場合、コンテンツは未定義と見なされます。

1つのトピックIDに対する定義テキストおよび方法テキストのコンテンツは、既存のトピックHTMLファイルに指定します。topic1.htmlという名前のサンプル・トピックを次に示します。

<html>
<body>

<div title="topic1" class="definition">
This is Definition Text help content.
</div>

...

<div title="topic1" class="instructions">
This is <b>Instructions Text</b> help content.
</div>

...

This is the regular Full Help content.

...

</body>
</html>

注意:

- タイトル属性はトピックIDを表しており、オプションです。指定がない場合は、コンテナHTMLファイルのトピックIDが考慮されます。指定がある場合は、その埋込みヘルプを含むHTMLファイルのトピックIDと一致していることが必要です。

- <div>は<body>のどこにあってもかまいません。

- 定義スタイル・クラスと方法スタイル・クラスは、既存のスタイル・シートに定義できます。

- この2つのスタイル・クラスは、フル・ヘルプ・コンテンツとの区別に必要な視覚的な手がかりを与えるよう定義できます。たとえば、淡い黄色の背景と灰色の枠を使用して定義テキストであることを示し、淡い青の背景と青い枠を使用して方法テキストであることを示すことができます。コンテンツを作成および編集するときには、このようにするとわかりやすくなります。

- ヘルプの作成時にフル・ヘルプ・コンテンツのみを表示する必要が生じた場合は、この2つのスタイル・クラスを非表示(display:none)に定義できます。これはプレビューのときに便利です。

- <div>にどちらかのスタイル・クラス名が指定されたHTMLの索引は生成されません。

10 ヘルプセット・オーサリング・ウィザード

この章では、ヘルプセット・オーサリング・ウィザードと、その各種画面について説明します。また、このウィザードを使用して、ヘルプ・システムを作成する方法についても説明します。

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

- ヘルプセット・オーサリング・ウィザードについて

- ウィザードの起動

- ヘルプセット・ファイルの作成

- オーサリング・ツールとHTMLブラウザの指定

- ソース・ディレクトリの指定

- ビューの定義

- 全文検索ビューの定義

- マップ・ファイルの定義

- 関連リンクの変換

- ポップアップ・ウィンドウ・リンクの変換

- ウィンドウ・タイプの定義

- ヘルプセットの作成

10.1 ヘルプセット・オーサリング・ウィザードについて

ヘルプセット・オーサリング・ウィザード(OHJオーサリング・ウィザードとも呼ばれる)は、Oracle Helpで使用される特定の制御ファイルを生成します。オーサリング・ウィザードの機能は制限されています。つまり、この機能は、すべての機能を備えたヘルプ・オーサリング・ツールになるのではなく、他の形式で作成されるヘルプ・システムの変換に使用されることが主な目的になります。たとえば、ヘルプセット・ウィザードを使用すると、Oracle Helpに対応していなかった、旧リリースのRoboHelp HTMLで生成されたファイルからOracle Helpシステムを作成できます。

現行バージョンのウィザードでは、ヘルプセット・ファイル、検索索引ファイルおよびマップ・ファイルを生成できます。また、特定のJavaScriptポップアップ・リンクをOracle Help形式に変換します。ただし、ウィザードは、現時点では、(存在するオプションを問わず)RoboHelp HTML関連リンクを、Oracle Helpの相当する形式に変換しません。

10.2 ウィザードの起動

OHJをWindowsにインストールすると、ウィザードを起動するためのバッチ・ファイルと初期化ファイルが、OHJをインストールしたパスに基づいて生成されます。また、ウィザードを起動するためのショートカットが、Windowsの「スタート」メニューに追加されます。ウィザードを起動するには、このショートカットを選択します。また、コマンド・プロンプトで次のコマンドを発行して起動することもできます。

<OHJ_HOME>\bin\authoringWizard.bat

たとえば、OHJをD:\ohelpフォルダにインストールした場合、ウィザードは次のコマンドで実行できます。

D:\ohelp\bin\authoringWizard.bat

前述のコマンドを実行すると、OHJオーサリング・ウィザードのようこそ画面が表示されます。「次へ」をクリックして、続行します。

図10-1 OHJオーサリング・ウィザード: ようこそ

10.3 ヘルプセット・ファイルの作成

OHJオーサリング・ウィザードの最初の手順では、ヘルプセット(.hs)ファイルを作成します。また、後で既存のヘルプセット・ファイルを開いて編集することもできます。ヘルプセットの詳細は、第5.2項「ヘルプセット・ファイル」を参照してください。

図10-2 OHJオーサリング・ウィザード: ヘルプセット・ファイル

次の情報を使用して、ヘルプセット・ファイル・ページの各フィールドにデータを入力します。

フィールド

説明

新しいOracle Help for Javaヘルプセット・ファイルを作成する

このオプションは、ヘルプセット・ファイルを作成する場合に選択します。

既存のOracle Help for Javaヘルプセット・ファイルを開く

このオプションは、既存のヘルプセット・ファイルを編集する場合に選択します。

ファイル

参照をクリックして、編集するヘルプセット・ファイルを選択します。

完了した後、次へをクリックして続行します。

10.4 オーサリング・ツールとHTMLブラウザの指定

OHJオーサリング・ウィザードのソースとターゲットの選択ページでは、オーサリング・ツールと、ヘルプ・ファイルの表示に使用するブラウザを選択できます。

図10-3 OHJオーサリング・ウィザード: ソースとターゲットの選択

次の情報を使用して、ソースとターゲットの選択ページの各フィールドにデータを入力します。

フィールド

説明

オーサリング・ツールを選択する

ヘルプ・ファイルの作成に使用するオーサリング・ツールを選択します。

HTMLブラウザを選択する

HTMLファイルの表示に使用するブラウザを選択します。

完了した後、次へをクリックして続行します。

10.5 ソース・ディレクトリの指定

OHJオーサリング・ウィザードのディレクトリの指定ページでは、HTMLファイルやその他の制御ファイルを格納するディレクトリを選択できます。

図10-4 OHJオーサリング・ウィザード: ディレクトリの指定

次の情報を使用して、ディレクトリの指定ページの各フィールドにデータを入力します。

フィールド

説明

ディレクトリ

参照をクリックし、HTMLファイルのソース・ディレクトリを選択します。既存のヘルプセット・ファイルを指定した場合は、このフィールドは編集できず、ヘルプセット・ファイルのディレクトリの場所が表示されます。

サブディレクトリを含める

このチェック・ボックスを選択すると、ディレクトリで選択したディレクトリのサブディレクトリが含められます。

ヘルプセット・タイトル

ヘルプセット・ファイルのタイトルを指定します。

完了した後、次へをクリックして続行します。

10.6 ビューの定義

OHJオーサリング・ウィザードのビューの定義ページでは、OHJヘルプ・ナビゲータ・ウィンドウのビューを定義できます。目次やキーワードの索引のビューを作成したり、カスタム・ビューを定義します。

図10-5 OHJオーサリング・ウィザード: ビューの定義

フィールド

説明

新規

新しいビューを作成し、そのビューの名前を現在のビューリストに追加します。

削除

選択したビューを現在のビューリストから削除します。

完了した後、次へをクリックして続行します。

10.6.1 新しいビューの定義

OHJオーサリング・ウィザードでは、ヘルプに複数のビューを作成できます。デフォルトでは、ビューは定義されません。新しいビューを定義するには、新規をクリックします。図10-6は、新しいビューの作成時に、ウィザードのビューの定義ページで使用できるフィールドを示します。

図10-6 OHJオーサリング・ウィザード: 新しいビューの定義

次の情報を使用して、ビューの定義ページの各フィールドにデータを入力します。

フィールド

説明

ビュー・タイプ

定義される新しいビューのビュー・タイプを選択します。ビュー・タイプとしてOHJ TOCナビゲータ、OHJキーボード・ナビゲータまたはOHJ検索ナビゲータを選択するか、カスタム・ナビゲータを定義します。

データ・エンジン

新しいビューのデータ・エンジンを選択します。エンジンとしてHHCエンジン、HHKエンジン、XML TOCエンジン、XML索引エンジン、TOCエンジン、TOKエンジンまたは検索エンジンを選択するか、カスタム・データ・エンジンを定義します。

データのロケーション

参照をクリックし、制御ファイルの場所を選択します。

タブのラベル

チェック・ボックスを選択し、OHJヘルプ・ナビゲータ・ウィンドウに表示されるタブのラベルを入力します。

ビューのタイトル

このチェック・ボックスを選択し、ビューのタイトルを入力します。

10.6.2 カスタム・ビュー・タイプの定義

使用可能なビューでは要件が満たされない場合は、カスタム・ビューを定義できます。

カスタム・ビュー・タイプを作成するには、ビューの定義ページのビュー・タイプ・ドロップダウン・リストからカスタムを選択します。カスタム・タイプの定義ダイアログ・ボックスが表示されます。

図10-7 OHJオーサリング・ウィザード: カスタム・ビュー・タイプの定義

次の情報を使用して、ビューの定義ページの各フィールドにデータを入力します。

フィールド

説明

識別名

ビューの一意の名前を指定します。

Navigatorサブクラス

Javaクラスの名前を指定します。指定するクラスはoracle.help.navigator.Navigatorのサブクラスであることが必要です。

10.6.3 カスタム・データ・エンジンの定義

使用可能なデータ・エンジンでは要件が満たされない場合は、カスタム・データ・エンジンを定義できます。

カスタム・データ・エンジンを作成するには、ビューの定義ページのデータ・エンジンドロップダウン・リストからカスタムを選択します。カスタム・データ・エンジンの定義ダイアログ・ボックスが表示されます。

図10-8 OHJオーサリング・ウィザード: カスタム・データ・エンジンの定義

次の情報を使用して、ビューの定義ページの各フィールドにデータを入力します。

フィールド

説明

識別名

データ・エンジンの一意の名前を指定します。

DataEngineサブクラス

Javaクラスの名前を指定します。指定するクラスはoracle.help.dataengine.DataEngineのサブクラスであることが必要です。

10.7 全文検索ビューの定義

OHJオーサリング・ウィザードの全文検索ビュー・ページでは、検索ビューの作成およびヘルプの全文検索索引の生成ができます。

全文検索索引を作成するには、ヘルプセットの全文検索索引を生成するチェック・ボックスを選択します。

図10-9 OHJオーサリング・ウィザード: 全文検索ビュー

次の情報を使用して、全文検索ビュー・ページの各フィールドにデータを入力します。

フィールド

説明

ヘルプセットの全文検索索引を生成する

全文検索索引を作成するには、このチェック・ボックスを選択します。

キャラクタ・セット・エンコーディングを指定してください

必要なキャラクタ・セット・エンコーディングをドロップダウン・リストから選択します。デフォルトでは、西ヨーロッパ言語(ISO 8859-1)が選択されます。

検索で大文字と小文字を区別する

このチェック・ボックスを選択すると、大文字と小文字を区別する検索機能をヘルプで使用できるようになります。

数字の検索を有効にする

このチェック・ボックスを選択すると、数値の検索機能をヘルプで使用できるようになります。

完了した後、次へをクリックして続行します。

10.8 マップ・ファイルの定義

OHJオーサリング・ウィザードのマップ・ファイル・ページでは、ヘルプで使用するマップ・ファイルの作成、および一意のトピックIDとヘルプ・トピックとの関連付けができます。

図10-10 OHJオーサリング・ウィザード: 全文検索ビュー

次の情報を使用して、全文検索ビュー・ページの各フィールドにデータを入力します。

フィールド

説明

マップ・ファイルを含めない

マップ・ファイルを用意しないことを指定します。このオプションは、ヘルプが状況依存ヘルプでない場合に役立ちます。

各HTMLファイルの<meta>タグを使用してマップ・ファイルを作成する

<meta>タグからマップ・ファイルを作成することを指定します。
一部のヘルプ・オーサリング・ツール(RoboHelpなど)は、HTMLファイル内のmetaタグにトピックIDを挿入します。このウィザード・オプションは、metaタグを検出して、そのタグからマップ・ファイルを作成します。

ツールで生成された別名(.ali)ファイルまたはヘッダー(.h)ファイルを使用してマップを作成する

生成された別名ファイルまたはヘッダー・ファイルからマップ・ファイルを作成することを指定します。参照をクリックし、マップ・ファイルの名前および場所を指定します。

既存のマップ・ファイルを含める

既存のマップ・ファイルを使用することを指定します。参照をクリックし、マップ・ファイルの名前および場所を指定します。

完了した後、次へをクリックして続行します。

10.9 関連リンクの変換

OHJオーサリング・ウィザードの関連リンク・ページでは、既存のヘルプ・システムに定義された関連リンクを独自の関連リンク・プロトコルに変換できます。

図10-11 OHJオーサリング・ウィザード: 関連リンク

次の情報を使用して、関連リンクページの各フィールドにデータを入力します。

フィールド

説明

OHJ ICEbrowserプロトコルを使用するよう関連リンクを変換する

すべての関連リンクをICEbrowser対応のalinkプロトコルに変換することを指定します。

関連リンクをリンクのハードコードされたリストに変換する

すべての関連リンクをリンクのハードコードされたリストに変換することを指定します。

すべての関連リンクを削除する

すべての関連リンクをヘルプ・ページから削除することを指定します。

完了した後、次へをクリックして続行します。

10.10 ポップアップ・ウィンドウ・リンクの変換

OHJオーサリング・ウィザードのポップアップ・ウィンドウ・ページでは、既存のヘルプ・システムに定義されたポップアップ・ウィンドウ・リンクを独自のポップアップ・リンク・プロトコルに変換できます。

図10-12 OHJオーサリング・ウィザード: ポップアップ・ウィンドウ

次の情報を使用して、ポップアップ・ウィンドウ・ページの各フィールドにデータを入力します。

フィールド

説明

OHJ ICEbrowserプロトコルを使用するようポップアップ・ウィンドウを変換する

すべてのポップアップ・ウィンドウ・リンクをICEbrowser対応のプロトコルに変換することを指定します。

すべてのポップアップ・ウィンドウを削除する

すべてのポップアップ・ウィンドウ・リンクをヘルプ・ページから削除することを指定します。

完了した後、次へをクリックして続行します。

10.11 ウィンドウ・タイプの定義

OHJオーサリング・ウィザードのウィンドウ・タイプ・ページでは、ウィンドウ・タイプを定義できます。デフォルトでは、ウィンドウ・タイプは定義されません。新しいウィンドウ・タイプを定義すると、ウィンドウの識別情報、画面上の配置、色の属性およびそのウィンドウで使用できるツールバー・ボタンを構成できます。

図10-13 OHJオーサリング・ウィザード: ウィンドウ・タイプの定義

次の情報を使用して、ウィンドウ・タイプの定義ページの各フィールドにデータを入力します。

フィールド

説明

新規

新しいウィンドウ・タイプを作成し、そのウィンドウの名前をウィンドウ・タイプリストに追加します。

削除

選択したウィンドウ・タイプをウィンドウ・タイプリストから削除します。

新しいウィンドウ・タイプを定義するには、新規をクリックし、その属性を構成します。構成できる属性は次のとおりです。

10.11.1 ウィンドウの識別情報

ウィンドウ・タイプの定義ページの識別情報タブでは、ウィンドウの名前とタイトルを定義できます。

図10-14 OHJオーサリング・ウィザード: ウィンドウ・タイプの識別情報のプロパティ

次の情報を使用して、ウィンドウ・タイプの定義ページの識別情報タブの各フィールドにデータを入力します。

フィールド

説明

名前

一意のウィンドウ名を指定します。

タイトル

ウィンドウ・タイトルを指定します。

指定がない場合はこのウィンドウ・タイプを使用する

このチェック・ボックスを選択すると、このウィンドウがデフォルト・ウィンドウになります。

10.11.2 配置の属性

ウィンドウ・タイプの定義ページの配置タブでは、画面上でのウィンドウのサイズと位置を構成できます。

図10-15 OHJオーサリング・ウィザード: ウィンドウ・タイプの配置のプロパティ

次の情報を使用して、ウィンドウ・タイプの定義ページの配置タブの各フィールドにデータを入力します。

フィールド

説明

高さ

ウィンドウの高さを指定します。また、使用する単位としてピクセルまたはパーセントを選択します。

幅

ウィンドウの幅を指定します。また、使用する単位としてピクセルまたはパーセントを選択します。

X位置

ウィンドウのX座標を指定します。また、使用する単位としてピクセルまたはパーセントを、方向として左からまたは右からを選択します。

Y位置

ウィンドウのY座標を指定します。また、使用する単位としてピクセルまたはパーセントを、方向として上からまたは下からを選択します。

10.11.3 スタイルの属性

ウィンドウ・タイプの定義ページのスタイルタブでは、ウィンドウの配色(テキスト色と背景色)を定義できます。

図10-16 OHJオーサリング・ウィザード: ウィンドウ・タイプのスタイルのプロパティ

次の情報を使用して、ウィンドウ・タイプの定義ページのスタイルタブの各フィールドにデータを入力します。

フィールド

説明

テキストの前景色

ウィンドウに表示されるテキストの色を16進カラー・コードで指定します。色を選択するには、選択をクリックし、目的のテキスト色を選択します。

リンクの前景色

ウィンドウに表示されるリンクの色を16進カラー・コードで指定します。色を選択するには、選択をクリックし、目的のリンク・テキスト色を選択します。

ページの背景色

ウィンドウのページの背景の色を16進カラー・コードで指定します。色を選択するには、選択をクリックし、目的のページ色を選択します。

10.11.4 ツールバー・ボタン

ウィンドウ・タイプの定義ページのツールバー・ボタンタブでは、ヘルプ・トピック・ウィンドウで使用できるツールバー・ボタンを構成できます。

図10-17 OHJオーサリング・ウィザード: ウィンドウ・タイプのツールバー・ボタンのプロパティ

次の情報を使用して、ウィンドウ・タイプの定義ページのツールバー・ボタンタブの各フィールドにデータを入力します。

フィールド

説明

ボタンのデフォルト・セットを表示する

ツールバー・ボタンのデフォルト・セットを表示するには、このチェック・ボックスを選択します。デフォルトでは、すべてのツールバー・ボタンを使用できます。ツールバー・ボタンをカスタマイズするには、このチェック・ボックスの選択を解除します。

「ナビゲータ」ボタン

「ナビゲータ」ツールバー・ボタンをウィンドウに追加するには、このチェック・ボックスを選択します。「ナビゲータ」ボタンを使用すると、「ヘルプ・ナビゲータ」ウィンドウが開きます。

「検索」ボタン

「検索」ツールバー・ボタンをウィンドウに追加するには、このチェック・ボックスを選択します。「検索」ボタンを使用すると、ヘルプ・ページ全体に対してテキストを検索できます。

「印刷」ボタン

「印刷」ツールバー・ボタンをウィンドウに追加するには、このチェック・ボックスを選択します。「印刷」ボタンを使用すると、トピックを印刷できます。

「進む」および「戻る」ボタン

「進む」および「戻る」ツールバー・ボタンをウィンドウに追加するには、このチェック・ボックスを選択します。「進む」ボタンと「戻る」ボタンを使用すると、前に開いたトピックにナビゲートし、現在のトピックに戻ってくることができます。

「ドッキング」および「ドッキング解除」ボタン

「ドッキング」および「ドッキング解除」ツールバー・ボタンをウィンドウに追加するには、このチェック・ボックスを選択します。「ドッキング」ボタンおよび「ドッキング解除」ボタンを使用すると、ヘルプ・トピック・ウィンドウと「ヘルプ・ナビゲータ」ウィンドウのドッキングおよびドッキング解除ができます。

10.12 ヘルプセットの作成

OHJオーサリング・ウィザードの終了ページでは、ウィザードで選択したオプションに基づいて、ヘルプセットが作成されます。

図10-18 OHJオーサリング・ウィザード: ヘルプセットの作成

次の情報を使用して、ヘルプセットの作成ページの各フィールドにデータを入力します。

フィールド

説明

ベース名

ヘルプ・セットのベース名を指定します。ベース名は、ファイル名拡張子なしで、制御ファイルの名前を定義します。たとえば、ベース名がmyprojectの場合、制御ファイル名はmyproject.hhc、myproject.hhk、myproject.idxなどのようになります。

バックアップ・コピーを作成する

更新されたファイルのバックアップ・コピーを作成することを指定します。ファイルは、.bakという拡張子で保存されます。

バックアップ・コピーを作成しない

更新されたファイルのバックアップ・コピーを作成しないことを指定します。

完了した後、終了をクリックして、ヘルプセット・ファイルを生成します。

11 テキスト検索インデクサの使用方法

この章では、テキスト検索インデクサについて説明します。また、テキスト検索インデクサを使用して索引ファイルを生成する方法について説明します。

この節の内容は以下のとおりです。

- テキスト検索インデクサについて

- Java要件

- インデクサの実行

- JapaneseIndexerの実行

11.1 テキスト検索インデクサについて

Oracle Help for Javaには、Javaベースのテキスト検索インデクサが付属しています。インデクサは、Oracle Helpでのテキスト検索に使用される.idxファイルを生成します。テキスト検索インデクサには、日本語コンテンツ用と非日本語コンテンツ用の2つのバージョンがあります。

11.2 Javaの要件

テキスト検索インデクサには、Java5 Standard Edition以上が必要です。JIT (Just In Time Compiler)をオンのままにしておくと、パフォーマンスが大幅に向上します。また、Java仮想マシンのヒープ・サイズを最大にしてください。

11.3 インデクサの実行

インデクサを実行する手順は、次のとおりです。

1. OHJインデクサJARファイルhelpindexer-version.jarをCLASSPATHに含めます。

2. コマンド・プロンプトからインデクサを実行します。インデクサでは、次のコマンドライン引数をサポートしています。

[-l=locale] [-e=charset] dirnameindexfilename

各要素の説明は次のとおりです。

引数

説明

-l=locale

オプション(推奨)のlocaleパラメータは、二文字形式のISO 639言語コードおよびISO 3166国コードを使用して指定します。形式はlanguage_COUNTRYまたはlanguage_COUNTRY_VARIANTです。localeの指定がない場合は、システムのデフォルト・ロケールが使用されます。

-e=charset

オプションの(ただし推奨の)キャラクタ・セット・パラメータは、索引付けされるHTMLファイルのJava対応キャラクタ・セット・エンコーディングの名前になります。エンコーディングを指定しない場合、現行システムのデフォルト・ロケールのデフォルト・キャラクタ・セット・エンコーディングが使用されます。指定する場合、値をJava対応キャラクタ・セット・エンコーディングの名前にする必要があります。Java SEの場合、http://download.oracle.com/javase/1.5.0/docs/guide/intl/encoding.doc.htmlを参照してください。

dirname

索引を作成するHTMLファイルが含まれるベース・ディレクトリ。インデクサでは、このディレクトリおよびそのサブディレクトリ(存在する場合)の下にあるすべてのファイルの索引が作成されます。

indexfilename

生成する索引ファイルの名前。

たとえば、java -mx64m oracle.help.tools.index.Indexer -l=en_US -e=8859_1 D:\MyHTMLFiles myIndex.idxのように指定します。

前述のコマンドでは、ロケールの言語を英語、国をアメリカ、エンコーディングを8859_1に設定し、D:\MyHTMLFilesディレクトリの索引を作成して、myIndex.idxファイルを作成します。

11.4 JapaneseIndexerの実行

インデクサを実行する手順は、次のとおりです。

1. OHJインデクサJARファイルhelpindexer-version.jarをCLASSPATHに含めます。

2. コマンド・プロンプトからインデクサを実行します。インデクサでは、次のコマンドライン引数をサポートしています。

[-e=charset] dirnameindexfilename

各要素の説明は次のとおりです。

引数

説明

-e=charset

オプションの(ただし推奨の)キャラクタ・セット・パラメータは、索引付けされるHTMLファイルのJava対応キャラクタ・セット・エンコーディングの名前になります。エンコーディングを指定しない場合、現行システムのデフォルト・ロケールのデフォルト・キャラクタ・セット・エンコーディングが使用されます。指定する場合、値をJava対応キャラクタ・セット・エンコーディングの名前にする必要があります。Java SEの場合、http://download.oracle.com/javase/1.5.0/docs/guide/intl/encoding.doc.htmlを参照してください。

dirname

索引を作成するHTMLファイルが含まれるベース・ディレクトリ。インデクサでは、このディレクトリおよびそのサブディレクトリ(存在する場合)の下にあるすべてのファイルの索引が作成されます。

indexfilename

生成する索引ファイルの名前。

たとえば、java -mx64m oracle.help.tools.index.JapaneseIndexer -e=MS932 D:\MyHTMLFiles myIndex.idxのように指定します。

前述のコマンドでは、JapaneseIndexerを実行し、エンコーディングをMS932に設定し、D:\MyHTMLFilesディレクトリの索引を作成して、myIndex.idxファイルを作成します。

第IV部

Oracle Help for Java

この部では、Oracle Help for Java Developer's Kitの使用について説明します。次の章で構成されます。

- 第12章「Oracle Help for Java Developer's Kitの概要」
この章では、Oracle Help for Java Developer's Kitの概要について説明します。

- 第13章「アプリケーションへのOHJの追加」
この章では、アプリケーションにOHJヘルプを追加する方法について説明します。

- 第14章「アプリケーションでの状況依存ヘルプの有効化」
この章では、アプリケーションで状況依存ヘルプを有効にする方法について説明します。

- 第15章「OHJヘルプ・システムのデプロイ」
この章では、OHJヘルプのデプロイについて説明します。

12 Oracle Help for Java Developer's Kitの概要

この章では、Oracle Help for Java Developer's Kit (OHJDK)の概要と、OHJDKの内容、およびOHJDKのインストール方法について説明します。

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

- Oracle Help for Java Developer's Kitについて

- JDeveloperのOracle Help for Javaランタイム

- OHJDKを使用する前に

12.1 Oracle Help for Java Developer's Kitについて

Oracle Help for Java Developer's Kitは、Java環境でHTMLベースのヘルプ・コンテンツを開発および表示するための一連のJavaコンポーネントとJava APIです。この中には、JavaアプレットおよびJavaアプリケーションで状況依存ヘルプを実装するために必要なOracle Help for Java (OHJ)エンジンとその他のツールが含まれます。

Oracle Help for Javaエンジンは、JavaアプリケーションとJavaアプレット用の機能がすべて装備されたJavaベースのヘルプ・システムです。また、状況依存ヘルプを移動および表示するためのピュアJavaコンポーネントを備えています。Oracle Help for Javaは無料で入手でき、ご自身のアプリケーションのヘルプ・システムとして再配布できます(リリースで配布されるライセンスを参照)。

Oracle Help for Javaは、JavaHelpやMicrosoftのHTML Help標準の拡張形式など、いくつかのファイル形式のヘルプ・コンテンツをサポートします。ヘルプ・コンテンツの作成にヘルプ・オーサリング・ツールを使用しない場合は、「Oracle Helpのファイル形式」を参照することをお薦めします。サード・パーティのOHJ対応ヘルプ・オーサリング・システムを使用している場合は、そのドキュメントを参照してください。

12.2 JDeveloperのOracle Help for Javaランタイム

Oracle Help for Javaランタイム・ライブラリohj.jarは、JDeveloperの一部として配布されます。開発者がOracle Help for Javaと自身のアプリケーションを統合する場合、Oracle Help for Javaライブラリを依存性ライブラリとして追加するようにプロジェクト設定を変更できます。サンプル・コード、ヘルプセット・オーサリング・ウィザード、インデクサおよびデモを含むOracle Help for Javaリリース一式は、次のOracle Technology NetworkのOracle Helpページから無料で入手できます。

http://www.oracle.com/technetwork/topics/index-083946.html

12.3 OHJDKを使用する前に

Oracle Help for Java Developer's Kit (OHJDK)は、Java環境でHTMLベースのヘルプ・コンテンツを開発および表示するための一連のJavaコンポーネントとJava APIです。この中には、JavaアプレットおよびJavaアプリケーションで状況依存ヘルプを実装するために必要なOracle Help for Java (OHJ)エンジンとその他のツールが含まれます。

この項では、OHJDKの内容と、OHJヘルプ・システムを開発するための設定方法について説明します。この項の内容は次のとおりです。

- 第12.3.1項「OHJDKのインストール」

- 第12.3.2項「OHJDKリリースの内容」

- 第12.3.3項「OHJDK開発のためのJava CLASSPATHの設定」

12.3.1 OHJDKのインストール

次の手順は、OHJDKのインストール・プロセスの説明です。

- 最新のOracle Help for Java Developer's KitをOTNからダウンロードします。Windowsの場合は、Windows実行可能ファイルまたは実行可能JARファイルをダウンロードします。SolarisまたはUNIXの場合は、バイナリ・ファイルをダウンロードします。

- Windowsの場合は、Windows実行可能ファイルまたは実行可能JARファイルをダブルクリックして、インストール・ウィザードを起動します。デフォルトで、OHJDKはC:\Program Files\ohelpにインストールされます。SolarisおよびUNIXの場合は、バイナリ・ファイルを実行して、インストール・ウィザードを起動します。

- インストール・フォルダを開いて、第12.3.2項「OHJDKリリースの内容」で説明されているファイルを確認します。

12.3.2 OHJDKリリースの内容

OHJDKには、OHJエンジンのためのコンパイル済ライブラリと、オーサリング・ツールやデモンストレーションのためのライブラリが含まれています。これらのライブラリは、JAR (Java ARchive)形式で配布されます。OHJDKには、このページを含むドキュメントも含まれています。

各ファイルについては、次の項で説明しています。

- 第12.3.2.1項「OHJエンジン」

- 第12.3.2.2項「オーサリング・ツール」

- 第12.3.2.3項「デモンストレーション・ファイル」

- 第12.3.2.4項「ドキュメント」

12.3.2.1 OHJエンジン

これらのファイルには、OHJエンジンの実装とその依存性で使用されるバイナリ・ファイルが含まれています。これらのファイルは、製品アプリケーションとともに再配布する必要があります。

表12-1 OHJのバイナリ

ファイル

目次

ohj.jar

ヘルプ・エンジンの最適化済バイナリ。

oracle_ice.jar

ICEsoft Technologies, Inc.のICEbrowserをOracleがカスタマイズしたバージョン。OHJエンジンは、HTMLトピックの表示にICEbrowserを使用します。

12.3.2.2 オーサリング・ツール

次のJARファイルには、ヘルプセット・オーサリング・ウィザードおよびテキスト検索インデクサの実装が含まれています。これらのファイルは、製品アプリケーションとともに再配布するためのものではありません。

表12-2 OHJのオーサリング・ツール

ファイル

目次

help-wizard.jar

ヘルプセット・オーサリング・ウィザードの実装。ヘルプセット・オーサリング・ウィザードの実行には、OHJDKインストールのbinディレクトリに作成されるバッチ・ファイルを使用できます。

help-indexer.jar

OHJテキスト検索インデクサの実装。この全文検索インデクサを使用してOracle Helpの検索索引(.idx)ファイルを作成できます。

12.3.2.3 デモンストレーション・ファイル

次のJARファイルには、OHJDKとともに配布されるデモンストレーション・プログラムが含まれています。このファイルは、製品アプリケーションとともに再配布するためのものではありません。

表12-3 OHJのデモンストレーションJARファイル

ファイル

目次

help-demo.jar

デモンストレーションのバイナリとソース・コードおよびHTML形式とOracle Help制御ファイル形式のサンプル・ドキュメント。

デモンストレーション・プログラムを実行するには、OHJDKインストールのbinディレクトリにあるバッチ・ファイルを実行します。Windows用のOHJインストーラは、Windowsの「スタート」メニューにショートカットを追加します。デモ・プログラムが使用するサンプル・コンテンツは、demodocサブディレクトリにあります。

OHJをアプリケーションに統合する際は、(helpdemo-version_num.jarファイルに含まれている)デモンストレーション・プログラムのソース・コードの検討が役立ちます。次のデモは特に参考になります。

表12-4 OHJのデモンストレーション・ファイル

ファイル

目次

ChoiceDemo.java

(OHJの機能のデモ)

次の機能について説明するサンプルJavaコード。

- Helpオブジェクトの構成

- ヘルプセット(データ)の追加

- OHJのナビゲータ・ウィンドウの表示

- 複数のヘルプセットの表示

CSHDemo.java

(状況依存ヘルプのデモ)

次の機能について説明するサンプルJavaコード。

- メニューからのヘルプ・システムの起動

- 特定のアプリケーション・コントロールへのヘルプ・トピックの関連付け

- [F1]キーによるヘルプ起動の有効化

- 右クリックで表示されるポップアップ・メニュー・ヘルプの実装

12.3.2.4 ドキュメント

OHJDKには次のドキュメントが用意されています。

表12-5 OHJのドキュメント

ドキュメント

内容

OHJDKリリースでの場所

OHJ APIリファレンス・ドキュメント

OHJのApplication Program Interface (API)のドキュメントがJavaDocとして用意されています。

OHJDKインストールのdoc/javadocサブディレクトリ。APIドキュメントを表示するには、HTMLブラウザでindex.htmlファイルを開きます。

Oracle Helpガイド

このドキュメント

OHJDKインストールのdocサブディレクトリ。

12.3.3 OHJDK開発のためのJava CLASSPATHの設定

OHJDKを使用して開発する場合は、OHJエンジン・ライブラリとツールキットの依存関係を環境のクラス・パスに追加する必要があります。

次に例を示します。

- Windows 2000またはXPの場合は、「環境変数」ダイアログ・ボックスのCLASSPATHを設定します。このダイアログ・ボックスには、「コントロール パネル」の「システムのプロパティ」の「詳細設定」タブからアクセスします。

- Windows NTの場合は、「コントロール パネル」の「システムのプロパティ」の「環境」タブでCLASSPATH変数を設定します。

- Windows 95/98の場合は、autoexec.batファイルでSETコマンドを使用します。

- UNIXの場合は、setenvコマンドを使用してシェルの環境変数を設定します。

CLASSPATH変数の設定方法の詳細は、使用しているJava仮想マシン(JVM)およびオペレーティング・システムのドキュメントを参照してください。

13 アプリケーションへのOHJの追加

この章では、OHJと製品アプリケーションの統合方法、Helpオブジェクトの構成および作成方法、ヘルプ・データの追加、タブの追加方法およびトピックの表示方法について説明します。

この章には、次のセクションがあります。

- アプリケーションへのOHJの追加について

- Helpオブジェクトの構成

- ヘルプ・データの追加

- 「お気に入り」タブまたはカスタム・タブの追加

- Helpオブジェクトをいつ作成するか

- ナビゲータ・ウィンドウの表示

- トピックの表示

- Helpオブジェクトの破棄

13.1 アプリケーションへのOHJの追加について

アプリケーションにOHJを追加するための基本的な手順は次のとおりです。

1. Helpオブジェクトを構成します。

2. Helpオブジェクトを次の手順でヘルプ・コンテンツに移入します。

- ヘルプ・データを表すBookオブジェクトを作成します。

- BookオブジェクトをHelpオブジェクトに追加します。

3. OHJナビゲータ・ウィンドウの表示メソッドおよびヘルプ・トピックの表示メソッドを実装します。

4. 製品のライフサイクルの最後にHelpオブジェクトを破棄します。

13.2 Helpオブジェクトの構成

Helpオブジェクトは、Oracle Help for Javaの主なエントリ・ポイントになります。ヘルプ・コンテンツの追加、OHJナビゲータ・ウィンドウの表示、および特定のトピックの表示など行うためのメソッドが含まれています。Helpオブジェクトの構築時にのみ設定可能ないくつかのオプションがあります。

Helpオブジェクト・コンストラクタのboolean combineBooksパラメータは、OHJで複数のBook、すなわちHelpSetを表示する方法を指定します。boolean combineBooksパラメータをtrueに設定すると、タイプとラベルが同じ作成者定義のビューがすべてマージされます。たとえば、同じラベルのキーワードの索引ビューが複数のブックに含まれている場合、1つのキーワード・ナビゲータ・タブに、マージされソートされたキーワード・リストが表示されます。combineBooksパラメータがfalseに設定されると、各ブックのビューが個別に表示され、エンド・ユーザーは表示するブックをOHJナビゲータ・ウィンドウのドロップダウン・リストを使用して選択します。

次の表に、Helpオブジェクト・コンストラクタの各バージョンを示します。oracle.help.HelpのAPIドキュメントの詳細は、第12.3.2項「OHJDKリリースの内容」を参照してください。

表13-1 Help()コンストラクタ

コンストラクタ

説明

Help()

トピックの表示に使用されるHTMLBrowserコンポーネントとしてICEBrowserを含む、Helpオブジェクトのインスタンスを作成します。このコンストラクタでは、ヘルプ・システムに対し、追加されたブックのすべてのビューを1つのタブ・パネルに表示し、作成者定義のタブ・ラベルを無視して標準タブ・ラベルを採用するように指示します。

Help(boolean combineBooks, boolean useLabelInfo)

トピックの表示に使用されるHTMLBrowserコンポーネントとしてICEBrowserを含む、Helpオブジェクトのインスタンスを作成します。

パラメータ:

- combineBooks: trueの場合、ヘルプ・システムに追加されたブックからのすべてのビューが1つのタブ・パネルに表示されます。falseの場合、ブックごとに個別のタブ・パネルが作成され、どのブックを表示するかをエンド・ユーザーが選択できます。

- useLabelInfo: trueの場合、表示とビューのマージに作成者定義のラベル情報が使用されます。falseの場合、デフォルト・ラベルが使用されます。

Help(Class htmlBrowserClass, boolean combineBooks, boolean useLabelInfo)

指定されたHTMLBrowserコンポーネントをトピックの表示に使用する、Helpオブジェクトのインスタンスを作成します。ICEBrowserは、現在OHJで配布されている単なるHTMLBrowserサブクラスです。

パラメータ:

- htmlBrowserClass: トピック表示コンポーネントとして使用するHTMLBrowserサブクラス。

- combineBooks: trueの場合、ヘルプ・システムに追加されたブックからのすべてのビューが1つのタブ・パネルに表示されます。falseの場合、ブックごとに個別のタブ・パネルが作成され、どのブックを表示するかをエンド・ユーザーが選択できます。

- useLabelInfo: trueの場合、表示とビューのマージに作成者定義のラベル情報が使用されます。falseの場合、デフォルト・ラベルが使用されます。

Help(Class htmlBrowserClass, boolean combineBooks, boolean useLabelInfo, boolean standAloneMode)

指定されたHTMLBrowserコンポーネントをトピックの表示に使用する、Helpオブジェクトのインスタンスを作成します。ICEBrowserは、現在OHJで配布されている単なるHTMLBrowserサブクラスです。このコンストラクタには、実行するOHJに対してスタンドアロン・モードを有効にする追加パラメータが含まれます。この場合、Helpオブジェクトは、すべてのヘルプ・ウィンドウを閉じた後、(System.exitによって) JVMを終了します。standAloneModeパラメータは、OHJをJavaアプリケーションから起動している場合はfalseに設定する必要があります(それ以外の場合、ヘルプを閉じると、アプリケーションが終了します!)。

パラメータ:

- htmlBrowserClass: トピック表示コンポーネントとして使用するHTMLBrowserサブクラス。

- combineBooks: trueの場合、ヘルプ・システムに追加されたブックからのすべてのビューが1つのタブ・パネルに表示されます。falseの場合、ブックごとに個別のタブ・パネルが作成され、どのブックを表示するかをエンド・ユーザーが選択できます。

- useLabelInfo: trueの場合、表示とビューのマージに作成者定義のラベル情報が使用されます。falseの場合、標準のデフォルト・ラベルが使用されます。

- standAloneMode: trueの場合、ヘルプ・ウィンドウがすべて閉じられるとヘルプ・システムはJVMを終了します。OHJをJavaアプリケーションから起動する場合は、falseに設定してください。

13.3 ヘルプ・データの追加

Helpオブジェクトを作成した後、1つ以上のBookオブジェクトを追加する必要があります。Bookオブジェクトは、ヘルプ・コンテンツの集まり、すなわちブックをカプセル化します。

ヘルプセット・ブック実装は、Oracle Helpファイル形式で説明するように、優先されるOracle Helpファイル形式を処理します。これらのファイルには、ヘルプ・システムの特徴を定義するヘルプセット・ファイルが含まれています。

ヘルプ・セットの追加方法およびその他のオプション機能について次の各項で説明します。

- 第13.3.1項「HelpSetの構成」

- 第13.3.2項「ヘルプへのブックの追加」

13.3.1 HelpSetの構成

表13-2に、HelpSet()コンストラクタを示します。

表13-2 HelpSet()コンストラクタ

コンストラクタ

説明

HelpSet(URL fileURL)

URLで指定される場所のヘルプセット・ファイルを使用してHelpSetオブジェクトを構成します。このコンストラクタは、ヘルプセット・ファイルの正確な場所がわかっている場合に使用します。

パラメータ:

- fileURL – ヘルプセット・ファイルの正確な場所を指定するURL。

HelpSet(Class pathClass, String pathExtension)

このコンストラクタは、ヘルプセット・ファイルへのパスがアプリケーション実装を基準にした場所としてしかわからない場合に使用します。

パラメータ:

- pathClass: アプリケーション・クラスの1つです。HelpSetオブジェクトは、このクラスの場所を使用してヘルプセット・ファイルの場所を判断します。

- pathExtension: pathClassの場所を基準にしたヘルプセット・ファイルへのパス。このパラメータの値は、pathClassを含むディレクトリへの絶対パスの末尾に付加されます。結果として生成されるパスが、ヘルプセット・ファイルへのパスになります。

詳細は、oracle.help.library.helpset.HelpSetのAPIドキュメントを参照してください。

13.3.2 ヘルプへのブックの追加

HelpSetコンストラクタを使用してBookインスタンスを作成した後、そのBookをHelpインスタンスに追加する必要があります。ヘルプにブックを追加するには、Helpインスタンスで次のメソッドを呼び出します。

表13-3 addBook()コンストラクタ

コンストラクタ

説明

addBook(Book book)

このメソッドでは、Bookインスタンスがヘルプ・システムに追加されます。Bookに含まれる作成者定義ビューがナビゲータ・ウィンドウに表示され、Bookからのトピックを表示できるようになります。

パラメータ:

- book: ヘルプ・システムに追加するBookインスタンス。

13.4 「お気に入り」タブまたはカスタム・タブの追加

helpオブジェクトの構成後、ナビゲータ・ウィンドウを表示する前に、必要に応じて「お気に入り」タブまたはカスタム・タブを追加できます。

- 「お気に入り」タブをナビゲータ・ウィンドウに追加するには、関数enableFavoritesNavigator(URL)を使用します。oracle.help.Help.enableFavoritesNavigator(URL)のAPIドキュメントの詳細は、第12.3.2項「OHJDKリリースの内容」を参照するか、例としてPreviewHelpSet.javaで次のコードを探します。

if (!"".equals(_favoritesPath))
{
try
{
File file = new File(_favoritesPath);
_help.enableFavoritesNavigator(file.toURL());
}
catch (MalformedURLException e)
{
e.printStackTrace();
}
}

- カスタム・タブを追加する場合は、第12.3.2項「OHJDKリリースの内容」のoracle.help.navigator.NavigatorのAPIドキュメントを参照してください。

13.5 Helpオブジェクトをいつ作成するか

単一インスタンスのHelpオブジェクトを作成し、アプリケーションの起動時にヘルプ・データを追加する必要があります。この単一インスタンスのHelpオブジェクトをアプリケーション・セッション全体で使用する必要があります。ユーザーがアプリケーションでヘルプをリクエストするたびに一意のHelpオブジェクトを作成する方法は効率的ではありません。

13.6 ナビゲータ・ウィンドウの表示

HelpインスタンスにOHJナビゲータ・ウィンドウの表示を指示するには、showNavigatorWindow()メソッドを呼び出します。このメソッドのいくつかのバージョンには、指定したナビゲータ・タブ(「目次」、「索引」、「検索」など)が選択された状態でナビゲータ・ウィンドウを表示するための追加パラメータを受け取るものがあります。

表13-4 showNavigatorWindow()コンストラクタ

コンストラクタ

説明

showNavigatorWindow()

最初のブックの最初のタブが選択された状態でナビゲータ・ウィンドウを表示します。

パラメータ:

- activeBook: ナビゲータ・ウィンドウの表示時に最初に表示されるナビゲータ・セットが関連付けられているBookオブジェクト。

showNavigatorWindow(Book activeBook)

指定されたブックに関連付けられているナビゲータ・セットが表示された状態でナビゲータ・ウィンドウを表示します。

パラメータ:

- activeBook: ナビゲータ・ウィンドウの表示時に最初に表示されるナビゲータ・セットが関連付けられているBookオブジェクト。

showNavigatorWindow(Navigator activeNavigator)

指定されたナビゲータ・タブが選択された状態でナビゲータ・ウィンドウを表示します。このメソッドは、指定したブックの特定のナビゲータを表示する場合に使用します。

パラメータ:

- activeNavigator: 最初に選択されたときに表示するナビゲータ。

13.7 トピックの表示

Helpインスタンスに特定のヘルプ・トピックの表示を指示するには、showTopic()メソッドを呼び出し、そのトピックのトピックIDとBookインスタンスを指定します。このメソッドの一部のバージョンでは、トピックの表示方法を指定する追加パラメータを指定します。

表13-5 showTopic()コンストラクタ

コンストラクタ

説明

showTopic(Book book, String topicID)

指定されたブックの指定されたトピックを現在表示されているトピック・ウィンドウに表示します。現在表示されているトピック・ウィンドウがない場合は、新しいトピック・ウィンドウがデフォルトのサイズと位置で作成されます。

パラメータ:

- book: 表示するトピックが含まれるBook。

- topicID: 表示されるトピックの(そのブックのマップ・ファイルで定義されている)トピックID。

showTopic(Book book, String topicID, boolean alwaysCreate)

特定のブックの特定のトピックを表示します。alwaysCreateがtrueの場合は、新しいウィンドウが必ず作成されます。falseの場合は、現在表示されているウィンドウがないときに、新しいウィンドウが作成されます。

パラメータ:

- book: 表示するトピックが含まれるBook。

- topicID: 表示されるトピックのトピックID(ブックのマップ・ファイルで定義されています)。

- alwaysCreate: trueの場合、常に新しいウィンドウが表示されます。falseの場合、ウィンドウがあればそれを再利用します。

showTopic(Book book, String topicID, boolean alwaysCreate, Point location, Dimension size)

特定のブックの特定のトピックを表示します。alwaysCreateがtrueの場合、新しいウィンドウが常に作成されます。また、falseの場合、ウィンドウが現在存在しなければ新しいウィンドウが作成されます。トピック・ウィンドウは、指定の場所やサイズを使用して表示されます。

パラメータ:

- book: 表示するトピックが含まれるBook。

- topicID: 表示されるトピックのトピックID(ブックのマップ・ファイルで定義されています)。

- alwaysCreate: trueの場合、常に新しいウィンドウが表示されます。falseの場合、ウィンドウがあればそれを再利用します。

- location: トピック・ウィンドウの位置。画面座標で指定します。

- size: トピック・ウィンドウのサイズ。ピクセル単位で指定します。

13.7.1 TopicDisplayExceptionsのキャッチ

トピックを表示しようとしたときにエラーが発生すると、showTopic()メソッドにより例外がスローされます。たとえば、マップ・ファイルにないトピックIDを表示しようとすると、TopicDisplayExceptionがスローされます。TopicDisplayExceptionをキャッチすることで、エラーが発生したときの対処が可能になります。次の例では、TopicDisplayExceptionがスローされると、作成者定義のエラー・トピックが表示されます。

次に例を示します。

try
{
myHelp.showTopic(myhelpset, "nonExistingTopic");
}
catch (TopicDisplayException e)
{
//An error has occurred, try to show an error topic
myHelp.showTopic(myhelpset, "onErrorTopic");
}

13.8 Helpオブジェクトの破棄

Helpオブジェクトを破棄すると、OHJリソースが解放されます。ヘルプ・エンジンが不要になったら、Helpオブジェクトを破棄してください。一般に、この処理はユーザーがアプリケーション・セッションを終了したときに行います。破棄することで、Helpオブジェクトが使用していたすべてのファイルが閉じられ、メモリーが解放されます。Helpオブジェクトを破棄するには、dispose()メソッドを呼び出します。

表13-6 dispose()コンストラクタ

コンストラクタ

説明

dispose()

ヘルプ・システムを破棄します。このメソッドは、ヘルプ・システムによって使用されていたすべてのリソースを解放します。アプリケーションでは、ヘルプが不要になったときにこのメソッドを呼び出します。dispose()を呼び出した後にHelpオブジェクトのメソッドを呼び出さないでください。

dispose()メソッドは、OHJクラスが保持していたオブジェクトへのあらゆる参照を削除しますが、作成者がアプリケーション・コードで作成した、その他のアプリケーションからHelpオブジェクトへの参照は削除しません。

したがって、dispose()の呼出し後に、OHJオブジェクト(HelpオブジェクトまたはBookオブジェクト)へのすべての参照をアプリケーション・コードで削除する必要があります。そうすることで、Javaガベージ・コレクション・プロセスがOHJオブジェクトを解放します。

14 アプリケーションでの状況依存ヘルプの有効化

この章では、アプリケーションで状況依存ヘルプを有効にする方法、およびヘルプ・トピックにトピックIDをマップする方法について説明します。

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

- 状況依存ヘルプについて

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

- 状況依存ヘルプをサポートするためのアプリケーションのプログラミング

- CSHManagerを使用した状況依存ヘルプの実装

14.1 状況依存ヘルプについて

状況依存ヘルプ・トピックは、製品のユーザー・インタフェースのコンテキストに関連付けられいてそのコンテキストから起動できるヘルプ・トピックです。たとえば、状況依存ヘルプ・システムには、製品のメニューやダイアログ・ボックスについて説明するトピックを用意します。該当するコントロールのいずれかに関するヘルプをユーザーが要求すると、そのコントロールに関するトピックが表示されます。

Oracle Help for Javaには、ヘルプ・トピックをユーザー・インタフェース・コントロールに関連付けるメカニズム、およびユーザーが[F1]キーを押すか右クリックによるポップアップ・メニューで「ヘルプ」を選択すると起動される状況依存ヘルプのメカニズムが備えられています。また、OHJには、コンポーネントに関連付けられているヘルプ・トピックを明示的に表示するためのAPIも備えられています。

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

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

状況依存ヘルプ・システムには、トピックIDをヘルプ・トピックにマップするマップ・ファイルが1つ以上含まれていることが必要です。マップ・ファイルは、プログラマではなくヘルプ作成者によって作成されるのが理想的です。OHJでは、次の2種類のマップ・ファイルをサポートしています。

OHJシステムの実装にHelpSetが使用されている場合、マップ・ファイルとして、Oracle Helpシステムの推奨形式でもあるXMLファイル形式を使用することが必要です。マップ・ファイルの詳細は、第5.3項「マップ・ファイル」を参照してください。

マップ・ファイルのトピックIDにマップするJava定数のセットをアプリケーション・コードに定義する場合が考えられます。トピックIDを必要とするOHJメソッド(Help.showTopic()など)を使用する場合、マップ・ファイルに指定されている明示的なトピックIDを使用するかわりに、定数変数名を使用できます。このようにしておくと、マップ・ファイルのトピックIDが後で変更されたときにコードを何箇所も変更する必要がありません。ヘルプ作成者がマップ・ファイルの管理を担当している場合に特に便利です。

14.3 状況依存ヘルプをサポートするためのアプリケーションのプログラミング

標準のJavaツールキット(AWTおよびSwing)には、ヘルプ・トピックをコンポーネントに関連付ける組込みメカニズムがありません。一方、OHJには、状況依存ヘルプをJavaアプリケーションに実装するための汎用的な方法が用意されており、OHJ CSHManagerクラスを使用します。このヘルプ・マネージャを使用すると、ヘルプ・トピックをユーザー・インタフェース・コンポーネントに関連付けたり、[F1]キーおよび右クリックによる状況依存ヘルプを有効化できます。

14.4 CSHManagerを使用した状況依存ヘルプの実装

OHJのCSHManagerクラスは、ヘルプ・トピックをユーザー・インタフェース・コントロールに関連付けたり、エンド・ユーザーが[F1]キーを押したり右クリックによるポップアップ・メニューから「ヘルプ」を選択したときに状況依存ヘルプを起動するための、汎用的な方法です。また、OHJには、コンポーネントに関連付けられているヘルプ・トピックを明示的に表示するためのAPIも備えられています。

CSHManagerの使用の概要について次の各項で説明します。

- 第14.4.1項「CSHManagerコンストラクタ」

- 第14.4.2項「デフォルト・ブックの設定」

- 第14.4.3項「トピックIDのユーザー・インタフェース・コンポーネントとの関連付け」

- 第14.4.4項「コンポーネントのヘルプの明示的な表示」

14.4.1 CSHManagerコンストラクタ

ユーザー・インタフェース・コンポーネントを作成する前に、CSHManagerクラスのインスタンスを作成することが必要です。表14-1に、CSHManagerコンストラクタを示します。

表14-1 CSHManager()コンストラクタ

コンストラクタ

説明

CSHManager(Help help)

CSHManagerクラスの新しいインスタンスを作成します。以降のこのマネージャ・オブジェクトに対するすべての呼出しで、ここで指定されたHelpオブジェクトが使用されます。

パラメータ:

- help: ヘルプの表示に使用されるHelpオブジェクト。

14.4.2 デフォルト・ブックの設定

ヘルプ・コンテンツのBookが1つしかない場合は、setDefaultBook()メソッドを使用してそれを状況依存ヘルプのデフォルトのブックとして定義します。これにより、addComponent()メソッドを呼び出すときにbookパラメータが不要になります。

表14-2 setDefaultBook()コンストラクタ

コンストラクタ

説明

setDefaultBook(Book book)

指定したBookをデフォルトのBookとして設定します。Book指定なしで登録されたコンポーネントの場合、これがデフォルトのBookとして使用されます。

パラメータ:

- book: デフォルトとして設定するBook。

複数のBookがある場合、特定のBookが割り当てられなかったコンポーネントについては、デフォルトのBookのみ使用されます。複数のBookによるヘルプ・システムでは、一般的に、コンポーネントに特定のBookを割り当てる必要があります。

14.4.3 トピックIDのユーザー・インタフェース・コンポーネントとの関連付け

マップ・ファイルに定義されているトピックIDをJavaユーザー・インタフェース・コンポーネントに関連付けるには、addComponent()メソッドを使用します。状況依存ヘルプが必要なコンポーネントごとに、このメソッドのいずれかのバージョンを呼び出します。

表14-3 addComponent()コンストラクタ

コンストラクタ

説明

addComponent(Component component, String topicId)

コンポーネントをヘルプ・マネージャに登録します。topicIdの検索にはデフォルトのBookが使用されます。このメソッドを呼び出したときにデフォルトのBookが登録されていない場合、コンポーネントはこのヘルプ・マネージャには登録されず、このコンポーネントに対して後でshowHelpForComponent()がコールされても、ヘルプは表示されません。このメソッドを使用して登録されたコンポーネントの場合、CSHManagerでは、[F1]キーを押したり右クリックしてもヘルプは表示されません。

パラメータ:

- component: 追加するコンポーネント。

- topicId: このコンポーネントに関連付けるトピックID。

addComponent(Component component, Book book, String topicId)

ヘルプ・マネージャにコンポーネントを登録します。topicIdの検索には指定したブックが使用されます。

このメソッドを使用して登録されたコンポーネントに対し、CSHManagerは[F1]キー押下イベントまたは右クリック・イベントに対してヘルプを表示しません。

パラメータ:

- component: 追加するコンポーネント。

- book: ヘルプ・トピックを含むブック。

- topicId: このコンポーネントに関連付けるトピックID。

addComponent(Component component, String topicId, boolean needF1Help, boolean needPopupHelp)

topicIdの検索にデフォルトのBookが使用されます。このメソッドを呼び出したときにデフォルトのBookが登録されていない場合、コンポーネントはこのヘルプ・マネージャでは登録されず、このコンポーネントに対して後でshowHelpForComponent()が呼び出されても、ヘルプは表示されません。

パラメータ:

- component: 追加するコンポーネント。

- topicId: このコンポーネントに関連付けるトピックID。

- needF1Help: trueの場合、[F1]キー押下イベントに対してこのコンポーネントのヘルプが表示されます。

- needPopupHelp: trueの場合、マウスの右クリックに対して「ヘルプ」を含むポップアップ・メニューを表示し、「ヘルプ」メニュー項目が選択された場合に状況依存ヘルプを起動します。

addComponent(Component component, Book book, String topicId, boolean needF1Help, boolean needPopupHelp)

ヘルプ・マネージャにコンポーネントを登録します。topicIdの検索には指定したブックが使用されます。

パラメータ:

- component: 追加するコンポーネント。

- topicId: このコンポーネントに関連付けるトピックID。

- needF1Help: trueの場合、[F1]キー押下イベントに対してこのコンポーネントのヘルプが表示されます。

- needPopupHelp: trueの場合、マウスの右クリックに対して「ヘルプ」を含むポップアップ・メニューを表示し、「ヘルプ」メニュー項目が選択された場合に状況依存ヘルプを起動します。

- needF1Help: trueの場合、[F1]キー押下イベントに対してこのコンポーネントのヘルプが表示されます。

- needPopupHelp: trueの場合、マウスの右クリックに対して「ヘルプ」を含むポップアップ・メニューを表示し、「ヘルプ」メニュー項目が選択された場合に状況依存ヘルプを起動します。

14.4.4 コンポーネントのヘルプの明示的な表示

コンポーネントに関連付けられているヘルプ・トピックを明示的に表示する場合は、CSHManagerに対してshowHelpForComponent()メソッドを呼び出します。たとえば、ユーザーがダイアログ・ボックスで「ヘルプ」ボタンをクリックしたときに状況依存ヘルプを起動するには、ボタン・イベント・ハンドラでこのメソッドを呼び出します。

表14-4 showHelpForComponent()メソッド

コンストラクタ

説明

showHelpForComponent(Component component)

指定したコンポーネントのヘルプを表示します。指定したコンポーネントの登録にaddComponent()が使用されていない場合、ヘルプは表示されません。

15 OHJヘルプ・システムのデプロイ

この章では、OHJヘルプ・システムをアプリケーションにデプロイする方法について説明します。また、OHJファイルに備えておく必要のあるファイルのリストと、JARファイルを作成する方法についても説明します。

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

- サポートされているJava仮想マシン

- 同梱する必要があるOHJ JARファイル

- JARに含まれる圧縮ヘルプ・コンテンツのデプロイ

15.1 サポートされているJava仮想マシン

OHJはJavaアプリケーション(またはアプレット)であるため、Java仮想マシン(JVM)で実行する必要があります。つまり、ユーザーの環境に適切なJVMがインストールされている必要があります。OHJがJavaアプリケーションのヘルプとして使用されている場合は、そのアプリケーションも仮想マシンで実行する必要があるため、通常、JVMはアプリケーションとともに配布されているはずです。

15.2 同梱する必要があるOHJ JARファイル

次のJAR (Java ARchive)ファイルを製品インストールの一部として再配布する必要があります。これらのファイルには、OHJエンジンの実装とその依存性が含まれます。これらのファイルの詳細は、第12.3.2項「OHJDKリリースの内容」を参照してください。

- helpversion_num.jar

- oracle_ice.jar

15.3 JARに含まれる圧縮ヘルプ・コンテンツのデプロイ

Javaベースのアプリケーションは、多くの場合、JAR形式で配布されます。HTMLコンテンツはJAR圧縮することでサイズが大幅に小さくなるため、ヘルプ・コンテンツをJARファイルとして含めることを検討してください。

15.3.1 JARファイルの作成

JARファイルを作成するには、Java Development Kitに付属のJARツールを使用します。この作業を、サード・パーティのOHJ対応ヘルプ・オーサリング・システムでもできることがあります。

ファイルの構成とそれらのJARアーカイブ内でのパスの割当てには特別な注意が必要です。ヘルプJARファイル内のディレクトリ構造は、製品実装JARファイルのディレクトリ構造と一致している必要があります。ヘルプ・コンテンツは、参照ポイントとして使用する実装クラスの位置の後ろであることが必要です。

次に例を示します。

製品実装JARに次のディレクトリ構造のクラスが含まれているとします。

/com/yourCompany/yourProduct/SomeProduct.class
/com/yourCompany/yourProduct/SomeClass.class

その場合、ヘルプJARには一致するパスが含まれており、ヘルプ・コンテンツが共有ディレクトリ構造で製品実装クラスの下になることが必要です。

/com/yourCompany/yourProduct/help/ProductHelp.hs
/com/yourCompany/yourProduct/help/TableOfContents.xml
/com/yourCompany/yourProduct/help/SomeHelpTopic.html

15.3.2 使用するBookコンストラクタ

JARファイルからロードされるヘルプ・コンテンツを使用するBookオブジェクトを作成するには、ヘルプJARファイルと実装JARファイルがシステムのCLASSPATH上にあることが必要です。JARファイルを前述のように編成した場合は、ヘルプ・コンテンツの場所はCLASSPATH上の実装クラスの場所を基準にしてわかります。

そのため、Javaクラスとそのクラスの相対パスを受け付けるバージョンのHelpSetコンストラクタを使用します。

たとえば、JARファイルが2つある場合は、helpsetオブジェクトの構成に次のコードを使用します。

import com.yourCompany.yourProduct.SomeProduct;
helpset myhelpset = new helpset(SomeProduct.class, "help/ProductHelp.hs");

第V部

Oracle Help for the Web

この部では、Oracle Help for Webの使用について説明します。次の章で構成されます。

- 第16章「OHWデモ・ファイルのデプロイ」
この章では、OHWデモ・ファイルのデプロイ方法について説明します。初めてOHWを使用する場合は、独自のヘルプ・システムのデプロイを開始する前に、デモ・ファイルをデプロイするようお薦めします。

- 第17章「OHWのデプロイメントの理解」
この章では、OHWのデプロイメント・プロセスについて説明します。

- 第18章「Webアプリケーションでの状況依存ヘルプの実装」
この章では、Webアプリケーションで状況依存OHWヘルプを実装する方法について説明します。

- 第19章「ADFリッチ・クライアント・ヘルプ・プロバイダ」
この章では、ADFリッチ・クライアント・ヘルプ・プロバイダと、OHWをヘルプ・プロバイダとして使用する方法について説明します。

16 OHWのデモ・ファイルのデプロイ

この章では、OHWのデモ・ファイルをスタンドアロンのOracle WebLogic ServerとJDeveloperが統合されたOracle WebLogic Serverにデプロイする方法、およびそのデモ・ファイルの実行方法について説明します。

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

- OHWのデモ・ファイルのデプロイについて

- OHWのデモ・ファイルの理解

- スタンドアロンOracle WebLogic ServerへのOHWデモEARファイルのデプロイ

- JDeveloperが統合されたOracle WebLogic ServerへのOHWデモEARファイルのデプロイ

- OHWのデモEARファイルの実行

16.1 OHWのデモ・ファイルのデプロイについて

OHWデモEARファイルには、デモの表示とリリースの試用に必要なクラス・ライブラリがすべて含まれています。また、サンプル・ヘルプセット、OHWサーブレット・ファイルおよびXML構成ファイルが含まれています。OHWインタフェースを体験するデモ・ファイルのデプロイや、既存のヘルプセットの交換および各自のヘルプセットの追加などを行えます。

16.2 OHWのデモ・ファイルの理解

OHWのデモ・ファイルには、ohw-rcf-demo-thin.ear、ohw-rcf-demo-thin-shared.earおよびohw-rcf-demo-thick.earの3つのバリアントが用意されています。

ohw-rcf-demo-thick.earには、デプロイ用に事前構成されたADF、JSFおよびJSTLライブラリが含まれます。サポートされているアプリケーション・サーバーまたはJDeveloperを使用しない場合、またはサポートされているアプリケーション・サーバーを使用するがライブラリがインストールされていない場合、このファイルを使用することをお薦めします。サポートされているアプリケーション・サーバーの詳細は、OTNの「動作保証情報」を参照してください。

ohw-rcf-demo-thin.earには、ADF、JSFおよびJSTLライブラリは含まれていないため、デプロイメントの前にライブラリをアプリケーション・サーバーにインストールしておく必要があります。このデモ・ファイルにはJDeveloperが必要です。デモ・ファイルのデプロイ方法の詳細は、第16.3項「スタンドアロンOracle WebLogic ServerへのOHWデモEARファイルのデプロイ」を参照してください。

ohw-rcf-demo-thin-shared.earには、ADF、JSFおよびJSTLライブラリは含まれていません。また、デモ・ファイルには、OHW関連jar(ohw-rcf.jar、ohw-share.jarおよびhelp-share.jarなど)は含まれていませんが、OHW-RCライブラリのOHW jarが使用されます。そのため、ohw-rcf-demo-thin-shared.earデモ・ファイルを使用している場合、そのファイルをJDeveloperからデプロイする必要があります。ohw-rcf-demo-thin-shared.earデモ・ファイルをデプロイするプロセスは、JDeveloperでohw-rcf-demo-thin.earファイルをデプロイする場合と同じです。デモ・ファイルをデプロイする方法の詳細は、第16.4項「JDeveloperが統合されたOracle WebLogic ServerへのOHWデモEARファイルのデプロイ」を参照してください。WebLogic Serverにデモ・ファイルをデプロイする場合、OHW-RCライブラリ・ファイルをOTNからダウンロードする必要があります。ohw-rcf-demo-thin-shared.earデモ・ファイルをデプロイするプロセスは、スタンドアロンのWebLogic Serverにohw-rcf-demo-thin.earファイルをデプロイする場合と同じです。デモ・ファイルのデプロイ方法の詳細は、第16.3項「スタンドアロンOracle WebLogic ServerへのOHWデモEARファイルのデプロイ」を参照してください。

注意:
デモEARファイルの実行時にohw-rcf-demo-thin.earとohw-rcf-demo-thick.earが競合する場合、どちらもOracle WebLogic Serverにデプロイしないでください。

OHWの両方のデモEARファイル(ohw-rcf-demo-thin.earおよびohw-rcf-demo-thick.ear)には、2つのOHWのサンプル・ヘルプセットが、それぞれのヘルプ・トピック、ヘルプセット・ファイルおよび制御ファイルとともに含まれます。また、OHWの構成に必要なohwconfig.xmlも含まれます。

ディレクトリへの解凍時には、OHWのデモ・ファイルは、ファイルと同じ名前のディレクトリ(ohw-rcf-demo-thinおよびohw-rcf-demo-thick)に、それぞれのファイルを解凍します。EARファイルにはWARファイルと、application.xmlファイルが含まれるMETA-INFディレクトリが抽出されます。WARファイルには、すべてのヘルプセットのディレクトリが、それぞれのヘルプ・トピック、ヘルプセット・ファイルおよび制御ファイルとともに含まれます。

表16-1に、OHWのデモEARファイルに含まれるファイルとディレクトリを示します。

表16-1 OHWのデモ・ファイルおよびディレクトリ

ファイル

説明

application.xml

Java EEアプリケーション・ファイル。

このファイルは、META-INFディレクトリにあります。

helpsetsディレクトリ

2つのヘルプセットを含むWebモジュール、ohguideおよびサンプルのshakespeareが、それぞれ別のディレクトリに含まれます。

ヘルプセット・ディレクトリは、それぞれのWARファイル(ohw-rcf-demo-thick.warまたはohw-rcf-demo-thin.war)に存在します。

trinidad-config.xml

faces-config.xml

web.xml

weblogic.xml

OHWのシン・クライアントおよびシック・クライアントに影響する構成およびデプロイの情報が含まれます。

これらのファイルは、WARファイルのWEB-INFディレクトリにあります。

help-share.jar

ohw-rcf.jar

ohw-share.jar

次のライブラリ・ファイルは、シック・クライアントでのみ提供されています。

- adf-richclient-api-11.jar

- adf-richclient-impl-11.jar

- trinidad-api.jar

- trinidad-impl.jar

デプロイに必要なOHWのライブラリ・ファイルです。

これらのファイルは、WARファイルのWEB-INF\libディレクトリにあります。

ohwconfig.xml

OHW構成ファイル。

このファイルは、helpsetsディレクトリにあります。

16.3 スタンドアロンOracle WebLogic ServerへのOHWデモEARファイルのデプロイ

デモ・ファイルのデプロイメントを開始する前に、ADF、JSFおよびJSTLライブラリがOracle WebLogic Serverにインストールされていることを確認してください。詳細は、第17.3項「OHWライブラリ・ファイルの検証」を参照してください。

ライブラリを確認した後の、デモEARファイルのデプロイは非常に簡単なプロセスです。

1. OHWのデモEARファイルをOTNからダウンロードします。デモ・ファイルの名前は、ohw-rcf-demo-thick.earです。このファイルには、OHWライブラリ・ファイルおよびサンプル・ヘルプセットが含まれます。

2. Oracle WebLogic管理コンソールを起動し、「デプロイメント」ページに移動します。

3. 「デプロイメント」ページで、「インストール」をクリックしてデプロイ・ウィザードを起動します。

4. 「パス」フィールドにohw-rcf-demo-thick.earファイルの保存先を入力するか、「現在の場所」でEARファイルを参照して選択します。
「次へ」をクリックして、続行します。

5. ターゲット指定スタイルの選択ページで、このデプロイメントをアプリケーションとしてインストールするを選択し、「次へ」をクリックします。

6. 「オプション設定」ページで設定を確認します。設定をデフォルトのままにしておくことをお薦めします。「次」をクリックして続行するか、「終了」をクリックしてデプロイメントを完了します。

7. 追加構成ページで、はい、デプロイメントの構成画面を表示しますを選択し、「終了」をクリックしてデプロイを完了します。
デプロイが成功すると、デプロイ・ウィザードの表示は、ohw-rcf-demo-thick.earの設定ページに戻ります。ファイルのデプロイ中にエラーが発生した場合は、「デプロイメント」ホームページが表示され、エラーが赤いテキストでリストされます。

16.4 JDeveloperが統合されたOracle WebLogic ServerへのOHWデモEARファイルのデプロイ

Oracle JDeveloperにデモ・ファイルをデプロイするには、次の手順を実行します。

1. OHWのデモEARファイルをOTNからダウンロードします。デモ・ファイルの名前は、ohw-rcf-demo-thin.earです。このファイルには、OHWおよびサンプル・ヘルプセットが含まれます。

2. JDeveloperを起動します。

3. ohw-rcf-demo-thin.earから、新しいアプリケーションを作成します。「file」メニューから、「新」を選択します。「新規ギャラリ」ダイアログ・ボックスで、「General」カテゴリの下の「アプリケーション」を選択し、「項目」リストから「EARファイルからのアプリケーション」を選択します。

4. EARファイルからのアプリケーション作成ウィザードのJNDI位置ページで、ohw-rcf-demo-thin.earファイルを参照して選択します。また、アプリケーション名およびアプリケーションの場所を変更することもできます。「次へ」をクリックして、続行します。

5. ウィザードのEARモジュール・ページに、プロジェクト名およびモジュール名が表示されます。「次」をクリックして続行するか、または「終了」をクリックしてEARファイルからアプリケーションを作成します。

6. ウィザードの終了ページに、アプリケーションの設定の概要が表示されます。「終了」をクリックしてEARファイルからアプリケーションを作成します。JDeveloperによって、EARファイルからすべてのファイルが抽出され、編集およびデプロイ可能なアプリケーションが作成されます。

7. 「アプリケーション」ウィンドウで、プロジェクトを開き、目的のファイルを編集します。

8. アプリケーションをデプロイするには、統合されたOracle WebLogic Serverインスタンスを起動します。「実行」メニューから、「サーバー・インスタンスの起動」を選択して統合されたOracle WebLogic Serverを起動します。

9. 「アプリケーション」ウィンドウで、ohw-rcf-demo-thinプロジェクトを選択します。「ビルド」メニューから、「デプロイ」を選択します。
デモ・アプリケーションを最初にデプロイするときは、サブメニューからohw-rcf-demo-thinを選択し、次の手順を実行します。

1. ohw-rcf-demo-thinのデプロイダイアログ・ボックスの「デプロイメント・アクション」ページで、デプロイメント・アクションとして「アプリケーション・サーバーへのデプロイ」を選択し、「次へ」をクリックします。

2. サーバーの選択ページで、アプリケーション・サーバーとしてIntegratedWebLogicServerを選択し、「次へ」をクリックします。

3. 「WebLogicオプション」ページで設定を確認します。設定をデフォルトのままにしておくことをお薦めします。「次」をクリックして続行するか、「終了」をクリックしてデプロイメントを完了します。

4. 「サマリー」ページで設定を確認し、「終了」をクリックします。

デモ・アプリケーションを以前にデプロイしたことがあり、同じ設定を継続して使用する場合は、サブメニューからohw-rcf-demo-thinからIntegratedWebLogicServerへを選択できます。

JDeveloperによってデプロイメント・プロセスが開始され、デプロイのステータスが「ログ」ウィンドウに反映されます。アプリケーションが正常にデプロイされると、「ログ」ウィンドウに「---- デプロイが終了 ----」メッセージが表示されます。

16.5 OHWのデモEARファイルの実行

デモ・ファイルのデプロイに成功すると、ブラウザが開いて次のURLが表示されます。

http://<yourHost>:<yourPort>/<jdevProjectName>/ohguide/

Oracle WebLogic管理コンソールを使用してOHWのデモEARファイルをインストールした場合、次のURLを使用します。

http://localhost:7101/ohw-rcf-demo/ohguide

Oracle JDeveloperを使用してOHWのデモEARファイルをインストールした場合、次のURLを使用します。

http://localhost:7101/ohw-rcf-demo-thin/ohguide

OHWのユーザー・インタフェースの詳細は、第3章「Oracle Help for the Webのユーザー・インタフェース」を参照してください。

17 OHWのデプロイメントの理解

この章では、OHWのデプロイメント・プロセスと構成ファイル、OHWのアーティファクトのインストール方法、OHWでのカスタム・ヘルプセットの表示の構成方法、アクセスURLの変更方法、スタンドアロンWebアプリケーションおよび別のWebアプリケーションの一部としてのOHWのデプロイ方法について説明します。

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

- OHWのデプロイメントについて

- 要件および依存性の検証

- OHWライブラリ・ファイルの検証

- OHWのアーティファクトのインストール

- OHW構成ファイルの理解

- OHWでのカスタム・ヘルプセットの表示の構成

- OHWのアクセスURLの変更

- スタンドアロンWebアプリケーションとしてのOHWのデプロイ

- Webアプリケーションの一部としてのOHWのデプロイ

- 1つのWebアプリケーションへの複数ヘルプ・インスタンスのデプロイ

17.1 OHWのデプロイメントについて

ヘルプ作成者によるヘルプ・コンテンツの作成が終了した後、OHW管理者は、OHWを使用してヘルプ・コンテンツをデプロイするようWeb構成を変更する必要があります。

OHWは、様々な方法でデプロイできます。ただし、すべてのデプロイ・モードには共通する特定のタスクがあります。この章では、後続の手順の前提条件となる共通のタスクについて説明します。

OHWに慣れていない場合は、デモ・ファイルのデプロイから開始できます。詳細は、第16章「OHWのデモ・ファイルのデプロイ」を参照してください。デモEARファイルには、サンプル・ヘルプセットを即時にデプロイするためのファイルがすべて含まれます。

OHWの新しいヘルプセットを作成する場合、次の各項で、OHWのデプロイメント・プロセスに役立つ情報と、OHWヘルプ・システムを作成してデプロイする手順を参照してください。

構成ファイルの作成とアプリケーション・サーバーの構成が行われていない場合、OHW管理者は、後続の項で説明するタスクを実行してOHWヘルプ・システムをデプロイする必要があります。

17.2 要件および依存性の検証

OHWの次の要件について検証する必要があります。

表17-1 OHWデプロイの最小要件

要件

説明

アプリケーション・サーバー

OHWには、Java Servlet、JSPおよびJSFをサポートするJava EE 1.5互換のアプリケーション・サーバーが必要です。Oracle WebLogic Server(スタンドアロンとしてまたはJDeveloperと統合して提供されている)では、構成作業を最小限に抑えることができるため、その使用をお薦めします。サポートされているアプリケーション・サーバーの詳細は、OTNの「動作保証情報」のアプリケーション・サーバーに関する項を参照してください。

クライアント

クライアントはHTMLのみを受信するため、必要となるのは、OHWヘルプ・コンテンツを表示して閲覧するためのWebブラウザのみです。WebブラウザのJavaScriptサポートは有効にする必要があります。

OHWは、Microsoft Internet Explorer 7、Microsoft Internet Explorer 8、Mozilla FireFox 2、Mozilla FireFox 3、Apple SafariおよびGoogle Chromeでサポートされます。サポートされているブラウザの詳細は、OTNの「リリース・ノート - JDeveloper 11g」のADF Facesおよびデータの視覚化に関する項を参照してください。

Rich ADF Faces

OHWでは、Rich ADF FacesライブラリおよびRich ADF Facesに依存する機能が使用可能である必要があります。また、アプリケーション・サーバーは、正しいJARファイルをインストールするか、またはOracle JDeveloperのADFランタイム・インストーラを実行し、ADFベースのアプリケーション用に構成する必要があります。詳細は、Oracle WebLogic Application Consoleのオンライン・ヘルプを参照してください。

17.3 OHWライブラリ・ファイルの検証

OHWはRich ADF Facesのテクノロジに依存しているため、Rich ADF FacesをサポートするようOHWヘルプ・ファイルのデプロイ先であるアプリケーション・サーバーを構成する必要があります。

Oracle WebLogic Serverを使用している場合は、Oracle WebLogic Application Consoleを調べて、次のライブラリがデプロイされていることを確認します。

- ADF (adf.oracle.domain(1.0,11.1.1.2.0))

- Java Server Faces(jsf(1.2,1.2.9.0))

- JavaServer Pages標準タグ・ライブラリ(jstl(1.2,1.2.0.1))

これらのライブラリは、Oracle WebLogic Application Consoleのデプロイ・ページに表示されます。ライブラリがインストールされていない場合は、Oracle WebLogic Configurationウィザードを使用して、Oracle JRFライブラリを含むようにWebLogicドメインを拡張します。Oracle JRFライブラリを含めた後にOracle WebLogic Serverを再起動すると、Oracle WebLogic Application Consoleのデプロイ・ページにライブラリが表示されます。ドメイン拡張の詳細は、「Oracle ADFアプリケーションの管理」を参照してください。

Oracle WebLogic Serverを使用しない場合は、ohw-rcf-demo-thick.earのすべてのjarファイルが、WARデプロイメント・ファイルの\WEB-INF\libディレクトリにコピーされていることを確認してください。ライブラリ・ファイルはOTNからダウンロードするか、デモ・ファイルからコピーできます。ライブラリは、ohw-rcf-demo-thick.earファイルのohw-rcf-demo-thick\ohw-rcf-demo-thick\WEB-INF\libディレクトリにあります。

17.4 OHWのアーティファクトのインストール

OHWが機能するためには、いくつかのファイルがサーバーにインストールされている必要があります。詳細は、OHWの様々なデプロイに関するトピックを参照してください。

OHWの配布コンポーネントは、ohw-rcf.jar、ohw-share.jar、help-share.jarなどのJARファイルとohw-rcf-webapp.zipで構成されています。ohw-rcf-webapp.zipにはhelppagesディレクトリがあり、このディレクトリには、OHWの正常な実行に必要なjspx (XML形式のJSFページ)などのインストール可能ファイルが含まれます。

アーティファクトは、OTNからダウンロード可能です。

17.5 OHW構成ファイルの理解

OHWヘルプセットのデプロイを開始する前に、OHWを正しく構成するために作成または変更の必要なファイルがあります。次に、XML構成ファイルの理解に役立つ情報を示します。

- application.xml: 指定のJava EEアプリケーションで実行するすべてのWebモジュールのマニフェスト。デプロイされる各製品のそれぞれのWebモジュールを指し示します。
application.xmlの名前および場所は、Java EE標準によって固定されています。このファイルは、<OHW_HOME>\META-INF\ディレクトリにあります。

- web.xml: OHW構成ファイルの場所など、OHWコンポーネントの初期化パラメータを設定します。各Webモジュールに1つのweb.xmlインスタンスがあります。このファイルは、<OHW_HOME>\<OHW_deployment_name>\WEB-INF\ディレクトリにあります。
OHWのすべての前提条件が正しくロードされて初期化されていることを確認するために設定の必要な、次の最小限のパラメータのセットがあります。

- JSFのサーブレットおよびサーブレット・マッピング

- Trinidadリソース・サーブレット、サーブレット・マッピング、フィルタおよびフィルタ・マッピング

- OHWのフィルタおよびフィルタ・マッピング

- ヘルプ・インスタンスのサーブレットおよびサーブレット・マッピング

次に、サンプルweb.xmlファイルの例を示します。

<context-param>
<param-name>org.apache.myfaces.trinidad.CHANGE_PERSISTENCE</param-name>
<param-value>oracle.adf.view.rich.change.FilteredPersistenceChangeManager</param-value>
</context-param>
<filter>
<filter-name>trinidad</filter-name>
<filter-class>org.apache.myfaces.trinidad.webapp.TrinidadFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>trinidad</filter-name>
<servlet-name>Faces Servlet</servlet-name>
</filter-mapping>
<servlet>
<servlet-name>Faces Servlet</servlet-name>
<servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>Faces Servlet</servlet-name>
<url-pattern>/faces/*</url-pattern>
</servlet-mapping>
<servlet>
<servlet-name>resources</servlet-name>
<servlet-class>org.apache.myfaces.trinidad.webapp.ResourceServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>resources</servlet-name>
<url-pattern>/adf/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>resources</servlet-name>
<url-pattern>/afr/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>resources</servlet-name>
<url-pattern>/ohr/*</url-pattern>
</servlet-mapping>

<!-- configuration for product1 help front servlet -->
<servlet>
<servlet-name>product1</servlet-name>
<servlet-class>oracle.help.web.rich.OHWServlet</servlet-class>
<init-param>
<param-name>ohwConfigFileURL</param-name>
<param-value>/helpsets/product1/ohwconfig.xml</param-value>
</init-param>
<load-on-startup>2</load-on-startup>
</servlet>

<!-- configuration for product2 help front servlet -->
<servlet>
<servlet-name>product2</servlet-name>
<servlet-class>oracle.help.web.rich.OHWServlet</servlet-class>
<init-param>
<param-name>ohwConfigFileURL</param-name>
<param-value>/helpsets/product2/ohwconfig.xml</param-value>
</init-param>
<load-on-startup>3</load-on-startup>
</servlet>

<!-- servlet mappings for the OHW-RC front servlets -->
<servlet-mapping>
<servlet-name>product1</servlet-name>
<url-pattern>/product1/*</url-pattern>
</servlet-mapping>

<servlet-mapping>
<servlet-name>product2</servlet-name>
<url-pattern>/product2/*</url-pattern>
</servlet-mapping>

<!-- OHW-RC servlet filter definition and mappings -->
<filter>
<filter-name>OHWRCFRequestFilter</filter-name>
<filter-class>oracle.help.web.rich.OHWFilter</filter-class>
</filter>

<filter-mapping>
<filter-name>OHWRCFRequestFilter</filter-name>
<servlet-name>Faces Servlet</servlet-name>
</filter-mapping>

- ohwconfig.xml(デフォルトのファイル名): 表示するヘルプセットと、それらの表示方法を指定します。ロケール、ブランド情報およびその他各種設定も指定できます。この構成ファイルの詳細は、第8章「Oracle Help for the Web構成ファイル」を参照してください。このファイルの名前と場所は、OHWフロント・サーブレット初期化パラメータとして設定されます。このパラメータは、サーブレット・コンテナごとに個別に処理されます。ohwConfigFileURL初期化パラメータは、{%some_parameter}トークンを含むパスを取ります。トークンの値は、JavaのSystem.getPropertyコールで解決されます。最新の情報一覧については、常にサーブレット・コンテナのドキュメントを確認してください。
このファイルは、<OHW-RC_HOME>\<OHW-RC_deployment_name>\helpsetsディレクトリにあります。propシステム・プロパティを使用して、ohwConfigURLを指定することもできます。たとえば、web.xmlでは、ohwConfigURLは次のように構成されます。

<param-name>ohwConfigFileURL</param-name>
<param-value>file:///{%prop}/help/ohwconfig.xml</param-value>

adf-settings.xmlでは、ohwConfigURLは次のように構成されます。

<property>
<property-name>ohwConfigFileURL</property-name>
<value>file:///{%prop}/help/ohwconfig.xml</value>
</property>

- trinidad-config.xml: TrinidadおよびADFリッチ・コンポーネントの構成を指定します。OHWで使用されるスキニング・オプションを指定します。このファイルは、<OHW_HOME>\<OHW_deployment_name>\WEB-INF\ディレクトリにあります。

- faces-config.xml: これはJSF構成ファイルです。このファイルは、<OHW_HOME>\<OHW_deployment_name>\WEB-INF\ディレクトリにあります。
ADF Facesレンダー・キット情報は、このファイルに追加する必要があります。

<application>
<default-render-kit-id>oracle.adf.rich</default-render-kit-id>
<locale-config>
<default-locale>en</default-locale>
</locale-config>
</application>

17.6 OHWでのカスタム・ヘルプセットの表示の構成

この項では、OHWヘルプ・システムで必要とされるディレクトリ構造の作成、カスタム・ヘルプセット・ファイルの正しい場所への追加、構成ファイルの作成と変更、およびアプリケーション・サーバーへのヘルプ・システムのデプロイに役立つ情報が提供されます。

この項の説明では、OHWのデモEARファイルがインストール済で、ユーザーがデモEARファイルのディレクトリ構造に精通していることを想定しています。まだデモ・ファイルがインストールされていない場合は、第16章「OHWのデモ・ファイルのデプロイ」の手順に従ってインストールしてください。

OHWヘルプ・システムを設定する手順は、次のとおりです。

1. 次のようにディレクトリ構造を設定します。

<OHW-RC_HOME>
|
— <OHW-RC_deployment_name>
|
— helppages
— helpsets
|
— <custom_helpset_directory>
— META-INF
— WEB-INF
|
— lib
— META-INF

次に例を示します。

my_module
|
— my_module_help
|
— helppages
— helpsets
|
— my_ModuleHelpset
— META-INF
— WEB-INF
|
— lib
— META-INF

2. 独自のヘルプセット・ディレクトリを作成します。ヘルプセット・ファイル、トピック・ファイルおよび他の制御ファイル(索引、目次など)を含め、独自のヘルプ・ファイルをすべて<OHW_HOME>\<OHW_deployment_name>\helpsets\<custom_helpset_directory>ディレクトリの下に配置します。また、ヘルプセットにJARファイルを使用する場合は、JARファイルもここに配置します。JARファイルを作成したヘルプセットとJARファイルを作成していないヘルプセットを1つのデプロイで一緒に使用できます。

3. 構成ファイルを更新および構成します。デモEARのohwconfig.xmlをohw-rc-thick-demo\ohw-rc-thick-demo\helpsetsディレクトリからコピーして、<OHW_HOME>\<OHW_deployment_name>\helpsetsディレクトリに保存します。次の手順で、必要に応じてファイルを編集します。

1. 自分のヘルプセットにダイレクトするように<books></books>セクションを変更します。次に例を示します。

<books>
<helpSet id="myModule" location="my_ModuleHelpset/my_ModuleHelpset.hs" />
</books>

2. <books></books>セクションから、希望しないヘルプセットを削除します。削除されたヘルプセットは、OHWユーザー・インタフェースのヘルプセット・スイッチャのドロップダウン・リストに表示されなくなります。<books></books>セクション内に<helpSet>要素が1つしかない場合、ヘルプセット・スイッチャは使用できません。

3. <brandings></brandings>セクションを更新して、独自のブランドを表示します。次に例を示します。

<brandings>
<branding text="My Module" />
</brandings>

ohwconfig.xmlファイルで構成できる動作の詳細は、第8章「Oracle Help for the Web構成ファイル」を参照してください。

4. ohw-rc-thick-demo\ohw-rc-thick-demo\helppagesディレクトリを<OHW_HOME>\<OHW_deployment_name>ディレクトリにコピーします。

5. 次のライブラリ・ファイルを、JDeveloperから<OHW_HOME>\<OHW_deployment_name>\WEB-INF\libディレクトリにコピーします。

ファイル名

場所

JSFライブラリ・ファイル(jsf-1.2.war)

<JDEV_HOME>\wlserver_10.3\common\deployable-libraries

JSTLライブラリ・ファイル(jstl-1.2.war)

<JDEV_HOME>\wlserver_10.3\common\deployable-libraries

ADFライブラリ・ファイル(adf-richclient-api-11.jar、adf-richclient-impl-11.jar)

<JDEV_HOME>\oracle_common\modules\oracle.adf.view_11.1.1

6. faces-config.xmlおよびtrinidad-config.xmlに、OHWでのJSFとJSTLのサポートを構成します。XMLファイルをohw-rc-thick-demo\ohw-rc-thick-demo\WEB-INFディレクトリからコピーして、<OHW_HOME>\<OHW_deployment_name>\WEB-INFディレクトリに保存します。
faces-config.xmlは、JSFアプリケーションのリソースとページ移動のルールを登録するJSF構成ファイルです。trinidad-config.xmlでは、ADF Faces機能を構成できます。faces-config.xml同様、trinidad-config.xmlは、JSF式言語(EL)または静的値を使用して要素プロパティを定義できる単純なXML構造を持ちます。

7. Oracle WebLogic Serverを使用する場合、weblogic.xmlをohw-rc-thick-demo\ohw-rc-thick-demo\WEB-INFディレクトリからコピーして、<OHW_HOME>\<OHW_deployment_name>\WEB-INFディレクトリに保存します。必要に応じてファイルを編集します。

8. web.xmlをohw-rc-thick-demo\ohw-rc-thick-demo\WEB-INFディレクトリからコピーして、<OHW_HOME>\<OHW_deployment_name>\WEB-INFディレクトリに保存します。次の手順で、必要に応じてファイルを編集します。

1. <display-name></<display-name>と<description></description>セクションを変更して、カスタム・ヘルプセット名を表示します。次に例を示します。

<web-app>
<display-name>My Module</display-name>
<description>My module help</description>
</web-app>

2. オプションで、<servlet>要素の下の<servlet-name>要素を編集して、OHWのアクセスに使用するURLを変更することもできます。アクセスURLの変更の詳細は、第17.7項「OHWのアクセスURLの変更」を参照してください。

9. <OHW-RC_deployment_name>ディレクトリをWARファイルに圧縮します。

10. application.xmlをohw-rc-thick-demo\META-INFディレクトリからコピーして、<OHW-RC_HOME>\META-INFディレクトリに保存します。必要に応じてファイルを編集します。このファイルで、デプロイする各製品のWebモジュール名を指定します。
手順9で作成したWARファイル名を<web-uri></web-uri>要素に指定することもできます。アプリケーションのアクセスURLを変更する場合は、<context-root><context-root>要素を更新します。詳細は、第17.7.2項「アクセスURLの名前の変更」を参照してください。

11. <OHW_HOME>ディレクトリをEARファイルに圧縮します。

12. Oracle WebLogic Serverを起動してEARファイルをデプロイします。Oracle WebLogic Serverが実行されている場合は、サーブレットを最後に起動してから加えた変更が有効になるように、シャットダウンしてから再起動する必要があります。EARファイルのデプロイの詳細は、Oracle Fusion Middleware Oracle WebLogic Server管理コンソール・オンライン・ヘルプのエンタープライズ・アプリケーションのインストールに関する項を参照してください。

13. ブラウザでhttp://<hostname>:<port>/<OHW-RC_deployment_name>/ohguide/を指定します。<hostname>は、Oracle WebLogic Serverがインストールされているシステムの名前です。
デモ・ヘルプ・システムの最初のページがブラウザに表示されます。複数のヘルプセットがある場合は、ツールバーのドロップダウン・リストを使用して1つのヘルプセットを選択し、ヘルプセット・スイッチャをクリックして、選択したヘルプセットのみの目次および索引を表示します。テキスト検索では、選択したヘルプセットの項目のみ検索されます。

17.7 OHWのアクセスURLの変更

OHWにアクセスするURLは、http://<hostname>:<port>/mymodule/ohguide/です。<hostname>は、OHWおよびOracle WebLogic Serverがインストールされているシステムの名前です。

このURLは、次の方法で変更できます。

- アクセスURLの最後のURL要素の変更

- アクセスURLの名前の変更

17.7.1 アクセスURLの最後のURL要素の変更

URLの最後にあるhelpを変更するには、<OHW_HOME>\<OHW_deployment_name>\WEB-INFのweb.xmlを編集します。

<servlet-mapping>のパラメータである<url-pattern>に、OHWへのアクセスに使用するURLを指定します。たとえば、<url-pattern>を、デフォルトの/help/*から/onlinereference/*に変更した場合、OHWへのアクセスに使用するURLはhttp://<hostname>:<port>/mymodule/onlinereference/となります。

次に例を示します。

<servlet-mapping>
<servlet-name>mymodule</servlet-name>
<url-pattern>/onlinereference/*</url-pattern>
</servlet-mapping>

17.7.2 アクセスURLの名前の変更

アプリケーションのアクセスURLを変更するには、<OHW_HOME>\META-INFにあるapplication.xml内で、<web>要素の下の<context-root>要素エントリを編集します。

<web>
<web-uri>my_module.war</web-uri>
<context-root>my_module</context-root>
</web>

たとえば、OHWのアクセスURLをhttp://<hostname>:<port>/jdeveloper/help/にする場合は、ルート要素を次のように変更します。

<web>
<web-uri>my_module.war</web-uri>
<context-root>jdeveloper</context-root>
</web>

17.8 スタンドアロンWebアプリケーションとしてのOHWのデプロイ

OHWのデプロイ方法の1つに、スタンドアロンWebアプリケーションとしてデプロイする方法があります。OHWをスタンドアロン・アプリケーションとしてデプロイするには、OHWの実行に必要なすべてのファイルを含むOHWのWARファイルを、専用のコンテキスト・パスを持つアプリケーション・サーバーの個別のデプロイ・ディレクトリにコピーする必要があります。

次に説明するように、OHW管理者は、主要なタスクを実行してから、スタンドアロンWebアプリケーションとしてOHWヘルプ・システムをデプロイする必要があります。タスクの詳細は、第17章「OHWのデプロイメントの理解」を参照してください。

17.8.1 OHWのアーティファクトのインストール

Oracle WebLogic Serverおよび他のサーブレット・コンテナでは、OHWのモジュールをWAR (Web ARchive)ファイルとして圧縮できます。これらのファイルは、WARファイル、JAR (Java ARchive)ファイルおよびOHWのインストール可能ファイルをラップするEAR (Enterprise ARchive)ファイルとしてデプロイされます。これを行うには、標準のJava JARユーティリティを使用して、WARまたはEARファイルを作成する方法があります。

OHWのWARまたはEARファイルは、WebクライアントがOHWのページにアクセスできるように、アプリケーション・サーバーによって解凍される必要があります。WARまたはEARファイルのデプロイ方法については、関連するアプリケーション・サーバーのガイドラインも参照してください。

また、Oracle JDeveloper StudioのようなWeb開発環境で、Webアプリケーションを手動で作成し、ライブラリ・パスにohw-rcf.jar、ohw-share.jarおよびhelp-share.jarを含め、public htmlディレクトリにohw-rcf-webapp.zipを解凍する方法もあります。

17.8.2 スタンドアロンWebアプリケーションとしてのOHWの構成

すべてのファイルを正しい場所に配置した後、OHWが機能するためには、OHW管理者が一部の構成ファイルを変更する必要があります。

- JSFおよびTrinidadパラメータを含むようにweb.xmlファイルを変更します。
次に例を示します。

<?xml version = '1.0' encoding = 'UTF-8'?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ... >
<context-param>
<param-name>javax.faces.STATE_SAVING_METHOD</param-name>
<param-value>client</param-value>
</context-param>
<context-param>
<param-name>org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION</param-name>
<param-value>false</param-value>
</context-param>
...
...
</web-app>

- OHWフロント・サーブレットおよびJSFフィルタをサポートするようにweb.xmlを変更します。
次に例を示します。

<?xml version = '1.0' encoding = 'UTF-8'?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ... >
...
...
<filter>
<filter-name>trinidad</filter-name>
<filter-class>
org.apache.myfaces.trinidad.webapp.TrinidadFilter
</filter-class>
</filter>
<filter-mapping>
<filter-name>trinidad</filter-name>
<servlet-name>Faces Servlet</servlet-name>
<dispatcher>FORWARD</dispatcher>
<dispatcher>REQUEST</dispatcher>
</filter-mapping>
<servlet>
<servlet-name>Faces Servlet</servlet-name>
<servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet>
<servlet-name>OHW Servlet 1</servlet-name>
<servlet-class>oracle.help.web.rich.OHWServlet</servlet-class>
<init-param>
<param-name>ohwConfigFileURL</param-name>
<param-value>/helpsets/ohwconfig.xml</param-value>
</init-param>
<load-on-startup>2</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>OHW Servlet 1</servlet-name>
<url-pattern>/ohguide/*</url-pattern>
</servlet-mapping>
...
...
</web-app>

- ohwconfig.xmlとhelpsetsディレクトリを作成していない場合は、第17.6項「OHWでのカスタム・ヘルプセットの表示の構成」の手順1、2および3の説明に従って、ファイルとディレクトリを作成してください。
作成している場合、ohwconfig.xmlを変更し、ヘルプ・コンテンツを必要に応じて編集します。表示するヘルプセットと、それらの表示方法を指定します。ロケール、ブランド情報およびその他各種設定も指定できます。このファイルの名前と場所は、ohwConfigFileURLサーブレット初期化パラメータとして設定されます。このパラメータは、サーブレット・コンテナごとに個別に処理されます。ohwConfigFileURLパラメータは、param-valueを指定するweb.xmlで定義されます。

この構成ファイルの詳細は、第8章「Oracle Help for the Web構成ファイル」を参照してください。

アプリケーションのEARファイルの外部でヘルプ・コンテンツを指定する場合、web.xmlファイルを構成する必要があります。<param-value>要素では、変数を使用して、ohwconfig.xmlのパスを次の構文で定義できます。

<init-param>
<param-name>ohwConfigFileURL</param-name>
<param-value>
file:///{%yourVariableName}/help/ohwconfig.xml
</param-value>
</init-param>

OHWのパスで変数({%yourVariableName}など)が検出されると、同じ名前のJavaシステム・プロパティ(yourVariableName)が検索され、その変数値がJavaシステム・プロパティに定義されている値に置き換えられます。Javaシステム・プロパティは、Oracle WebLogic Serverの起動スクリプトで定義できます。

[Ctrl]+[N]のショートカット・キーによる新しいヘルプ・ウィンドウのオープンのサポート

web.xmlを構成して、ユーザーが[Ctrl]キーを押しながら[N]キーを押した場合に、新しいブラウザ・ウィンドウが開かれるように設定できます。次のコードをweb.xmlに追加して、ショートカット・キーのサポートを有効にします。

<context-param>
<param-name>oracle.adf.view.rich.newWindowDetect.OPTIONS</param-name>
<param-value>on</param-value>
</context-param>

部分ページ移動のサポート

パフォーマンスを向上させるために、OHWでの部分ページ移動を有効にできます。デフォルトでは、部分ページ移動のサポートはADF Facesアプリケーションで無効ですが、次のコードをweb.xmlに追加して、ヘルプセット内での使用を有効にできます。

<context-param>
<param-name>oracle.adf.view.rich.pprNavigation.OPTIONS</param-name>
<param-value>onWithForcePPR</param-value>
</context-param>

17.9 Webアプリケーションの一部としてのOHWのデプロイ

OHWのデプロイ方法として、Webアプリケーションと共存させる方法があります。Webアプリケーションとして、JSF、ADFまたはJSPアプリケーション、あるいはJava EE Webアプリケーションを使用できます。これにより、OHWを既存のアプリケーションに含まれるWebプロジェクトの1つとしてデプロイできるようになります。

既存のWebアプリケーションの一部としてOHWをデプロイする場合、WebアプリケーションとOHWヘルプ・システムでは、どちらも同じweb.xmlを共有します。このため、OHWヘルプ・システムの詳細なチューニングが制限され、アプリケーションで競合が生じる場合があります。OHWをWebアプリケーションから個別にデプロイして、ヘルプ・システムとアプリケーションをリンク付けることをお薦めします。詳細は、第17.8項「スタンドアロンWebアプリケーションとしてのOHWのデプロイ」を参照してください。アプリケーションでADF Facesを使用する場合、ADFアプリケーションのADF FacesコンポーネントでhelpTopicId属性を使用できます。詳細は、第19.2項「オンライン・ヘルプとADF Facesアプリケーションの統合」を参照してください。

17.9.1 OHWのアーティファクトのインストール

ohw-rcf-webapp.zipを、既存のWebアプリケーションのpublic_htmlフォルダ(またはWebアプリケーションのルート・ディレクトリ)に解凍します。

ohw-rcf.jar、ohw-share.jarおよびhelp-share.jarファイルを、アプリケーションのWEB-INF/libフォルダ、または定義されたライブラリ・フォルダにコピーします。JDeveloperで開発している場合は、これらのJARファイルをプロジェクト(「プロジェクト・プロパティ」 > 「ライブラリとクラスパス」)に追加してください。

17.9.2 Webアプリケーションの一部としてのOHWの構成

すべてのファイルを正しい場所に配置した後、OHWが機能するためには、OHW管理者が一部の構成ファイルを変更する必要があります。

- JSFおよびTrinidadパラメータがない場合は、これらを含むようにweb.xmlファイルを変更します。
次に例を示します。

<?xml version = '1.0' encoding = 'UTF-8'?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ... >
<context-param>
<param-name>javax.faces.STATE_SAVING_METHOD</param-name>
<param-value>client</param-value>
</context-param>
<context-param>
<param-name>org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION</param-name>
<param-value>true</param-value>
</context-param>
...
...
</web-app>

- OHWフロント・サーブレットおよびJSFフィルタをサポートするようにweb.xmlを変更します。
OHWが既存のアプリケーションの一部であるため、OHW管理者は、load-on-startup順序が、正しい順序で維持されているかどうかを確認する必要があります。

次に例を示します。

<?xml version = '1.0' encoding = 'UTF-8'?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ... >
...
...
<filter>
<filter-name>trinidad</filter-name>
<filter-class>
org.apache.myfaces.trinidad.webapp.TrinidadFilter
</filter-class>
</filter>
<filter-mapping>
<filter-name>trinidad</filter-name>
<servlet-name>Faces Servlet</servlet-name>
<dispatcher>FORWARD</dispatcher>
<dispatcher>REQUEST</dispatcher>
</filter-mapping>
<servlet>
<servlet-name>Faces Servlet</servlet-name>
<servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet>
<servlet-name>product1</servlet-name>
<servlet-class>oracle.help.web.rich.OHWServlet</servlet-class>
<init-param>
<param-name>ohwConfigFileURL</param-name>
<param-value>/helpsets/product1/ohwconfig.xml</param-value>
</init-param>
<load-on-startup>2</load-on-startup>
</servlet>
...
...
</web-app>

- ohwconfig.xmlを変更し、必要に応じてヘルプ・コンテンツを編集します。ヘルプセットまたはohwconfig.xmlファイルを作成していない場合は、手順1、2および3の説明に従って作成してください。
ohwconfig.xmlファイルは、表示するヘルプセットと、それらの表示方法を指定します。ロケール、ブランド情報およびその他各種設定も指定できます。このファイルの名前と場所は、(web.xmlで定義される)ohwConfigFileURLサーブレット初期化パラメータとして設定されます。このパラメータは、サーブレット・コンテナごとに個別に処理されます。この構成ファイルの詳細は、第8章「Oracle Help for the Web構成ファイル」を参照してください。

17.10 1つのWebアプリケーションへの複数ヘルプ・インスタンスのデプロイ

OHWでは、1つのWebアプリケーションまたはエンタープライズ・アプリケーションに、複数のヘルプ・インスタンス(1つのヘルプ・インスタンスには複数のヘルプセットが含まれる場合があります)をデプロイすることがサポートされています。このサポートの主な理由の1つは、OHW構成からのアップグレード時に必要となる変更を最小限に抑えるためです。OHWの複数ヘルプ・インスタンスのデプロイは、JSFサーブレットにリクエストを転送するOHWフロント・サーブレットを用意することによって可能になります。

17.10.1 アプリケーションおよびOHWの構成ファイルの設定

OHWフロント・サーブレットにサーブレット・マッピングを追加するように、アプリケーションのweb.xmlファイルを変更する必要があります。

次に、OHWの複数ヘルプ・インスタンスのデプロイをサポートするために必要な変更を行ったweb.xmlファイルの例を示します。

<!-- configuration for product1 help front servlet -->
<servlet>
<servlet-name>product1</servlet-name>
<servlet-class>oracle.help.web.rich.OHWServlet</servlet-class>
<init-param>
<param-name>ohwConfigFileURL</param-name>
<param-value>/helpsets/product1/ohwconfig.xml</param-value>
</init-param>
<load-on-startup>2</load-on-startup>
</servlet>

<!-- configuration for product2 help front servlet -->
<servlet>
<servlet-name>product2</servlet-name>
<servlet-class>oracle.help.web.rich.OHWServlet</servlet-class>
<init-param>
<param-name>ohwConfigFileURL</param-name>
<param-value>/helpsets/product2/ohwconfig.xml</param-value>
</init-param>
<load-on-startup>3</load-on-startup>
</servlet>

<servlet-mapping>
<servlet-name>product1</servlet-name>
<url-pattern>/product1/*</url-pattern>
</servlet-mapping>

<servlet-mapping>
<servlet-name>product2</servlet-name>
<url-pattern>/product2/*</url-pattern>
</servlet-mapping>

このサンプル・コードには、product1およびproduct2という2つのOHWフロント・サーブレットがあります。各サーブレットは、ユーザー・インタフェースに表示するブックおよびビューのセットを決定するOHW構成ファイルを、個別にロードできます。product1サーブレットは、URLパターン/product1/*にマップされています。これにより、URLの最後の部分にproduct1を含む、リッチOHWのコンテキスト・ルートにマップされたURLを指定すると、このサーブレットに再ルーティングされます。同様に、product2は、URLパターン/product2/*にマップされています。

17.10.2 アプリケーションの実行

OHWをアプリケーション・サーバーに正常にデプロイした後、次のようなURLを使用して、構成済のOHWフロント・サーブレットに接続できます。

http://www.myhelpserver.com:<port>/docs/product1

前例のURLでは、/helpsets/product1/ohwconfig.xmlのOHW構成ファイルをロードするproduct1サーブレットが呼び出され、次のようなURLにリダイレクトされます。

http://www.myhelpserver.com:<port>/docs/faces/helppages/main.jspx?config=product1

また、OHWは(OHWと同様に)、URLに追加されたロケールおよびグループ情報を処理できます。

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

この章では、Webアプリケーションで状況依存ヘルプを有効にする方法、およびヘルプ・トピックにトピックIDをマップする方法について説明します。

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

- Webアプリケーションでの状況依存ヘルプの実装について

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

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

18.1 Webアプリケーションでの状況依存ヘルプの実装について

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

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

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

OHWの状況依存ヘルプ・システムには、ヘルプ・トピックHTMLファイルにトピックIDをマップする1つ以上のマップ・ファイルが必要となります。ヘルプセットでは、マップ・ファイルはmap.xmlとして、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属性はオプションであり、トピックを表示するウィンドウ・タイプの名前を指定します。マップ・ファイルで使用される要素の詳細は、第5.3項「マップ・ファイル」を参照してください。

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

状況依存ヘルプの実装にOHWを使用するアプリケーションは、OHWサーブレットへの特別な形式のURLを使用して状況依存トピックを要求します。宛先URL(リンク、イメージなど)を持つすべてのユーザー・インタフェース・コントロールを、状況依存トピックに関連付けることができます。

状況依存ヘルプ用のOHWへのリンクを作成するには、フロント・メイン・ページ(「目次」、「索引」および「検索」ナビゲータがページ左側の3つのペインにレイアウトされたUI)の宛先URLを使用するか、またはトピックIDを使用して、3ペイン・レイアウトUIでトピックを表示する宛先URLを作成できます。また、宛先URLにロケールおよびグループを指定することもできます。

- 第18.3.1項「フロント・メイン・ページへのリンク」

- 第18.3.2項「トピックへのリンク」

- 第18.3.3項「ロケールおよびグループの指定」

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

フロント・メイン・ページのURLは、次のように、単にOHWサーブレットのURLとなります。

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

<server>はサーブレット・コンテナを実行するサーバーの名前、<port>はサーブレット・コンテナが使用するポート、および<servlet mapping>はOHWサーブレット(oracle.help.web.rich.OHWServlet)用のweb.xmlファイルに設定されているサーブレット・マッピングです。

たとえば、web.xmlには、次のようなサーブレット定義およびサーブレット・マッピングが設定されています。

<!-- configuration for product1 help front servlet -->
<servlet>
<servlet-name>product1</servlet-name>
<servlet-class>oracle.help.web.rich.OHWServlet</servlet-class>
<init-param>
<param-name>ohwConfigFileURL</param-name>
<param-value>/helpsets/product1/ohwconfig.xml</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>

<servlet-mapping>
<servlet-name>product1</servlet-name>
<url-pattern>/product1/*</url-pattern>
</servlet-mapping>

この例の場合、フロント・メイン・ページのURLは次のとおりです。

http://www.myhelpserver.com:8888/docs/product1/

ユーザーがフロント・メイン・ページにリンクされたユーザー・インタフェース・コントロールのヘルプを要求すると、ユーザーのブラウザにOHWのメイン・ページが表示され、「目次」、「索引」および「検索」ナビゲータが、左側に3ペイン・レイアウトで表示されます。

18.3.2 トピックへのリンク

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

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

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

http://www.myhelpserver.com:8888/docs/product1/?topic=topic_1

OHWへの状況依存リンクを実装するときに、アプリケーションのメイン・ページを置き換えるのではなく、JavaScriptを使用して2次ウィンドウにリンク先が表示されるようにする場合があります。

ユーザーがトピックIDにリンクされたユーザー・インタフェース・コントロールのヘルプを要求すると、3ペイン・レイアウトUIで、「トピック」ナビゲータ(右側)にトピック・ファイルが表示され、「目次」ナビゲータ(左側)の目次ツリーでのそのトピックが選択されます。

18.3.3 ロケールおよびグループの指定

トピック・ページまたはフロント・ページなどのOHWページへのリンクを作成する場合は、localeおよびgroup問合せパラメータを使用して、OHWサーブレットのURLにロケールおよびグループを含めることができます。

トピックの構文は、次のとおりです。

http://<server>:<port>/<servlet-mapping>/?topic=<topic-id>&locale=<ISO-code>
http://<server>:<port>/<servlet-mapping>/?topic=<topic-id>&locale=<ISO-code>&group=<aGroup>

フロント・ページの構文は、次のとおりです。

http://<server>:<port>/<servlet-mapping>/?locale=<ISO-code>
http://<server>:<port>/<servlet-mapping>/?locale=<ISO-code>&group=<aGroup>

ロケールを指定した場合、OHWによって、ローカライズ済ヘルプセット(使用可能な場合)に切り替えられ、指定したロケールが上書きまたは削除されるまで引き続きそのロケールが使用されます。指定したローカライズ済ヘルプセットがない場合、このパラメータは無視されます。

次に例を示します。

http://www.myhelpserver.com:7101/docs/product1/?topic=topic_1&locale=sp

ロケールおよびグループの詳細は、第8章「Oracle Help for the Web構成ファイル」を参照してください。

19 ADFリッチ・クライアントのヘルプ・プロバイダ

この章では、オンライン・ヘルプとADF Facesアプリケーションの統合方法およびOHWのヘルプ・プロバイダとしての登録方法について説明します。

この章には、次のセクションがあります。

- ADFリッチ・クライアントのヘルプ・プロバイダについて

- オンライン・ヘルプとADF Facesアプリケーションの統合

- ADFリッチ・クライアントのヘルプ・プロバイダとしてのOHWの登録

- HelpTopicId属性の使用

- その他のヘルプ・プロバイダの使用

19.1 ADFリッチ・クライアントのヘルプ・プロバイダについて

ご使用のADF Facesアプリケーションにオンライン・ヘルプを組み込む場合、ADF Faces (ADFリッチ・クライアントとも呼ばれる)には、そのための簡単な方法が用意されています。オンライン・ヘルプ・システムを作成して、アプリケーションのコンポーネントにヘルプ・トピックを統合できます。

この章では、ヘルプ・プロバイダとしてのOHWの構成方法、ADFリッチ・クライアントのその他のヘルプ・プロバイダ、およびHelpTopicId属性を使用してヘルプ・トピックをアプリケーションに関連付ける方法について説明します。

19.2 オンライン・ヘルプとADF Facesアプリケーションの統合

ヘルプ・トピックをADF Facesコンポーネントと統合すると、そのコンポーネントにヘルプ・アイコン(疑問符を青色の円で囲んだもの)が表示されます。ヘルプ・アイコンをクリックすると、図19-1に示すように、関連するヘルプ・トピックが新しいウィンドウに表示されます。

図19-1 ADF Facesアプリケーションのヘルプ・アイコン

次の手順で説明するように、オンライン・ヘルプとアプリケーションとの統合は簡単なプロセスです。

- ヘルプ・プロバイダのアプリケーションでの登録

- 各ヘルプ・トピックのトピックIDおよびヘルプ・テキストを含むプロパティ・ファイルの作成

- HelpTopicId属性を使用した、UIコンポーネントのヘルプ・トピックへの関連付け

オンライン・ヘルプとアプリケーションとの統合の詳細は、『Oracle ADF FacesによるWebユーザー・インタフェースの開発』のコンポーネントのヘルプの表示に関する項を参照してください。

19.3 ADFリッチ・クライアントのヘルプ・プロバイダとしてのOHWの登録

ADF Facesリッチ・クライアントには、多様なヘルプ・プロバイダが用意されています。これらの異なるヘルプ・プロバイダを組み合せるか、独自のヘルプ・プロバイダ・クラスを作成できます。また、ヘルプ・プロバイダとしてOHWを使用することもできます。

ADFリッチ・クライアント・アプリケーションのヘルプ・プロバイダとしてOHWを設定するには、次のタスクを実行する必要があります。

1. WebアプリケーションとしてOHWをデプロイします。

1. Webアプリケーション・サーバーにADFアプリケーションをデプロイします。

2. このデプロイのコンテキスト・ルートを書き留めます。

3. このデプロイのweb.xmlファイルを開きます。

4. OHWサーブレット・インスタンスを見つけます。

2. jspx Webページを開発します。

1. ADF FacesベースのWebアプリケーションを作成します。

2. 特定のコンポーネント(input*、select*など)用にjspx Webページを作成し、helpTopicIdという名前の属性を見つけて、OHWインスタンスで表示するIDを指定します。

3. ヘルプセットをコピーし、<application_root>/public_htmlフォルダの下にあるディレクトリに配置します。たとえば、このディレクトリをhelpsetsという名前にします。

4. adf-settings.xmlファイルを設定します。

1. アプリケーションのディレクトリに移動し、.adf/META-INF/ディレクトリを検索します。このディレクトリの下に、adf-settings.xmlファイルがあります。.adf/META-INF/ディレクトリがない場合は、META-INFディレクトリを、ViewController/srcディレクトリの下に作成します。

2. adf-settings.xmlにコードを入力します。次に例を示します。

<?xml version="1.0" encoding="UTF-8" ?>
<adf-settings xmlns="http://xmlns.oracle.com/adf/settings">
<adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/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-faces-config>
</adf-settings>

このadf-settings.xmlファイルを、次のように設定してください。

- OHWをヘルプ・プロバイダとして使用する場合は、このadf-settings.xmlファイルで、クラスをOHWHelpProviderにする必要があります。

- ohwConfigFileURLプロパティを、/helpsets/ohwconfig.xmlを指すように設定します。helpsetsディレクトリは、手順3で作成したものです。

注意:
propシステム・プロパティを使用して、ohwConfigURLを指定することもできます。たとえば、web.xmlでは、ohwConfigURLは次のように構成されます。

<param-name>ohwConfigFileURL</param-name>
<param-value>file:///{%prop}/help/ohwconfig.xml</param-value>

adf-settings.xmlでは、ohwConfigURLは次のように構成されます。

<property>
<property-name>ohwConfigFileURL</property-name>
<value>file:///{%prop}/help/ohwconfig.xml</value>
</property>

propプロパティは、Oracle WebLogic Serverを-Dpropオプションを指定して起動することで事前定義または指定できます。たとえば、-Dprop=/Oracle/helpと指定します。

- groupプロパティに、ohwconfig.xmlファイルのグループ名(ヘルプ・プロバイダで使用するもの)を指定します。

- baseURIプロパティに、手順1でデプロイしたRCFアプリケーションの、サーバー・ホスト、コンテキスト・ルートおよびOHWサーブレット・インスタンスを指定します。

19.4 HelpTopicId属性の使用

ヘルプ・トピックをADFコンポーネントに関連付けるには、ヘルプ・トピックの一意のIDをHelpTopicId属性の値として割り当てる必要があります。HelpTopicId属性は、「プロパティ」ウィンドウの「外観」セクションで使用できます。

図19-2 HelpTopicId属性

ヘルプ・トピックをコンポーネントに関連付ける前に、アプリケーションにヘルプ・プロバイダが登録されていることを確認してください。ヘルプ・プロバイダとしてOHWを登録するには、第19.3項「ADFリッチ・クライアントのヘルプ・プロバイダとしてのOHWの登録」を参照してください。

HelpTopicId属性の詳細は、『Oracle ADF FacesによるWebユーザー・インタフェースの開発』のコンポーネントのヘルプの表示に関する項を参照してください。

19.5 その他のヘルプ・プロバイダの使用

ADFリッチ・クライアントの一般的な2つのヘルプ・プロバイダは、ResourceBundleHelpProviderとELHelpProviderです。ResourceBundleHelpProviderでは、リソース・バンドルに定義されているヘルプをADF Facesアプリケーションに表示できます。リソース・バンドルは、ヘルプ・ファイル、制御ファイル、グラフィックおよびその他の関連ファイルのコンテナです。ELHelpProviderでは、XLIFFファイルに定義されているヘルプ・テキストをADF Facesアプリケーションに表示できます。XLIFFファイルはマップに変換されるか、ヘルプ・テキスト文字列のマップを含むマネージドBeanを作成します。ELHelpProviderではヘルプ・ファイルは作成されませんが、このファイルをADF Facesアプリケーションに関連付けるのに役立ちます。

これらと他のヘルプ・プロバイダの詳細は、『Oracle ADF FacesによるWebユーザー・インタフェースの開発』のコンポーネントのヘルプの表示に関する項を参照してください。

A Oracle HelpおよびJavaHelpのファイル形式

この付録では、JavaHelp仕様に基づいたOracle Helpのファイル形式について説明します。Oracle Helpでは、追加機能に対応するためにJavaHelpのファイル定義を拡張しています。

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

- ヘルプセット・ファイル

- マップ・ファイル

- 目次ファイル

- 索引ファイル

- 検索索引ファイル

- リンク・ファイル

- OHW構成ファイル

ここで示す表には、次の表記規則が適用されます。

- 要素列では、子要素は親要素の下にインデントされます。

- 属性列の項目は、属性のすぐ上にリストされている要素の属性です。

- 由来列のJHは、JavaHelp 1.0ファイル形式の仕様を表します。OHは、Oracle Helpを表します。オラクル社によるJavaHelpの拡張機能は、当初、Oracle Help for Java (OHJ)用に開発されました。ただし、現在では、ほとんどの形式が、OHJおよびOracle Help for the Web (OHW)の両方に適用されています。このため、OHのみが記載されています。

- サポート列のOHは、OHJおよびOHWの両方を表します。

A.1 ヘルプセット・ファイル

このファイルの詳細は、第5.2項「ヘルプセット・ファイル」を参照してください。

表A-1 ヘルプセット・ファイルの要素

要素

属性

由来

サポート

<helpset>

-

JH

OHおよびJH: 相違点については以下を参照

-

xml:lang

JH

JHのみ

-

version

JH

JHのみ

<title>

-

JH

OHおよびJH

<maps>

-

JH

OHおよびJH

<homeID>

-

JH

JHおよび(一部の環境の)OH

<mapref>

-

JH

OHおよびJH: 相違点については以下を参照

-

location

JH

OHおよびJH

-

class

OH

OHのみ

<wintype>

-

OH

OHのみ

-

default

OH

OHのみ

<name>

-

OH

OHのみ

<height>

-

OH

OHのみ

<width>

-

OH

OHのみ

<x>

-

OH

OHのみ

<y>

-

OH

OHのみ

<textfg>

-

OH

OHのみ

<linkfg>

-

OH

OHのみ

<bg>

-

OH

OHのみ

<title>

-

OH

OHのみ

<toolbar>

-

OH

OHのみ

<links>

-

OH

OHのみ

<linkref>

-

OH

OHのみ

-

location

OH

OHのみ

<view>

-

JH

OHおよびJH: 相違点については以下を参照

<name>

-

JH

JHのみ

<label>

-

JH

OHおよびJH

-

image

OH

OHのみ

<title>

-

OH

OHのみ

-

image

OH

OHのみ(目次ビューのみ)

<type>

-

JH

OHおよびJH

<data>

-

JH

OHおよびJH: 相違点については以下を参照

-

class

OH

OHのみ

-

engine

JH

OHおよびJH

<subhelpset>

-

OH

OHのみ

-

location

OH

OHのみ

-

class

OH

OHのみ

A.2 マップ・ファイル

このファイルの詳細は、第5.3項「マップ・ファイル」を参照してください。

表A-2 マップ・ファイルの要素

要素

属性

由来

サポート

<map>

-

JH

OHおよびJH: 相違点については以下を参照

-

xml:lang

JH

JHのみ

-

version

JH

JHのみ

<mapID>

-

JH

相違点については以下を参照

-

target

JH

OHおよびJH

-

url

JH

OHおよびJH

-

wintype

OH

OHのみ

-

xml:lang

JH

JHのみ

A.3 目次ファイル

このファイルの詳細は、第6.2項「目次ファイル」を参照してください。

表A-3 目次ファイルの要素

要素

属性

由来

サポート

<toc>

-

JH

OHおよびJH: 相違点については以下を参照

-

xml:lang

JH

JHのみ

-

version

JH

JHのみ

<tocitem>

-

JH

相違点については以下を参照

-

target

JH

OHおよびJH

-

テキスト

JH

OHおよびJH

-

image

JH

OHおよびJH

-

xml:lang

JH

JHのみ

A.4 索引ファイル

このファイルの詳細は、第6.4項「索引ファイル」を参照してください。

表A-4 索引ファイルの要素

要素

属性

由来

サポート

<index>

-

JH

OHおよびJH: 相違点については以下を参照

-

xml:lang

JH

JHのみ

-

version

JH

JHのみ

<indexitem>

-

JH

OHおよびJH: 相違点については以下を参照

-

target

JH

OHおよびJH

-

テキスト

JH

OHおよびJH

<indexentry>

-

OH

OHのみ

-

target

OH

OHのみ

-

テキスト

OH

OHのみ

A.5 検索索引ファイル

このファイルはOracle Helpに固有です。詳細は、第6.5項「検索索引ファイル」を参照してください。

A.6 リンク・ファイル

このファイルはOracle Helpに固有です。詳細は、第6.6項「リンク・ファイル」を参照してください。

A.7 OHW構成ファイル

このファイルはOracle Helpに固有です。詳細は、第8章「Oracle Help for the Web構成ファイル」を参照してください。

B Javaモーダル・ウィンドウの問題への対処

この付録では、モーダル・ウィンドウに状況依存のヘルプ・トピックを表示しようとすると問題が発生する場合、Javaでそのモーダル・ウィンドウがどのように処理されるかについて説明します。モーダル・ウィンドウとは、そのウィンドウから制御を移動できないウィンドウのことです。モーダルではないウィンドウとは、他のウィンドウに制御の切替えが可能なウィンドウのことです。

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

- Javaモーダル・ウィンドウの問題について

- ウィンドウの登録

- ウィンドウの登録解除

B.1 Javaモーダル・ウィンドウの問題について

ユーザーがモーダルではないウィンドウからヘルプを要求した場合は、ヘルプ・ウィンドウと要求元ウィンドウを自由に切り替えることができます。ただし、モーダル・ウィンドウからヘルプを要求した場合は切替えを行うことができません。Javaでは、モーダル・ウィンドウは、さらに別のモーダル・ウィンドウを除いて、Java仮想マシンによって生成された他のウィンドウへのアクセスをすべてブロックします。このため、ヘルプがモーダル・ウィンドウから要求された場合、OHJはモーダルなヘルプ・ウィンドウにヘルプを表示する必要があります。OHJ自体がモーダル・ウィンドウに表示されるため、アプリケーションに戻るには、ヘルプ・ウィンドウを閉じる必要があります。

ヘルプがリクエストされると、OHJは、アクティブ・ウィンドウがモーダルかどうかを判断します。モーダルの場合、通常のOHJトピック・ウィンドウとOHJナビゲータ・ウィンドウの親を新しいモーダル・ウィンドウに変更します。新しいウィンドウは、ユーザーのディスプレイの最前面に表示され、ユーザーはそのウィンドウで操作できます。単純にモーダル・ヘルプ・ウィンドウを閉じる場合にも、一切にウィンドウを操作する必要があります。Javaでのモダリティの実装が粗密な場合、これは、現在OHJでサポートされるすべてのJava仮想マシンで機能する唯一のソリューションになります。

B.2 ウィンドウの登録

OHJの回避策が機能するためには、OHJは現在アクティブであるウィンドウを追跡できる必要があります。registerClientWindow()メソッドを使用し、作成する各ウィンドウ(フレームまたはダイアログ)をHelpオブジェクトに登録します。

表B-1 registerClientWindow()メソッド

コンストラクタ

説明

registerClientWindow(Window aWindow)

Helpオブジェクトに登録されたウィンドウ・インスタンスを追跡します。アクティブ・ウィンドウがモーダル・ダイアログである場合にヘルプが要求されると、Helpオブジェクトは、アクティブなモーダル・ダイアログがヘルプ・ウィンドウをブロックしないように、特別な処理を行います。

パラメータ:

- aWindow: 登録対象のウィンドウ・インスタンス。

B.3 ウィンドウの登録解除

Help.registerClientWindow()を使用してウィンドウ・オブジェクトを登録した場合、そのオブジェクトの登録も解除する必要があります。ウィンドウがアクティブではなくなることに気付いたら、unregisterClientWindow()メソッドを使用して、Helpオブジェクトからウィンドウの登録を解除する必要があります。ウィンドウ・インスタンスの登録解除に失敗すると、ウィンドウはガベージ・コレクションの対象外となるため注意してください。

表B-2 unregisterClientWindow()メソッド

メソッド

説明

unregisterClientWindow(Window aWindow)

クライアントは、registerClientWindow()を使用して登録したウィンドウ・インスタンスのウィンドウがアクティブではなくなると、その登録を解除する必要があります。登録解除に失敗すると、そのウィンドウはガベージ・コレクションの対象外となります。

パラメータ:

- aWindow: 登録対象のウィンドウ・インスタンス。

C ヘルプ・ブックの処理

この付録では、古いバージョンのOHJでヘルプ・ブック・ファイルおよびHelpBookオブジェクトが使用されていることについて説明します。ヘルプ・ブックは現行バージョンのOHJでもまだサポートされていますが、現行バージョンではヘルプセット(ヘルプセット・ファイルおよびHelpSetオブジェクト)を使用することをお薦めします。

ヘルプ・ブック・ファイルおよびHelpBookオブジェクトをまだ使用しており、ヘルプセットを使用していない場合は、次の項のヘルプ・ブック固有の情報を参照してください。

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

- ヘルプ・ブック・ファイル名の拡張子

- OHJへのHelpデータの追加

- Oracle Help for the Web構成ファイルのロケール

C.1 ヘルプ・ブック・ファイル名の拡張子

ヘルプ・ブックを使用する場合は、ファイル名および拡張子が正しいことを確認してください。OHJおよびOHWは、指定されたディレクトリで、サポートするファイル形式に対応したファイル名の拡張子(TOC、TOK、HHC、HHK、OHTおよびIDXを含む)を検索します。正しいファイル名および拡張子の詳細は、第4.2項「ファイル名の拡張子」を参照してください。

ヘルプセットを使用する場合は、関連する制御ファイルの名前に、指定された拡張子を使用する必要はありません。

C.2 OHJへのHelpデータの追加

ヘルプ・ブックをOHJに追加する場合は、まず、Helpオブジェクトを作成する必要があります。詳細は、第13.2項「Helpオブジェクトの構成」を参照してください。

注意:
ヘルプ・ブックを使用してOHJシステムを実装している場合、マップ・ファイルにOHTファイル形式を使用する必要があります。ヘルプ・ブック・ファイルおよびOHTファイルは、OHJの初期バージョンのレガシーであり、現在は使用が推奨されていませんが、まだサポート対象となっています。マップ・ファイルの詳細は、第5.3項「マップ・ファイル」を参照してください。

Helpオブジェクトを作成した後、1つ以上のBookオブジェクトを追加する必要があります。Bookオブジェクトによって、コレクション(つまり、ヘルプ・コンテンツのブック)がカプセル化されます。

HelpBookブックのこの実装によって、レガシーOHJのファイル形式が処理されます。HelpBookクラスは、ディレクトリを調べて、既知の拡張子のファイルを識別し、ヘルプ・システムに追加します。

次の項では、ヘルプ・ブックおよび他のオプション機能を追加する方法について説明します。

- 第C.2.1項「ヘルプ・ブックの構築」

- 第C.2.2項「ヘルプへのブックの追加」

詳細は、oracle.help.library.helpset.HelpSetのAPIドキュメントを参照してください。

C.2.1 ヘルプ・ブックの構築

HelpBookの形式は、ディレクトリ・ベースです。コンストラクタを使用して、ヘルプ・コンテンツ(HTMLトピック・ファイル)のあるディレクトリの場所を指定します。

表C-1 HelpBook()コンストラクタ

コンストラクタ

説明

HelpBook(String baseURL, String baseName, String bookTitle)

baseURLに指定されたディレクトリからデータをロードする、指定されたタイトルのHelpBookを作成します。HelpBookオブジェクトでは、ディレクトリを調べ、指定されたbaseNameの名前が付けられた既知の制御ファイル(TOC、TOK、HHC、HHK、OHTおよびIDX)を識別します。このコンストラクタは、ヘルプ・コンテンツの正確な場所がわかっている場合に使用してください。

パラメータ:

- baseURL: ヘルプセット・ファイルの正確な場所をURL形式で指定する文字列。

- baseName: 指定されたディレクトリ内に見つかった制御ファイルのベース名(たとえば、制御ファイルの名前が、userguide.hhc、userguide.hhkなどである場合、baseNameはuserguideです)。

- bookTitle: 複数ブックのヘルプ・システムにおいてブック選択のプルダウン・メニューに表示されるブック名。多くの場合、タイトルはヘルプ作成者が指定します。

HelpBook(Class baseClass, String dirPathExt, String baseName, String bookTitle)

baseClassおよびdirPathExtに指定されたディレクトリからデータをロードする、指定されたタイトルのHelpBookを作成します。HelpBookオブジェクトでは、ディレクトリを調べ、指定されたbaseNameの名前が付けられた既知の制御ファイル(TOC、TOK、HHC、HHK、OHTおよびIDX)を識別します。このコンストラクタは、アプリケーションの実装を基準としたヘルプ・コンテンツ・ディレクトリの相対パスのみがわかっている場合に使用してください。

パラメータ:

- baseClass: アプリケーション・クラスの1つ。HelpBookオブジェクトは、このクラスの場所を使用し、ヘルプ・コンテンツ・ディレクトリの場所を決定します。

- dirPathExt: baseClassの場所を基準としたヘルプ・コンテンツ・ディレクトリの相対パス。このパラメータの値は、baseClassのあるディレクトリの絶対パスに追加されます。追加により生成されるパスは、ヘルプ・コンテンツ・ディレクトリのパスです。

- baseName: 指定されたディレクトリ内に見つかった制御ファイルのベース名(たとえば、制御ファイルの名前が、discoverer.hhc、discoverer.hhkなどである場合、baseNameはdiscovererです)。

- bookTitle: 複数ブックのヘルプ・システムにおいてブック選択のプルダウン・メニューに表示されるブック名。多くの場合、タイトルはヘルプ作成者が指定します。

C.2.2 ヘルプへのブックの追加

Bookインスタンスを、HelpBookコンストラクタまたはHelpSetコンストラクタを使用して構築した後、BookをHelpインスタンスに追加する必要があります。ヘルプにブックを追加するには、Helpインスタンスで次のメソッドを呼び出します。

表C-2 addBook()コンストラクタ

コンストラクタ

説明

addBook(Book book)

このメソッドでは、Bookインスタンスがヘルプ・システムに追加されます。Bookに含まれる作成者定義ビューがナビゲータ・ウィンドウに表示され、Bookからのトピックを表示できるようになります。

パラメータ:

- book: ヘルプ・システムに追加するBookインスタンス。

C.3 Oracle Help for the Web構成ファイルのロケール

Oracle Help for the Web構成ファイル(ohwconfig.xml)のロケールを構成する場合、<locales>セクションに単一のロケールまたは複数のロケールを指定できます。

この構成ファイルの詳細は、第8章「Oracle Help for the Web構成ファイル」を参照してください。

C.3.1 <locale>の子要素である<books>

<books>要素は、Oracle Help for the Webで表示されるコンテンツを指定します。<books>要素には、任意の数のヘルプ・ブック、またはヘルプセットとヘルプ・ブックの組合せを指定できます。ヘルプセットおよびヘルプ・ブックはブックとも呼ばれます。

表C-3に、<helpbook>子要素を示します。

表C-3 <books>の子要素

の子要素である<books>の子要素を示します。" title="<books>の子要素" width="100%">

要素

説明

<helpBook>

このOHWインスタンスに含めるヘルプ・ブック。この要素には、次の属性があります。

- id: このブックの一意のID。この属性は必須です。

- basename: ディレクトリにある制御ファイルの名前(拡張子を除いた部分)。たとえば、制御ファイルの名前が、myproject.hhc、myproject.hhk、myproject.idxなどの場合、basenameはmyprojectです。

- location: ヘルプ・ブック・ファイルの場所。このパスは、OHW構成ファイルの場所を示す絶対パスまたは相対パスを指定できます。

- title: ヘルプ・ブックまたはヘルプセットがマージされた場合に使用するタイトル。ヘルプ・ブックは、OHWユーザー・インタフェースのマージされたブック・リストに表示されます。ただし、このタイトルは、ヘルプセットのヘルプセット・ファイルの<title>要素に設定されています。

- controlFileencoding: Javaでサポートされるエンコーディング名。サポートされるエンコーディングのセットは、JDKのバージョンに応じて異なります。Java SEでサポートされるエンコーディングのリストについては、http://download.oracle.com/javase/1.5.0/docs/guide/intl/encoding.doc.htmlを参照してください。

次に例を示します。

<books>
<helpBook id="disco" baseName="discoverer" location="discoverer/" title="Discoverer Help" />
</books>

<helpbook>には、ヘルプ・トピック・ファイルがOracle Helpの予期していない場所にある場合のために、0(ゼロ)以上の<contentLocation>要素を含めることができます。

<books>の他の子要素の詳細は、第8.4.1項「<books>子要素」を参照してください。

C.3.2 <contentLocation>要素

デフォルトでは、OHWは自動的に、ヘルプ・ブックのベース・ディレクトリと同じ場所にあるヘルプ・トピック・ファイルを処理します。

ヘルプ・ブックでは、OHWは、次の場所にあるヘルプ・トピックHTMLファイルを処理します。

- ヘルプ・ブックのベース・ディレクトリおよびそのサブディレクトリ内。

- ヘルプ・ブックがJARファイルの中にある場合、そのJARファイルに含まれるすべてのヘルプ・トピック・ファイル。

ヘルプ・トピック・ファイルが別の場所にある場合は、<contentLocation>要素を使用してその場所を指す必要があります。

<contentLocation>要素には属性baseURIがあります。これは、絶対パスまたは相対パスのいずれかを使用して、ヘルプ・コンテンツのセットのルートの場所を示すURIを表します。

<contentLocation>要素は、<helpbook>の子要素として指定できます。<helpbook>には、0(ゼロ)以上の<contentLocation>要素を含めることができます。

プレーンHTMLファイルとは異なり、Oracle Helpのヘルプ・トピック・ファイルは、表示されるためにサーブレットによって処理される必要があるため、この要素が必要になります。そのため、ヘルプブックで参照されるヘルプ・トピック・ファイルがデフォルトの場所にない場合、それらが存在する場所を明示的にリスト表示する必要があります。これは、別の場所または別のWebサーバーにあるサブヘルプセットがヘルプセットに含まれる場合、あるいは状況依存マップ・ファイルに、同じサーバーまたは別のサーバーの他の場所にあるヘルプ・トピック・ファイルの参照が含まれる場合に生じます。

詳細は、第8.4.2項「<contentLocation>要素」を参照してください。

D Oracle Help for the Web-UIX

この付録では、Oracle Help for the Web-UIX (OHW-UIX)について説明します。OHW-UIXは、HTMLに基づくヘルプ・コンテンツをWeb環境で開発し、配信するためのJavaサーブレットおよびファイル形式仕様です。

OHW-UIXを使用すると、Webアプリケーションの状況依存ヘルプを提供したり、独立したHTMLコンテンツの構造化されたビューをWebで処理および表示できます。OHW-UIXでは、ユーザーに必要となるのは、ヘルプ・コンテンツをナビゲートし、表示するためのWebブラウザのみです。処理は、OHW-UIXサーブレットを介してサーバー上で行われます。ヘルプ・コンテンツは1台のサーバーで管理され、任意の数のWebブラウザで表示されるため、数多くのユーザーがヘルプの単一のインストールにアクセスします。

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

- Oracle Help for the Web-UIXについて

- OHW-UIXユーザー・インタフェース

- OHW-UIXのデモ・ファイルのデプロイ

- OHW-UIXのデプロイの理解

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

- OHW-UIXヘルプ・システムのOHWヘルプ・システムへのアップグレード

D.1 Oracle Help for the Web-UIXについて

OHW-UIXは、Oracle Help for the Webの以前のバージョンです。新しいヘルプ・システムを作成する場合、OHW-UIXのかわりにOracle Help for the Webを使用してヘルプ・システムを作成することをお薦めします。オラクル社のADF UIXテクノロジを使用してアプリケーションを構築する場合は、OHW-UIXを使用する必要があります。

OHW-UIXに含まれているものは、次のとおりです。

- OHW-UIXサーブレット: OHW-UIXサーブレットはWebサーバーにインストールされ、Webブラウザからヘルプ・システムにアクセスする複数のユーザーにヘルプを提供します。OHW-UIXサーブレットのタスクは、次のとおりです。

- ヘルプセットの解析とマージ

- 検索の処理

- OHW-UIXユーザー・インタフェースの生成とユーザーのWebブラウザへのインタフェースの配信

- ユーザーのWebブラウザでOHW-UIXを介して表示するヘルプ・コンテンツの配信

OHW-UIXユーザー・インタフェースには、OHJのJavaユーザー・インタフェースで使用可能な機能がすべて含まれていますが、これらの機能は、ユーザーのブラウザでHTMLとしてレンダリングされます。機能には、目次、索引、テキスト検索などがあります。

ヘルプ・コンテンツ・ファイルおよび制御ファイル(OHJで使用されるのと同じHTMLファイルおよびXMLファイル)は、同じサーバーにサーブレットとして保存することも、様々な場所にある複数のサーバーに分散させることもできます。

- ドキュメント: ドキュメントにはこのマニュアルも含まれます。

D.2 OHW-UIXユーザー・インタフェース

Oracle Help for the Web-UIX (OHW-UIX)のユーザー・インタフェースは、Oracle Help for Java (OHJ)と同じ機能を提供します。ただし、OHW-UIXはWebアプリケーションであるため、外観および動作に若干の相違点があります。

Oracle ADF UIXテクノロジを使用してアプリケーションを構築する場合は、OHW-UIXのヘルプ・システムの使用をお薦めします。Oracle ADF UIXテクノロジを使用しない場合は、Oracle Help for the Web-Rich Clientのヘルプ・システムを使用する必要があります。詳細は、第3章「Oracle Help for the Webのユーザー・インタフェース」を参照してください。

図D-1 OHW-UIXユーザー・インタフェース

図D-1の番号付きコールアウトは、次のユーザー・インタフェース・コンポーネントを示しています。

1. ブランド領域: この領域には、テキスト、イメージまたはその両方を含めることができます。通常、この領域では、ヘルプ・コンテンツが特定されるか、または社名やロゴなどの会社情報が表示されます。

2. ヘルプセット・スイッチャ: ヘルプセットが複数ある場合に、それらのヘルプセットをマージするか、またはこのドロップダウンに個別に登録するかを指定できます。

3. タブ・バー: デフォルトのタブは、「目次」、「索引」、「検索」および「トピックの表示」です。

4. コンテンツ領域: タブを選択すると、そのタブに関連するコンテンツが、この領域に表示されます。

ブランド領域を除いて、これらの要素はヘルプセット・ファイルで構成されています。OHW-UIXおよびOHJは、ヘルプセット・ファイルを含め、まったく同じファイル形式を使用します。つまり、既存の制御ファイルを変更することなく、既存のOHJヘルプ・システムをOHW-UIXシステムとしてデプロイできます。OHW-UIXおよびOHJでは、ヘルプセット・ファイルの同じディレクティブを使用して、ユーザー・インタフェースを構築します。ヘルプ・システムをOHW-UIXシステムとしてデプロイするには、サーブレット・コンテナを構成してデプロイし、OHW-UIX構成ファイルを追加する必要があります。ブランド情報は、他の構成パラメータとともにこのファイル内に指定されます。

OHW-UIXシステムのデプロイの詳細は、第D.4項「OHW-UIXのデプロイの理解」を参照してください。

OHW-UIXのタブとOHJのタブの比較

OHW-UIXの標準タブ(ナビゲータとも呼ばれる)は、「目次」、「索引」、「検索」および「トピックの表示」になります。「目次」、「索引」および「検索」の各タブは、ヘルプセットのOHJナビゲーション・ウィンドウに表示される同じタブに相当します。「トピックの表示」タブは、OHJでのトピック・ウィンドウのかわりになるものです。OHW-UIXナビゲータは、現行ユーザーの状態を記憶します。つまり、あるタブから別のタブに切り替える場合や、トピックからの一連のリンクをたどる場合、前にアクセスしたタブにはそのコンテンツが保持されます。たとえば、「検索」タブで検索を実行し、検索で見つかったいずれかのトピックから複数のリンクをたどる場合、「検索」タブに戻ると、最新の検索条件や結果が表示されます。これは、ローカル・システム(OHJなど)上にあるアプリケーションにとって驚くような機能ではありませんが、アプリケーションがサーバー上で実行するWebアプリケーションにとっては重要な機能になります。この機能には、多くのリモート・ユーザーが同時にアクセスできます。次のトピックでは、OHJとの比較を含め、OHW-UIXユーザー・インタフェース要素について詳しく説明します。

- OHW-UIXの目次

- OHW-UIXの索引

- OHW-UIXの検索

- OHW-UIXのトピック

D.2.1 OHW-UIXの目次

目次(TOC)をツリーで表示するOHJとは対照的に、OHW-UIXのTOCでは、ヘルプ・システムの階層は一連のページで表示されます。各ページは階層の1つのノードを示します。そのページでは、トピックと子ノード(つまり、現在のノードの配下のノード)の両方をリスト表示できます。トピック・タイトルを選択すると、OHW-UIXは「トピックの表示」タブに切り替えられ、そのトピックのコンテンツが表示されます。「目次」タブでノードのタイトルをクリックすると、ページがリフレッシュされ、該当ノードのリストが表示されます。階層を移動すると、ナビゲーション証跡(ブレッドクラム)がページ上部に一連のリンクとして表示されます。これにより、階層の前のレベルにすばやく戻ることができます。

図D-2 OHW-UIXの「目次」ビュー

図D-3 ナビゲーション・リンク

D.2.2 OHW-UIXの索引

OHW-UIXのキーワード索引も、OHJのキーワード索引とは若干異なっています。OHJと同様、OHW-UIXの索引にも、「移動先」というラベルが付けられた、索引で見つける語句を入力するためのテキスト・フィールドがあります。ただし、OHJとは異なり、関連する語句が表示されるようにするには、「移動」を選択するか、または[Enter]キーを押す必要があります。OHW-UIXで一度に表示される項目は10個のみですが、「移動先」フィールドに入力した語句と一致する項目のリスト内を移動するためのコントロールも表示されます。「移動先」フィールドに何も入力しない場合は、キーワード・リスト全体での移動が可能です。

キーワード・リストから項目を選択すると、ページがリフレッシュされ、選択したキーワードに関連するトピックのリストが表示されます。このリストは、OHJの「索引」タブの下部に表示される、見つかったトピックのリストに相当します。このリストから項目を選択すると、タブが「トピックの表示」に切り替えられ、そのトピックが表示されます。

索引のトピックの対象ページの上部には、目次の項で説明したものと同様のナビゲーション・リンクが表示されます。ただし、このリンクを使用した場合、常に、キーワード・リストに戻ります。

図D-4 OHW-UIXの「索引」ビュー

D.2.3 OHW-UIXの検索

OHW-UIXのテキスト検索は、索引に似ています。「検索」テキスト・フィールドに単語または句を入力して[Enter]を押すと、関連するトピックのリストが表示されます。最初の10項目が表示され(リストはランクに応じてソートされます)、リストの他の項目にさらに移動できます。「拡張検索」モードでは、検索オプション(大/小文字の区別、すべての単語に一致する、いずれかの単語に一致する、など)を指定したり、ブール式を使用することもできます。

索引と同様、見つかったトピックのリストから項目を選択すると、「トピックの表示」タブにトピックが表示されます。

図D-5 OHW-UIXの「検索」ナビゲータ

図D-6 OHW-UIXの「拡張検索」ナビゲータ

D.2.4 OHW-UIXのトピック

OHW-UIXでは、トピックは、「トピックの表示」タブに表示されます。このナビゲータでは、トピックIDリンク、関連リンク、ポップアップなどのOHJのいくつかの特殊機能がサポートされています。OHJでは、これらの機能はICEbrowser表示エンジンによってサポートされています。OHW-UIXでは、これらの機能はどのブラウザでも動作します。これらの機能の詳細は、第7章「トピック・ファイル」を参照してください。

図D-7 OHW-UIXでのコンテンツ(トピック)の表示

「目次」でトピックを見つけるには、「目次に移動」をクリックします。トピックを印刷するには、「印刷可能ページ」をクリックします。ナビゲーション・タブ、ヘルプ・タイトルおよびヘルプセット・スイッチャなしで、新しい印刷可能ページが作成されます。

D.3 OHW-UIXのデモ・ファイルのデプロイ

この項では、OHW-UIXのデモ・ファイルをOracle WebLogic Serverにデプロイする方法について説明します。

OHW-UIXデモEARファイルには、デモの表示やリリースの試用を行う必要があるクラス・ライブラリが含まれています。また、サンプル・ヘルプセット、OHW-UIXサーブレット・ファイルおよびXML構成ファイルが含まれています。OHW-UIXインタフェースを体験するデモ・ファイルのデプロイや、既存のヘルプセットの交換および各自のヘルプセットの追加などを行えます。

次の項では、デモ・ファイルについて理解し、ユーザーの環境でサンプル・ヘルプセットをデプロイおよびテストを行ったり、オプションでデプロイおよびテスト用に独自のヘルプセットを追加する方法について説明します。

- 第D.3.1項「OHW-UIXのデモ・ファイルの理解」

- 第D.3.2項「Oracle WebLogic ServerでのOHW-UIXのデモEARファイルのインストール」

- 第D.3.3項「Oracle JDeveloperを使用したOHW-UIXのデモEARファイルのインストール」

- 第D.3.4項「OHW-UIXのデモEARファイルの実行」

D.3.1 OHW-UIXのデモ・ファイルの理解

OHW-UIXデモ・ファイルohw-uix-demo.earには、3つのOHW-UIXサンプル・ヘルプセットと、そのヘルプ・トピック、ヘルプセット・ファイルおよび制御ファイルが含まれています。また、OHW-UIXの構成に必要なohwconfig.xmlも含まれています。

OHWデモEARファイルによって、ohw-uix-demoディレクトリにファイルが解凍されます。解凍されたEARファイルにはohw-uix-demo.warファイルが含まれており、application.xmlファイルを含むMETA-INFディレクトリが作成されます。ohw-uix-demo.warの解凍後に作成されるohw-uix-demoディレクトリには、ヘルプセットのディレクトリが、それぞれのヘルプ・トピック、ヘルプセット・ファイルおよび制御ファイルとともに含まれます。

表D-1に、OHW-UIXのデモ・ファイルに含まれるファイルとディレクトリを示します。

表D-1 OHW-UIXのデモ・ファイル

ディレクトリの場所

説明

application.xml

Java EEアプリケーション: 簡単なOHW-UIXアプリケーションです。

このファイルは、META-INFディレクトリにあります。

helpsets

blafdoc、ohguideおよびサンプルのshakespeareの3つのヘルプセットがそれぞれのディレクトリに含まれるWebモジュール。

ヘルプセット・ディレクトリは、ohw-uix-demo.warファイルに存在します。

cabo

UIXのインストール可能なリソース・ファイルです。

caboディレクトリは、ohw-uix-demo.warファイルに存在します。

web.xml

OHW-UIXに影響する構成およびデプロイの情報が含まれます。

このファイルは、ohw-uix-demo.warファイルのWEB-INFディレクトリにあります。

ohwconfig.xml

OHW-UIX構成ファイルです。

このファイルは、helpsetsディレクトリにあります。

D.3.2 Oracle WebLogic ServerでのOHW-UIXのデモEARファイルのインストール

デモEARファイルのインストールは、非常に簡単なプロセスです。

1. OHW-UIXのデモEARファイルをOTNからダウンロードします。デモ・ファイルの名前は、ohw-uix-demo.earです。このファイルには、OHW-UIXおよびサンプル・ヘルプセットが含まれます。

2. Oracle WebLogic管理コンソールを起動し、「デプロイメント」ページに移動します。

3. 「デプロイメント」ページで、「インストール」をクリックしてデプロイ・ウィザードを起動します。

4. 「パス」フィールドにohw-uix-demo.earファイルの保存先を入力し、「次へ」をクリックします。

5. ターゲット指定スタイルの選択ページで、このデプロイメントをアプリケーションとしてインストールするを選択し、「次へ」をクリックします。

6. 「オプション設定」ページで設定を確認します。設定をデフォルトのままにしておくことをお薦めします。「次」をクリックして続行するか、「終了」をクリックしてデプロイメントを完了します。

7. 追加構成ページで、はい、デプロイメントの構成画面を表示しますを選択し、「終了」をクリックしてデプロイを完了します。
デプロイが成功すると、デプロイ・ウィザードの表示は、ohw-uix-demo.earの設定ページに戻ります。ファイルのデプロイ中にエラーが発生した場合は、「デプロイメント」ホームページが表示され、エラーが赤いテキストでリストされます。

D.3.3 Oracle JDeveloperを使用したOHW-UIXのデモEARファイルのインストール

Oracle JDeveloperにデモ・ファイルをインストールする手順は、次のとおりです。

1. OHW-UIXのデモEARファイルをOTNからダウンロードします。デモ・ファイルの名前は、ohw-uix-demo.earです。このファイルには、OHW-UIXおよびサンプル・ヘルプセットが含まれます。

2. JDeveloperを起動します。

3. ohw-uix-demo.earファイルから新規アプリケーションを作成します。「file」メニューから、「新」を選択します。「新規ギャラリ」ダイアログ・ボックスで、「General」カテゴリの下の「アプリケーション」を選択し、「項目」リストから「EARファイルからのアプリケーション」を選択します。

4. EARファイルからのアプリケーション作成ウィザードの場所ページで、ohw-uix-demo.earファイルを参照して選択します。また、アプリケーション名およびアプリケーションの場所を変更することもできます。「次へ」をクリックして、続行します。

5. ウィザードのEARモジュール・ページに、プロジェクト名およびモジュール名が表示されます。「次」をクリックして続行するか、または「終了」をクリックしてEARファイルからアプリケーションを作成します。

6. ウィザードの終了ページに、アプリケーションの設定の概要が表示されます。「終了」をクリックしてEARファイルからアプリケーションを作成します。JDeveloperによって、EARファイルからすべてのファイルが抽出され、編集およびデプロイ可能なアプリケーションが作成されます。

7. 「アプリケーション」ウィンドウで、プロジェクトを開き、目的のファイルを編集します。

8. アプリケーションをデプロイするには、統合されたOracle WebLogic Serverインスタンスを起動します。「実行」メニューから、「サーバー・インスタンスの起動」を選択して統合されたOracle WebLogic Serverを起動します。

9. 「アプリケーション」ウィンドウで、ohw-uix-demoプロジェクトを選択します。「アプリケーション」メニューから、「デプロイ」を選択します。サブメニューからohw-uix-demo→「デプロイ先」を選択し、IntegratedWLSConnectionを選択します。JDeveloperによってデプロイメント・プロセスが開始され、デプロイのステータスが「ログ」ウィンドウに反映されます。
アプリケーションが正常にデプロイされると、「ログ」ウィンドウに「---- デプロイが終了 ----」メッセージが表示されます。

D.3.4 OHW-UIXのデモEARファイルの実行

ohw-uix-demo.earのデプロイに成功すると、ブラウザが開いて次のURLが表示されます。

http://<yourHost>:<yourPort>/ohw-uix-demo/help/

次に例を示します。

Oracle WebLogic Serverをローカル・システムにインストールした場合は、次のURLを使用してデモ・ヘルプ・ファイルを開くことができます。

http://localhost:7101/ohw-uix-demo/help/

このURLは自動的にhttp://localhost:7101/ohw-uix-demo/help/state?navSetId=ohguide&navId=0&destination=に変更され、ヘルプの目次ビューが表示されます。OHW-UIXのユーザー・インタフェースの詳細は、第D.2項「OHW-UIXユーザー・インタフェース」を参照してください。

D.4 OHW-UIXのデプロイの理解

ヘルプ作成者は、任意のオーサリング・ツールを使用してヘルプ・コンテンツを作成します。ヘルプ作成者は、通常、ヘルプ・コンテンツをOHW-UIXヘルプ・システムとしてデプロイするために必要なOracle Help制御ファイルも作成します。OHW-UIX管理者は、一般的に、ヘルプセットのデプロイに必要なすべてのタスクを実行します。

ヘルプ作成者およびOHW-UIX管理者の両方とも、テストまたは本番用にデプロイすることがあるため、デモ・デプロイ・ファイルが提供されています。最新のデモ・ファイルは、OTNからダウンロードできます。

OHW-UIXに慣れていない場合は、デモ・ファイルohw-uix-demo.earのデプロイから開始できます。詳細は、第D.3.1項「OHW-UIXのデモ・ファイルの理解」を参照してください。デモEARファイルには、サンプル・ヘルプセットを即時にデプロイするためのファイルが含まれます。

OHW-UIXの新しいヘルプセットを作成する場合、次の各項で、OHW-UIXのデプロイメント・プロセスに役立つ情報と、OHW-UIXヘルプ・システムを作成してデプロイする手順を参照してください。

構成ファイルをすでに作成し、アプリケーション・サーバーを構成している場合を除いて、OHW-UIX管理者は、OHW-UIXヘルプ・システムをデプロイするために、次のタスクを実行する必要があります。

- 第D.4.1項「要件および依存性の検証」

- 第D.4.2項「OHW-UIX構成ファイルの理解」

- 第D.4.3項「OHW-UIXでのカスタム・ヘルプセットの表示の構成」

- 第D.4.4項「OHW-UIXのアクセスURLの変更」

- 第D.4.5項「OHW-UIXおよびUIXのアップグレード」

D.4.1 要件および依存性の検証

デプロイを開始する前に、すべての要件および依存性を検証します。

表D-2 OHW-UIXデプロイの最小要件

要件

説明

サーブレット・コンテナ

OHW-UIXには、JavaEE 1.5互換のアプリケーション・サーバーが必要です。Oracle WebLogic Server(スタンドアロンとしてまたはJDeveloperと統合して提供されている)では、構成作業を最小限に抑えることができるため、その使用をお薦めします。

クライアント

クライアントはHTMLのみを受信するため、必要となるのは、OHW-UIXヘルプ・コンテンツを表示して閲覧するためのWebブラウザのみです。WebブラウザのJavaScriptサポートは有効にする必要があります。

OHW-UIXは、Microsoft Internet Explorer 7、Microsoft Internet Explorer 8、Mozilla FireFox 2、Mozilla FireFox 3、Apple SafariおよびGoogle Chromeでサポートされます。

UIX

OHW-UIXはUIXアプリケーションです。

UNIXのみ: X Server

UNIXでは、動的イメージ生成が正常に行われるために、X Serverに接続するようにサーブレット・コンテナを構成する必要があります。

D.4.2 OHW-UIX構成ファイルの理解

OHW-UIXヘルプセットのデプロイを開始する前に、OHW-UIXを正しく構成するために変更の必要なファイルがあります。次に、XML構成ファイルの理解に役立つ情報を示します。

- application.xml: 指定のJava EEアプリケーションで実行するすべてのWebモジュールのマニフェスト。デプロイされる各製品のそれぞれのWebモジュールを指し示します。2つのインスタンスのapplication.xmlを使用することをお薦めします。

- UIXアプリケーション用の比較的安定したバージョン(任意)。

- Webモジュールが追加または再構成されるたびに、頻繁に変更されるOHW-UIXアプリケーション用のバージョン。

application.xmlの名前および場所は、Java EE標準によって固定されています。OHW-UIXでは、このファイルは<OHW-UIX_HOME>\META-INFディレクトリにある必要があります。

- web.xml: OHW-UIX構成ファイルの場所など、サーブレットの初期化パラメータを設定します。各Webモジュールに1つのweb.xmlインスタンスがあります。OHW-UIX構成ファイルが一定の方法で格納され、名前が付けられている場合、このファイルはすべてのOHW-UIXのWebモジュールに対して同じになります。このファイルは、<OHW-UIX_HOME>\<OHW-UIX_deployment_name>\WEB-INF\ディレクトリにある必要があります。

- ohwconfig.xml(デフォルトのファイル名): 表示するヘルプセットと、それらの表示方法を指定します。ロケール、ブランド情報およびその他各種設定も指定できます。構成ファイルの詳細は、第8章「Oracle Help for the Web構成ファイル」を参照してください。このファイルの名前と場所は、サーブレット初期化パラメータとして設定されます。このパラメータは、サーブレット・コンテナごとに個別に処理されます。このファイルは、<OHW-UIX_HOME>\<OHW-UIX_deployment_name>ディレクトリにある必要があります。

D.4.3 OHW-UIXでのカスタム・ヘルプセットの表示の構成

この項では、OHW-UIXヘルプ・システムで必要とされるディレクトリ構造の作成、カスタム・ヘルプセット・ファイルの正しい場所への追加、構成ファイルの作成と変更、およびアプリケーション・サーバーへのヘルプ・システムのデプロイに役立つ情報が提供されます。

この項の説明では、OHW-UIXのデモEARファイルがインストール済で、ユーザーがデモEARファイルのディレクトリ構造に精通していることを想定しています。まだデモ・ファイルがインストールされていない場合は、第D.3.1項「OHW-UIXのデモ・ファイルの理解」の手順に従ってインストールしてください。

OHW-UIXヘルプ・システムを設定する手順は、次のとおりです。

1. 次のようにディレクトリ構造を設定します。

<OHW-UIX_HOME>
|
— <OHW-UIX_deployment_name>
|
— cabo
— helpsets
|
— <custom_helpset_directory>
— META-INF
— WEB-INF
|
— lib
— META-INF

次に例を示します。

my_module
|
— my_module_help
|
— cabo
— helpsets
|
— my_ModuleHelpset
— META-INF
— WEB-INF
|
— lib
— META-INF

2. 独自のヘルプセット・ディレクトリを作成します。ヘルプセット・ファイル、トピック・ファイルおよび他の制御ファイル(索引、目次など)を含め、独自のヘルプ・ファイルをすべて<OHW-UIX_HOME>\<OHW-UIX_deployment_name>\helpsets\<custom_helpset_directory>ディレクトリの下に配置します。また、ヘルプセットにJARファイルを使用する場合は、JARファイルもここに配置します。JARファイルを作成したヘルプセットとJARファイルを作成していないヘルプセットを1つのデプロイで一緒に使用できます。

3. ohwconfig.xmlをohw-uix-demo\ohw-uix-demo\helpsetsディレクトリからコピーして、<OHW-UIX_HOME>\<OHW-UIX_deployment_name>\helpsetsディレクトリに保存します。その後、構成ファイルを更新および構成します。

1. 自分のヘルプセットにダイレクトするように<books></books>セクションを変更します。次に例を示します。

<books>
<helpSet id="myModule" location="my_ModuleHelpset/my_ModuleHelpset.hs" />
</books>

2. <books></books>セクションから、希望しないヘルプセットを削除します。削除されたヘルプセットは、OHW-UIXユーザー・インタフェースのヘルプセット・スイッチャのドロップダウン・リストに表示されなくなります。<books></books>セクション内に<helpSet>要素が1つしかない場合、ヘルプセット・スイッチャは使用できません。

3. <brandings></brandings>セクションを更新して、独自のブランドを表示します。次に例を示します。

<brandings>  <branding text="My Module" /></brandings>

4. caboファイルをohw-uix-demo\ohw-uix-demo\caboディレクトリから<OHW-UIX_HOME>\<OHW-UIX_deployment_name>\caboディレクトリへ、ライブラリ・ファイルをohw-uix-demo\ohw-uix-demo\WEB-INF\libディレクトリから<OHW-UIX_HOME>\<OHW-UIX_deployment_name>\WEB-INF\libディレクトリへ、それぞれコピーします。

5. uix-config.xmlをohw-uix-demo\ohw-uix-demo\WEB-INFディレクトリからコピーして、<OHW-UIX_HOME>\<OHW-UIX_deployment_name>\WEB-INFディレクトリに保存します。必要に応じてファイルを編集します。

6. web.xmlをohw-uix-demo\ohw-uix-demo\WEB-INFディレクトリからコピーして、<OHW-UIX_HOME>\<OHW-UIX_deployment_name>\WEB-INFディレクトリに保存します。次の手順で、必要に応じてファイルを編集します。

1. <display-name></<display-name>と<description></description>セクションを変更して、カスタム・ヘルプセット名を表示します。次に例を示します。

<web-app>
<display-name>My Module</display-name>
<description>My module help</description>
</web-app>

2. オプションで、<servlet>要素の下の<servlet-name>要素を編集して、OHW-UIXのアクセスに使用するURLを変更することもできます。アクセスURLの変更方法の詳細は、「OHW-UIXのアクセスURLの変更」を参照してください。

7. <OHW-UIX_deployment_name>ディレクトリをWARファイルに圧縮します。

8. application.xmlをohw-uix-demo\META-INFディレクトリからコピーして、<OHW-UIX_HOME>\META-INFディレクトリに保存します。必要に応じてファイルを編集します。このファイルで、デプロイする各製品のWebモジュール名を指定します。手順7で<web-uri></web-uri>要素内に作成したWARファイル名を指定します。アプリケーションのアクセスURLを変更する場合は、<context-root></context-root>要素を更新します。詳細は、第D.4.4項「OHW-UIXのアクセスURLの変更」を参照してください。

9. <OHW-UIX_HOME>ディレクトリをEARファイルに圧縮します。

10. Oracle WebLogic Serverを起動してEARファイルをデプロイします。Oracle WebLogic Serverがすでに実行されている場合は、サーブレットを最後に起動してから加えた変更が有効になるように、シャットダウンしてから再起動する必要があります。

11. ブラウザでhttp://<hostname>:<port>/<OHW-UIX_deployment_name>/help/を指定します。<hostname>は、OHW-UIXおよびOracle WebLogic Serverがインストールされているシステムの名前です。
デモ・ヘルプ・システムの最初のページがブラウザに表示されます。2つ以上のヘルプセットがある場合は、ツールバーのドロップダウン・リストを使用して1つのヘルプセットを選択し、ヘルプセット・スイッチャをクリックして、選択したヘルプセットのみの目次および索引を表示します。テキスト検索では、選択したヘルプセットの項目のみ検索されます。

D.4.4 OHW-UIXのアクセスURLの変更

OHW-UIXにアクセスするURLは、http://<hostname>:<port>/mymodule/help/です。<hostname>は、OHW-UIXおよびOracle WebLogic Serverがインストールされているマシンの名前です。

このURLは、次の方法で変更できます。

- アクセスURLの最後のURL要素の変更

- アクセスURLの名前の変更

D.4.4.1 アクセスURLの最後のURL要素の変更

URLの最後にあるhelpを変更するには、<OHW-UIX_HOME>\<OHW-UIX_deployment_name>\WEB-INFのweb.xmlを編集します。

<servlet-mapping>のパラメータである<url-pattern>に、OHW-UIXへのアクセスに使用するURLを指定します。たとえば、<url-pattern>を、デフォルトの/help/*から/onlinereference/*に変更した場合、OHW-UIXへのアクセスに使用するURLはhttp://<hostname>:<port>/mymodule/onlinereference/となります。

次に例を示します。

<servlet-mapping>
<servlet-name>mymodule</servlet-name>
<url-pattern>/onlinereference/*</url-pattern>
</servlet-mapping>

D.4.4.2 アクセスURLの名前の変更

アプリケーションのアクセスURLを変更するには、<OHW-UIX_HOME>\META-INFにあるapplication.xml内で、<web>要素の下の<context-root>要素エントリを編集します。

<web>
<web-uri>my_module.war</web-uri>
<context-root>my_module</context-root>
</web>

たとえば、OHW-UIXのアクセスURLをhttp://<hostname>:<port>/jdeveloper/help/にする場合は、ルート要素を次のように変更します。

<web>
<web-uri>my_module.war</web-uri>
<context-root>jdeveloper</context-root>
</web>

D.4.5 OHW-UIXおよびUIXのアップグレード

OHW-UIXおよびUIXの新規バージョンがリリースされた場合、OHW-UIXをアップグレードする前に、OHW-UIXおよびUIXのダウンロード・ページを参照して最新のダウンロードおよびインストール方法について確認してください。

- OHW-UIXを新規バージョンにアップグレードするには、WEB-INF/libディレクトリにあるOHW-UIXのJARファイルを置換する必要があります。

- UIXを新規バージョンにアップグレードするには、WEB-INF/libディレクトリにあるUIXのJARファイルを置換し、また、uix2-install.zipをcaboディレクトリに解凍することによって、UIXのインストール可能なリソース・ファイルを置換する必要があります。

アップグレードをテストするには、サーブレット・コンテナを再起動し、ブラウザでhttp://<hostname>:<port>/ohw-uix-demo/help/またはOHW-UIXアプリケーションをマップした場所を指定します。

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

Oracle Help for the Web-UIX (OHW-UIX)には、Webアプリケーションのユーザー・インタフェースの一部の状況に関連付けられたヘルプ・トピックを表示する、状況依存ヘルプ・メカニズムが備えられています。通常、ヘルプ・トピックは、Webアプリケーションの特定のページ、表または入力フィールドの機能について説明するために記述されています。「ヘルプ」ボタンを選択するなどして、ユーザー・インタフェース・コントロールのヘルプを要求すると、その状況(またはコントロール)に関連する適切なトピックが表示されます。

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

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

- 第D.5.1項「ヘルプ・トピックへのトピックIDのマップ」

- 第D.5.2項「ヘルプ・システムへの状況依存リンクの作成」

- 第D.5.3項「Oracle UIXベースのアプリケーションでの状況依存ヘルプの実装」

D.5.1 ヘルプ・トピックへのトピックIDのマップ

OHW-UIXの状況依存ヘルプ・システムには、ヘルプ・トピックHTMLファイルにトピックIDをマップする1つ以上のマップ・ファイルが必要となります。ヘルプセットでは、マップ・ファイルは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属性はオプションであり、トピックを表示するウィンドウ・タイプの名前を指定します。マップ・ファイルで使用される要素の詳細は、第12.3.2項「OHJDKリリースの内容」を参照してください。

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

状況依存ヘルプの実装にOHW-UIXを使用するアプリケーションは、OHW-UIXサーブレットへの特別な形式のURLを使用して状況依存トピックを要求します。宛先URL(リンク、イメージなど)を持つすべてのユーザー・インタフェース・コントロールを、状況依存トピックに関連付けることができます。

状況依存ヘルプ用のOHW-UIXへのリンクを作成するには、フロント・ページ(「目次」、「索引」および「検索」ナビゲータを含む)の宛先URLを使用するか、またはトピックIDを使用してトピックの宛先URLを作成できます。また、宛先URLにロケールを指定することもできます。

- 第D.5.2.1項「フロント・ページへのリンク」

- 第D.5.2.2項「トピックへのリンク」

- 第D.5.2.3項「ロケールの指定」

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

フロント・ページのURLは、次のように、単にOHW-UIXサーブレットのURLとなります。

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

<server>はサーブレット・コンテナを実行するサーバーの名前、<port>はサーブレット・コンテナが使用するポート、および<servlet mapping>はOHW-UIXサーブレット用のweb.xmlファイル(デフォルトの場所はohw-uix/help/)に設定されているサーブレット・マッピングです。次に例を示します。

http://www.yourcompany.com:7101/ohw-uix/help/

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

D.5.2.2 トピックへのリンク

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

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

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

http://www.yourcompany.com:7101/ohw-uix/help/?topic=topic_1

OHW-UIXへの状況依存リンクを実装するときに、アプリケーションのメイン・ページを置き換えるのではなく、JavaScriptを使用して2次ウィンドウにリンク先が表示されるようにする場合があります。

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

D.5.2.3 ロケールの指定

トピック・ページまたはフロント・ページなどのOHW-UIXページへのリンクを作成する場合は、locale問合せパラメータを使用して、OHW-UIXサーブレットのURLにロケールを含めることができます。

トピックの構文は、次のとおりです。

http://<server>:<port>/<servlet-mapping>/?topic=<topic-id>&locale=<ISO-code>

フロント・ページの構文は、次のとおりです。

http://<server>:<port>/<servlet-mapping>/help?locale=<ISO-code>

ロケールを指定した場合、OHW-UIXは、ローカライズ済ヘルプセット(使用可能な場合)に切り替えられ、指定したロケールが上書きまたは削除されるまで引き続きそのロケールが使用されます。指定したローカライズ済ヘルプセットがない場合、このパラメータは無視されます。

次に例を示します。

http://www.yourcompany.com:7101/ohw-uix/help/?topic=topic_1&locale=sp

ロケールの詳細は、第8章「Oracle Help for the Web構成ファイル」を参照してください。

D.5.3 Oracle UIXベースのアプリケーションでの状況依存ヘルプの実装

UIXは、Webアプリケーションを作成するためのオラクル社のテクノロジです。UIXには、OHW-UIXを使用して状況依存ヘルプを簡単に実装できるメカニズムが備えられています。UIXでは、状況依存ヘルプをUIX Java APIを使用してプログラム的に実装するか、またはUIX言語(XML言語の1つ)を使用して宣言的に実装できます。

注意:
UIXは、現行リリースのJDeveloperに付属していませんが、UIXを使用する場合は、OTNのアーカイブからJDeveloper 10.1.2以前のリリースをダウンロードします。uix-config.xmlファイルの詳細は、JDeveloperオンライン・ヘルプで入手できます。

UIXのHelpProviderアーキテクチャには、汎用的な状況依存ヘルプ・メカニズムが備えられています。OHW-UIXでは、OracleHelpProviderと呼ばれる固有のHelpProviderを実装することによって、UIXアプリケーションに状況依存ヘルプを提供します。

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

D.5.3.1 OracleHelpProviderへのOHW-UIXの登録

OracleHelpProviderを使用する際の最初の手順として、OracleHelpProviderインスタンス(OHW-UIXなど)をUIX構成オブジェクトに登録します。UIXでは、HelpProviderは、データバインディングに使用できる特殊なUIX DataProviderとして表示されます。これは、UIXページで宣言する必要がないという点で特殊です。HelpProviderを構成オブジェクトに登録すると、すべてのページで利用できます。

UIXでは、uix-config.xmlファイルおよびApplicationConfiguration APIを使用して、コードを1行も記述することなく構成オブジェクトのセットを作成でき、フィールドの構成プロパティを更新する場合もコードの再コンパイルが必要ありません。

OHW-UIXをアプリケーションに登録するには、UIXがOHW-UIXサーブレットのインスタンスを指すように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:7101/ohw-uix</ohw-servlet-url>
</help-provider>

</default-configuration>

...
</configurations>

<help-provider>要素を使用すると、ヘルプ・プロバイダを構成できます。現在サポートされている構文は、含まれている<ohw-servlet-url>要素のみです。ohw-servlet-urlには、OHW-UIXのインストール先を指すURLを含める必要があります。このプロパティを設定した後、すべてのuiXMLページおよびUIX Javaページから、ui:helpTopicsおよびui:helpSystemという2つのデータ・プロバイダにアクセスできます。

UIXで、構成オブジェクトの作成にJavaコードの使用が必要であるものの、uix-config.xmlファイルに定義されているデフォルトのプロパティを使用する場合は、次のコードを使用します。

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

UIXで、OHWをアプリケーションにプログラム的に登録するには、次のサンプル・コードを参照してください。

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:7101/ohw-uix/help/")
cfg.setProperty(Configuration.HELP_PROVIDER, provider);
return cfg;
}

HelpProviderでは、2つの特別なデータ・オブジェクト(UIX UIコンポーネントの名前空間にあるhelpTopicsおよびhelpSystem)が設定されます。

D.5.3.2 リンク先のデータ・バインディング

HelpProviderでは、2つのデータ・プロバイダ(ui:helpTopicsおよびui:helpSystem)が設定されます。uiはUIX UI名前空間の接頭辞として使用されます。これらは、ヘルプ・システムへの接続元とするリンクまたはボタン(リンク先を持つすべてのコントロール)のdestination属性をデータ・バインディングする場合に使用されます。

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

フロント・ページのリンク先のデータ・バインディング

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

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

ユーザーがフロント・ページにリンクされたユーザー・インタフェース・コントロールのヘルプを要求すると、ユーザーのブラウザにOHW-UIXが表示され、ヘルプ・システムの最初のページが表示されます。

注意:
ヘルプ・システムの最初のページは、.hsファイルに宣言された最初のナビゲータおよびOHW-UIX構成ファイル(ohwconfig.xml、またはサーブレットのconfigFileName初期化パラメータによって指定されている別のファイル名)に定義されている最初のブックとして定義されます。最初のブックの最初のナビゲータは、通常、目次です。

トピックのリンク先のデータ・バインディング

トピックを表示するには、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が含まれるリンク先が自動的に返されます。ユーザーがメイン・ページにアクセスする場合は、このウィンドウに含まれるヘルプ・システムのフロント・ページへのリンクを使用できます。

D.6 OHW-UIXヘルプ・システムのOHWヘルプ・システムへのアップグレード

OHW-UIXからOHWにアップグレードする場合、ヘルプセット・コンテンツの変更は不要ですが、OHWを使用するために、次の2つの操作を実行する必要があります。

- OHWのjarファイルを、WEB-INF/libディレクトリにコピーします。

- WEB-INF/ディレクトリにあるweb.xmlファイルを変更します。このためには、OHWのデモ・バンドルからweb.xmlを取り出し、サーブレットとリソースの定義およびマッピングをコピーする方法が最適です。

OHWのweb.xmlには、3つの主要部分があります。

- JSF TrinidadおよびADF RC (Facesサーブレット、Trinidadサーブレットおよびフィルタなど)の基本構成

<context-param>
<param-name>javax.faces.STATE_SAVING_METHOD</param-name>
<param-value>client</param-value>
</context-param>

<filter>
<filter-name>trinidad</filter-name>
<filter-class>org.apache.myfaces.trinidad.webapp.TrinidadFilter</filter-class>
</filter>

<filter-mapping>
<filter-name>trinidad</filter-name>
<servlet-name>Faces Servlet</servlet-name>
</filter-mapping>

<servlet>
<servlet-name>Faces Servlet</servlet-name>
<servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>

<servlet-mapping>
<servlet-name>Faces Servlet</servlet-name>
<url-pattern>/faces/*</url-pattern>
</servlet-mapping>

<servlet>
<servlet-name>resources</servlet-name>
<servlet-class>org.apache.myfaces.trinidad.webapp.ResourceServlet</servlet-class>
</servlet>

<servlet-mapping>
<servlet-name>resources</servlet-name>
<url-pattern>/adf/*</url-pattern>
</servlet-mapping>

<servlet-mapping>
<servlet-name>resources</servlet-name>
<url-pattern>/afr/*</url-pattern>
</servlet-mapping>

<servlet-mapping>
<servlet-name>resources</servlet-name>
<url-pattern>/ohr/*</url-pattern>
</servlet-mapping>

- OHWの基本構成:
OHWのフィルタを定義し、そのフィルタをFacesサーブレットにマップする必要があります。

<filter>
<filter-name>OHWRCFRequestFilter</filter-name>
<filter-class>oracle.help.web.rich.OHWFilter</filter-class>
</filter>

<filter-mapping>
<filter-name>OHWRCFRequestFilter</filter-name>
<servlet-name>Faces Servlet</servlet-name>
</filter-mapping>

- OHW-UIXサーブレット定義およびサーブレット・マッピング
既存のOHW-UIXのサーブレット定義は、OHWのクラスoracle.help.web.rich.OHWServletを使用するように変更が必要です。次に、既存のOHWサーブレット定義を変更する手順を説明します。

1. OHW-UIXサーブレット・インスタンス用のohw-config.xmlの場所を指定するために、OHW-UIXサーブレットに、ohwConfigFileURLという名前の<init-param>を定義します。

2. OHW-UIXサーブレットにURLマッピングを定義します。既存のサーブレット・マッピングを変更する必要はありません。

3. <load-on-startup>パラメータを指定します。

OHWでは、1つのWebアプリケーションで複数のOHWインスタンスをサポートします。次に、2つのOHWインスタンスをデプロイするweb.xmlの例を示します。

<!-- configuration for product1 help front servlet -->
<servlet>
<servlet-name>product1</servlet-name>
<servlet-class>oracle.help.web.rich.OHWServlet</servlet-class>
<init-param>
<param-name>ohwConfigFileURL</param-name>
<param-value>/helpsets/product1/ohwconfig.xml</param-value>
</init-param>
<load-on-startup>2</load-on-startup>
</servlet>

<servlet-mapping>
<servlet-name>resources</servlet-name>
<url-pattern>/ohr/*</url-pattern>
</servlet-mapping>

<!-- configuration for product1 help front servlet -->
<servlet>
<servlet-name>product2</servlet-name>
<servlet-class>oracle.help.web.rich.OHWServlet</servlet-class>
<init-param>
<param-name>ohwConfigFileURL</param-name>
<param-value>/helpsets/product2/ohwconfig.xml</param-value>
</init-param>
<load-on-startup>3</load-on-startup>
</servlet>

<servlet-mapping>
<servlet-name>product1</servlet-name>
<url-pattern>/product1/*</url-pattern>
</servlet-mapping>

<servlet-mapping>
<servlet-name>product2</servlet-name>
<url-pattern>/product2/*</url-pattern>
</servlet-mapping>