Oracle® Fusion Middleware Oracle Fusion Middleware Oracle Help開発者ガイド

11gリリース2 (11.1.2.4.0)

B71911-02(原本部品番号:E16280-05)

目次

図一覧

表一覧

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

はじめに

- 対象読者

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

- 関連ドキュメント

- 表記規則

新機能

第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 動的マッピングの最適化

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 埋込みヘルプを含むヘルプセットの事前ロード

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

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-RCのアクセスURLの変更

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

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

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

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

- 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-RCの登録

- 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-RCヘルプ・システムへのアップグレード

図一覧

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

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

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

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

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

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

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

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

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

- 2-10 マージの結果

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

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

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

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

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

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

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

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

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

- 10-1 OHJオーサリング・ウィザード: ようこそ

- 10-2 OHJオーサリング・ウィザード: ヘルプセット・ファイル

- 10-3 OHJオーサリング・ウィザード: ソースとターゲットの選択

- 10-4 OHJオーサリング・ウィザード: ディレクトリの指定

- 10-5 OHJオーサリング・ウィザード: ビューの定義

- 10-6 OHJオーサリング・ウィザード: 新しいビューの定義

- 10-7 OHJオーサリング・ウィザード: カスタム・ビュー・タイプの定義

- 10-8 OHJオーサリング・ウィザード: カスタム・データ・エンジンの定義

- 10-9 OHJオーサリング・ウィザード: 全文検索ビュー

- 10-10 OHJオーサリング・ウィザード: 全文検索ビュー

- 10-11 OHJオーサリング・ウィザード: 関連リンク

- 10-12 OHJオーサリング・ウィザード: ポップアップ・ウィンドウ

- 10-13 OHJオーサリング・ウィザード: ウィンドウ・タイプの定義

- 10-14 OHJオーサリング・ウィザード: ウィンドウ・タイプの識別情報のプロパティ

- 10-15 OHJオーサリング・ウィザード: ウィンドウ・タイプの配置のプロパティ

- 10-16 OHJオーサリング・ウィザード: ウィンドウ・タイプのスタイルのプロパティ

- 10-17 OHJオーサリング・ウィザード: ウィンドウ・タイプのツールバー・ボタンのプロパティ

- 10-18 OHJオーサリング・ウィザード: ヘルプセットの作成

- 19-1 ADF Facesアプリケーションのヘルプ・アイコン

- 19-2 HelpTopicId属性

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

- D-2 OHW-UIXの「目次」ビュー

- D-3 ナビゲーション・リンク

- D-4 OHW-UIXの「索引」ビュー

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

- D-6 OHW-UIXの「拡張検索」ナビゲータ

- D-7 OHW-UIXでのコンテンツ(トピック)の表示

表一覧

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

- 5-1 <maps>の子要素

- 5-2 <wintype>の子要素

- 5-3 <links>の子要素

- 5-4 <view>の子要素

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

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

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

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

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

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

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

- 8-1 <brandings>の子要素

- 8-2 <locales>の子要素

- 8-3 <books>の子要素

- 8-4 <parameters>の子要素

- 8-5 <parameters>キーワード子要素

- 8-6 <parameters>パフォーマンス子要素

- 8-7 preloadの値の動作

- 12-1 OHJのバイナリ

- 12-2 OHJのオーサリング・ツール

- 12-3 OHJのデモンストレーションJARファイル

- 12-4 OHJのデモンストレーション・ファイル

- 12-5 OHJのドキュメント

- 13-1 Help()コンストラクタ

- 13-2 HelpSet()コンストラクタ

- 13-3 addBook()コンストラクタ

- 13-4 showNavigatorWindow()コンストラクタ

- 13-5 showTopic()コンストラクタ

- 13-6 dispose()コンストラクタ

- 14-1 CSHManager()コンストラクタ

- 14-2 setDefaultBook()コンストラクタ

- 14-3 addComponent()コンストラクタ

- 14-4 showHelpForComponent()メソッド

- 16-1 OHWのデモ・ファイルおよびディレクトリ

- 17-1 OHWデプロイの最小要件

- A-1 ヘルプセット・ファイルの要素

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

- A-3 目次ファイルの要素

- A-4 索引ファイルの要素

- B-1 registerClientWindow()メソッド

- B-2 unregisterClientWindow()メソッド

- C-1 HelpBook()コンストラクタ

- C-2 addBook()コンストラクタ

- C-3 <books>の子要素

- D-1 OHW-UIXのデモ・ファイル

- D-2 OHW-UIXデプロイの最小要件

Oracle® Fusion Middleware

Oracle Fusion Middleware Oracle Help開発者ガイド

11gリリース2 (11.1.2.4.0)

B71911-02(原本部品番号:E16280-05)

2013年3月

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

Oracle Fusion Middleware Oracle Help開発者ガイド, 11g リリース2 (11.1.2.4.0)

B71911-02

Copyright © 2002, 2013, Oracle and/or its affiliates.All rights reserved.

原本著者: Himanshu Marathe

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

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

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

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 Fusion Middleware Oracle Help開発者ガイドでは、Oracle Helpを使用して、JavaアプリケーションおよびWebアプリケーションのHTMLに基づくヘルプ・システムを開発、表示する方法について説明します。

対象読者

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

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

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

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、サンプル内のコード、画面に表示されるテキスト、または入力するテキストを示します。

新機能

Oracle Helpリリース11.1.2.4.0には、アプリケーション用のヘルプ・システムを作成および管理するために役立つ多数の機能が組み込まれています。現行リリースのOracle Helpには、Oracle Help for Java、Oracle Help for the Web – Rich Client、およびOracle Help for the Web – UIXが含まれています。また、Oracle Helpは、Oracle Fusion Middleware 11gリリース2 (11.1.2.4.0)もサポートしています。

- Oracle Help for Javaの目次でのカスタム・アイコンのサポート

- 検索文字列内でのワイルドカード文字(*)のサポート

- 各種ブックに含まれる子目次の構造を制御する、マスター目次のサポート

第I部

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ベースのヘルプシステムを開発し、表示する方法の概要についても説明します。

この章の構成は、次のとおりです。

- 第1.1項「Oracle Helpについて」

- 第1.2項「Oracle Help for Java」

- 第1.3項「Oracle Help for Web」

- 第1.4項「Oracle JDeveloperのOracle Help」

- 第1.5項「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と表記します。説明内容がOracle Help for Javaにのみ該当する場合は、OHJと表記します。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は、Web環境にHTMLベースのヘルプ・コンテンツを配信します。Oracle Help for the Webは、その充実したインタフェースから、Oracle Help for the Web – Rich Client (OHW-RC)とも呼ばれます。これは、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構文をサポートできるようになります。また、1つの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のユーザー・インタフェース・コンポーネントについて説明します。このコンポーネントには、ナビゲータ・ウィンドウ、トピック・ウィンドウ、索引タブ、検索タブ、お気に入りタブなどがあります。

この章の構成は、次のとおりです。

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

- 第2.2項「OHJのトピック・ウィンドウ」

- 第2.3項「OHJのナビゲータ・ウィンドウ」

- 第2.4項「ヘルプセットのマージ」

- 第2.5項「その他のOHJ機能」

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

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

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

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

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

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

「図2-2 ドッキングされたウィンドウ」の説明

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

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

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

「図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-4 ナビゲータ・ウィンドウの「目次」タブ」の説明

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

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

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

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

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

2.3.2 「索引」タブ

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

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

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

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

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

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

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

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

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

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

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

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

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

2.3.3 「検索」タブ

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

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

「図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 ナビゲータ・ウィンドウの「お気に入り」タブ

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

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

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

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

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

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

注意:

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

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

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

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

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

2.4 ヘルプセットのマージ

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

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

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

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

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

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

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

「図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ガイドの他の箇所では触れられていない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)ファイルにカプセル化して圧縮できます。ヘルプ・システムを実行するときにこれらのファイルを解凍する必要はありません。

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

この章では、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.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 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 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の「目次」ナビゲータ

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

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

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

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

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

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

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

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

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

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

注意:

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

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

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

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

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

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

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

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

3. 展開/縮小: このボタンをクリックすると、キーワード・リストおよび「キーワードに移動」テキスト・フィールドが非表示になり、トピックのリストが拡大されて「索引」ナビゲータ全体に表示されます。このボタンは、検索キーワードのトピックのリストがあり、そのリスト内を参照する場合に役立ちます。

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

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

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

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

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

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

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

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

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

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

5. 展開/縮小: このボタンをクリックすると、検索テキスト、ソース、検索オプションおよび「大/小文字の区別」フィールドを非表示にし、トピックのリストを拡大して「検索」ナビゲータ全体に表示します。このボタンは、検索キーワードのトピックのリストがあり、そのリスト内を参照する場合に役立ちます。

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

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

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

注意:

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

3.6 OHWのトピック・ペイン

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

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

「図3-6 OHW-RCのトピック・ペイン」の説明

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

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

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

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

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

3.7 その他のOHW機能

このOracle Helpガイドの他の箇所では触れられていない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 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)で使用する、各種のファイル形式(メタデータ・ファイル、情報ファイル、トピック・ファイルなど)について説明します。

この章の構成は、次のとおりです。

- 第4.1項「Oracle Helpのファイル形式について」

- 第4.2項「ファイル名の拡張子」

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

Oracle Help for Java (OHJ)およびOracle Help for the Web (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項「メタデータ・ファイルについて」

- 第5.2項「ヘルプセット・ファイル」

- 第5.3項「マップ・ファイル」

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

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

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

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

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

- 第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>要素は、トピックIDをトピック・ファイルにマップするために使用される1つ以上のマップ・ファイルをポイントします。<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クラスが含まれています。各ビュー・タイプは、それぞれ固有のアコーディオン・パネルに表示されます。デフォルトのパネルは、「目次」、「索引」および「検索」パネルです。

ヘルプセットには、各タイプのビューを複数含めることができます。つまり、複数の「目次」タブや「索引」タブなどをユーザー・インタフェースに表示できます。また、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形式に基づく)、Microsoft 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に関連付けられいているトピックが、ヘルプセットに定義されているデフォルト・ウィンドウに表示されます。この属性は、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コンテンツが表示されます。

<?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を使用できます。この情報をマップ・ファイル内に保持することによって、このマップ・ファイルを、これらの割当てを管理するための集中リポジトリにすることができます。

6 ヘルプ情報ファイル

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

この章の構成は、次のとおりです。

- 第6.1項「ヘルプ情報ファイルについて」

- 第6.2項「目次ファイル」

- 第6.3項「マスター目次」

- 第6.4項「索引ファイル」

- 第6.5項「検索索引ファイル」

- 第6.6項「リンク・ファイル」

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は、マップ・ファイルに保持されます。親ノード(階層で、自身の下に他の項目を含む項目)には、ターゲットが含まれる場合と含まれない場合があります。ノードにターゲットが含まれていないときに、そのノードを選択すると、そのノードの子項目および子ノードが表示されます。

- 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と関連リンク、ポップアップ、ウィンドウ・タイプおよびカスタム・プロトコル・リンクについて説明します。

この章の構成は、次のとおりです。

- 第7.1項「トピック・ファイルについて」

- 第7.2項「トピックIDリンク」

- 第7.3項「関連リンク」

- 第7.4項「カスタム・プロトコル・リンク」

- 第7.5項「ポップアップ」

- 第7.6項「トピックID」

- 第7.7項「ウィンドウ・タイプ」

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

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

OHJ付属のHTML表示コンポーネントは、ICEsoft Technologies社のICEbrowserをオラクル社用に変更したものです。バージョン5.01以上のICEbrowserはHTML 4.0標準に準拠しており、表やフレームの表示およびアプレットの実行が可能です。ただし、標準のICEbrowserは、フル機能のヘルプ・システムで重要となるいくつかの機能をサポートしていません。そのためオラクル社は、ICEsoft Technologies社から供与されたライセンスのもと、オラクル社が開発した規則をサポートするように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を渡します。

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 ウィンドウ・タイプ

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

注意:

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

ヘルプセット・オーサリング・ウィザードを使用する場合は、トピック・ファイル内に含まれるトピックにウィンドウ・タイプを関連付けできますが、それと同時にトピックのtopic-id METAタグでトピックIDも指定する必要があります。OHJオーサリング・ウィザードでは、両方の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を設定しなくてもヘルプ・システムは破損しませんが、パフォーマンスは低下します。

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

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

この章の構成は、次のとおりです。

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

- 第8.2項「<helpConfiguration>要素」

- 第8.3項「<brandings>要素」

- 第8.4項「<locales>要素」

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

- 第8.6項「<parameters>要素」

- 第8.7項「<navigatorAliases>要素」

- 第8.8項「カスタム・プロトコル・リンク」

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

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の検出に成功します。したがって、より限定的なロケール(nl_NL)をOHWに指定し、より広範なロケール(nl)をブラウザに設定すると、この指定は無視されます。これは、リソース・バンドルなどの他の標準的なロケール・メカニズムと同様です。

<brandingFromResource>

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

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

- textKey: ResourceBundleへのブランド・テキストのキー。

- imageSourceKey: ResourceBundleへのブランド・テキストのキー。この属性とtextKeyが設定されている場合は、この属性が優先されます。

- imageShortDescKey: ResourceBundleへのブランド・イメージの説明のキー。このテキストは、HTMLでのalt説明の処理方法と同じ方法で表示されます。たとえば、イメージの上にマウス・ポインタを置くとこのテキストが表示されます。

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

OHWでは、使用ロケールが絞り込まれることはありますが、拡大されることはありません。たとえば、ロケールnlを指定している場合に、ブラウザの使用ロケールがnl_NLに設定されているとします。この場合、OHWはまずnl_NLの検索に失敗し、その後nlの検出に成功します。したがって、より限定的なロケール(nl_NL)をOHWに指定し、より広範なロケール(nl)をブラウザに設定すると、この指定は無視されます。これは、リソース・バンドルなどの他の標準的なロケール・メカニズムと同様です。

例:

<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>タグがサポートされています。<locale>タグは、ロケールに依存する操作に対応するJavaロケールを構成するために使用されるISO言語、国および(オプションの)バリアント・コードを指定します。また、Oracle Help制御ファイルのキャラクタ・セット・エンコーディングのJavaでサポートされるエンコーディング名(ISO8859_1など)を指定します。リストされる最初の<locale>要素がデフォルト・ロケールとなります。

OHWでは、ヘルプセットは別の方法でロードされます。RCFアプリケーションとしてのOHW-RCでは、ヘルプセット内の単一ファイル内に指定されたDefinition Textコンテンツとともに、50のコンポーネントが画面に表示されることがあります。すべてのヘルプセットがロードされないようにして、ユーザーが画面を開いたときにヘルプセットのロードにより発生するラグを削減するには、選択したヘルプセットの事前ロードを有効にします。

このため、OHW-RCの場合、構成ファイルでは、<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>

第III部

Oracle Helpのオーサリング

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

- 第9章「Oracle Helpシステムのオーサリング」
この章では、Oracle Helpのオーサリングを紹介します。

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

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

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

この章では、Oracle Helpシステムのオーサリング・ユーティリティとプロセスについて説明します。

この項の構成は、次のとおりです。

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

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

- 第9.3項「埋込みヘルプのオーサリング」

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-RCの埋込みヘルプ機能の一部として、アプリケーションの各コンポーネントに複数のレベルのヘルプを関連付け、各レベルが特定のユーザー動作によってトリガーされるようにできます。ヘルプのレベルは次のとおりです。

- 定義テキスト

- 方法テキスト

- フル・ヘルプ

どのレベルとも、どのような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ファイル

HTML本文には、定義テキストおよび方法テキストの<div>タグがあります。この両方のレベルのヘルプのコンテンツは同じファイル内に指定する必要があります。同じファイル内にいずれかが指定されていない場合、コンテンツは未定義とみなされます。

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 ヘルプセット・オーサリング・ウィザード

この章では、ヘルプセット・オーサリング・ウィザードと、その各種画面について説明します。また、このウィザードを使用して、ヘルプ・システムを作成する方法についても説明します。

この章の構成は、次のとおりです。

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

- 第10.2項「ウィザードの起動」

- 第10.3項「ヘルプセット・ファイルの作成」

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

- 第10.5項「ソース・ディレクトリの指定」

- 第10.6項「ビューの定義」

- 第10.7項「全文検索ビューの定義」

- 第10.8項「マップ・ファイルの定義」

- 第10.9項「関連リンクの変換」

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

- 第10.11項「ウィンドウ・タイプの定義」

- 第10.12項「ヘルプセットの作成」

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-1 OHJオーサリング・ウィザード: ようこそ」の説明

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

OHJオーサリング・ウィザードの最初の手順では、ヘルプセット(.hs)ファイルを作成します。また、後で既存のヘルプセット・ファイルを開いて編集することもできます。ヘルプセットの詳細は、第5.2項「ヘルプセット・ファイル」を参照してください。

図10-2 OHJオーサリング・ウィザード: ヘルプセット・ファイル

「図10-2 OHJオーサリング・ウィザード: ヘルプセット・ファイル」の説明

次の情報を使用して、ヘルプセット・ファイル・ページの各フィールドにデータを入力します。

フィールド

説明

新しいOracle Help for Javaヘルプセット・ファイルを作成する

このオプションは、ヘルプセット・ファイルを作成する場合に選択します。

既存のOracle Help for Javaヘルプセット・ファイルを開く

このオプションは、既存のヘルプセット・ファイルを編集する場合に選択します。

ファイル

参照をクリックして、編集するヘルプセット・ファイルを選択します。

完了した後、次へをクリックして続行します。

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

OHJオーサリング・ウィザードのソースとターゲットの選択ページでは、オーサリング・ツールと、ヘルプ・ファイルの表示に使用するブラウザを選択できます。

図10-3 OHJオーサリング・ウィザード: ソースとターゲットの選択

「図10-3 OHJオーサリング・ウィザード: ソースとターゲットの選択」の説明

次の情報を使用して、ソースとターゲットの選択ページの各フィールドにデータを入力します。

フィールド

説明

オーサリング・ツールを選択する

ヘルプ・ファイルの作成に使用するオーサリング・ツールを選択します。

HTMLブラウザを選択する

HTMLファイルの表示に使用するブラウザを選択します。

完了した後、次へをクリックして続行します。

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

OHJオーサリング・ウィザードのディレクトリの指定ページでは、HTMLファイルやその他の制御ファイルを格納するディレクトリを選択できます。

図10-4 OHJオーサリング・ウィザード: ディレクトリの指定

「図10-4 OHJオーサリング・ウィザード: ディレクトリの指定」の説明

次の情報を使用して、ディレクトリの指定ページの各フィールドにデータを入力します。

フィールド

説明

ディレクトリ

参照をクリックし、HTMLファイルのソース・ディレクトリを選択します。既存のヘルプセット・ファイルを指定した場合は、このフィールドは編集できず、ヘルプセット・ファイルのディレクトリの場所が表示されます。

サブディレクトリを含める

このチェック・ボックスを選択すると、ディレクトリで選択したディレクトリのサブディレクトリが含められます。

ヘルプセット・タイトル

ヘルプセット・ファイルのタイトルを指定します。

完了した後、次へをクリックして続行します。

10.6 ビューの定義

OHJオーサリング・ウィザードのビューの定義ページでは、OHJヘルプ・ナビゲータ・ウィンドウのビューを定義できます。目次やキーワードの索引のビューを作成したり、カスタム・ビューを定義します。

図10-5 OHJオーサリング・ウィザード: ビューの定義

「図10-5 OHJオーサリング・ウィザード: ビューの定義」の説明

フィールド

説明

新規

新しいビューを作成し、そのビューの名前を現在のビューリストに追加します。

削除

選択したビューを現在のビューリストから削除します。

完了した後、次へをクリックして続行します。

10.6.1 新しいビューの定義

OHJオーサリング・ウィザードでは、ヘルプに複数のビューを作成できます。デフォルトでは、ビューは定義されません。新しいビューを定義するには、新規をクリックします。図10-6は、新しいビューの作成時に、ウィザードのビューの定義ページで使用できるフィールドを示します。

図10-6 OHJオーサリング・ウィザード: 新しいビューの定義

「図10-6 OHJオーサリング・ウィザード: 新しいビューの定義」の説明

次の情報を使用して、ビューの定義ページの各フィールドにデータを入力します。

フィールド

説明

ビュー・タイプ

定義される新しいビューのビュー・タイプを選択します。ビュー・タイプとしてOHJ TOCナビゲータ、OHJキーボード・ナビゲータまたはOHJ検索ナビゲータを選択するか、カスタム・ナビゲータを定義します。

データ・エンジン

新しいビューのデータ・エンジンを選択します。エンジンとしてHHCエンジン、HHKエンジン、XML TOCエンジン、XML索引エンジン、TOCエンジン、TOKエンジンまたは検索エンジンを選択するか、カスタム・データ・エンジンを定義します。

データの場所

参照をクリックし、制御ファイルの場所を選択します。

タブのラベル

チェック・ボックスを選択し、OHJヘルプ・ナビゲータ・ウィンドウに表示されるタブのラベルを入力します。

ビューのタイトル

このチェック・ボックスを選択し、ビューのタイトルを入力します。

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

使用可能なビューでは要件が満たされない場合は、カスタム・ビューを定義できます。

カスタム・ビュー・タイプを作成するには、ビューの定義ページのビュー・タイプ・ドロップダウン・リストからカスタムを選択します。カスタム・タイプの定義ダイアログ・ボックスが表示されます。

図10-7 OHJオーサリング・ウィザード: カスタム・ビュー・タイプの定義

「図10-7 OHJオーサリング・ウィザード: カスタム・ビュー・タイプの定義」の説明

次の情報を使用して、ビューの定義ページの各フィールドにデータを入力します。

フィールド

説明

識別名

ビューの一意の名前を指定します。

Navigatorサブクラス

Javaクラスの名前を指定します。指定するクラスはoracle.help.navigator.Navigatorのサブクラスであることが必要です。

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

使用可能なデータ・エンジンでは要件が満たされない場合は、カスタム・データ・エンジンを定義できます。

カスタム・データ・エンジンを作成するには、ビューの定義ページのデータ・エンジンドロップダウン・リストからカスタムを選択します。カスタム・データ・エンジンの定義ダイアログ・ボックスが表示されます。

図10-8 OHJオーサリング・ウィザード: カスタム・データ・エンジンの定義

「図10-8 OHJオーサリング・ウィザード: カスタム・データ・エンジンの定義」の説明

次の情報を使用して、ビューの定義ページの各フィールドにデータを入力します。

フィールド

説明

識別名

データ・エンジンの一意の名前を指定します。

DataEngineサブクラス

Javaクラスの名前を指定します。指定するクラスはoracle.help.dataengine.DataEngineのサブクラスであることが必要です。

10.7 全文検索ビューの定義

OHJオーサリング・ウィザードの全文検索ビュー・ページでは、検索ビューの作成およびヘルプの全文検索索引の生成ができます。

全文検索索引を作成するには、ヘルプセットの全文検索索引を生成するチェック・ボックスを選択します。

図10-9 OHJオーサリング・ウィザード: 全文検索ビュー

「図10-9 OHJオーサリング・ウィザード: 全文検索ビュー」の説明

次の情報を使用して、全文検索ビュー・ページの各フィールドにデータを入力します。

フィールド

説明

ヘルプセットの全文検索索引を生成する

全文検索索引を作成するには、このチェック・ボックスを選択します。

キャラクタ・セット・エンコーディングを指定してください

必要なキャラクタ・セット・エンコーディングをドロップダウン・リストから選択します。デフォルトでは、西ヨーロッパ言語(ISO 8859-1)が選択されます。

検索で大文字と小文字を区別する

このチェック・ボックスを選択すると、大文字と小文字を区別する検索機能をヘルプで使用できるようになります。

数字の検索を有効にする

このチェック・ボックスを選択すると、数値の検索機能をヘルプで使用できるようになります。

完了した後、次へをクリックして続行します。

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

OHJオーサリング・ウィザードのマップ・ファイル・ページでは、ヘルプで使用するマップ・ファイルの作成、および一意のトピックIDとヘルプ・トピックとの関連付けができます。

図10-10 OHJオーサリング・ウィザード: 全文検索ビュー

「図10-10 OHJオーサリング・ウィザード: 全文検索ビュー」の説明

次の情報を使用して、全文検索ビュー・ページの各フィールドにデータを入力します。

フィールド

説明

マップ・ファイルを含めない

マップ・ファイルを用意しないことを指定します。このオプションは、ヘルプが状況依存ヘルプでない場合に役立ちます。

各HTMLファイルの<meta>タグを使用してマップ・ファイルを作成する

<meta>タグからマップ・ファイルを作成することを指定します。

一部のヘルプ・オーサリング・ツール(RoboHelpなど)は、HTMLファイル内のmetaタグにトピックIDを挿入します。このウィザード・オプションは、metaタグを検出して、そのタグからマップ・ファイルを作成します。

ツールで生成された別名(.ali)ファイルまたはヘッダー(.h)ファイルを使用してマップを作成する

生成された別名ファイルまたはヘッダー・ファイルからマップ・ファイルを作成することを指定します。参照をクリックし、マップ・ファイルの名前および場所を指定します。

既存のマップ・ファイルを含める

既存のマップ・ファイルを使用することを指定します。参照をクリックし、マップ・ファイルの名前および場所を指定します。

完了した後、次へをクリックして続行します。

10.9 関連リンクの変換

OHJオーサリング・ウィザードの関連リンク・ページでは、既存のヘルプ・システムに定義された関連リンクを独自の関連リンク・プロトコルに変換できます。

図10-11 OHJオーサリング・ウィザード: 関連リンク

「図10-11 OHJオーサリング・ウィザード: 関連リンク」の説明

次の情報を使用して、関連リンクページの各フィールドにデータを入力します。

フィールド

説明

OHJ ICEbrowserプロトコルを使用するよう関連リンクを変換する

すべての関連リンクをICEbrowser対応のalinkプロトコルに変換することを指定します。

関連リンクをリンクのハードコードされたリストに変換する

すべての関連リンクをリンクのハードコードされたリストに変換することを指定します。

すべての関連リンクを削除する

すべての関連リンクをヘルプ・ページから削除することを指定します。

完了した後、次へをクリックして続行します。

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

OHJオーサリング・ウィザードのポップアップ・ウィンドウ・ページでは、既存のヘルプ・システムに定義されたポップアップ・ウィンドウ・リンクを独自のポップアップ・リンク・プロトコルに変換できます。

図10-12 OHJオーサリング・ウィザード: ポップアップ・ウィンドウ

「図10-12 OHJオーサリング・ウィザード: ポップアップ・ウィンドウ」の説明

次の情報を使用して、ポップアップ・ウィンドウ・ページの各フィールドにデータを入力します。

フィールド

説明

OHJ ICEbrowserプロトコルを使用するようポップアップ・ウィンドウを変換する

すべてのポップアップ・ウィンドウ・リンクをICEbrowser対応のプロトコルに変換することを指定します。

すべてのポップアップ・ウィンドウを削除する

すべてのポップアップ・ウィンドウ・リンクをヘルプ・ページから削除することを指定します。

完了した後、次へをクリックして続行します。

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

OHJオーサリング・ウィザードのウィンドウ・タイプ・ページでは、ウィンドウ・タイプを定義できます。デフォルトでは、ウィンドウ・タイプは定義されません。新しいウィンドウ・タイプを定義すると、ウィンドウの識別情報、画面上の配置、色の属性およびそのウィンドウで使用できるツールバー・ボタンを構成できます。

図10-13 OHJオーサリング・ウィザード: ウィンドウ・タイプの定義

「図10-13 OHJオーサリング・ウィザード: ウィンドウ・タイプの定義」の説明

次の情報を使用して、ウィンドウ・タイプの定義ページの各フィールドにデータを入力します。

フィールド

説明

新規

新しいウィンドウ・タイプを作成し、そのウィンドウの名前をウィンドウ・タイプリストに追加します。

削除

選択したウィンドウ・タイプをウィンドウ・タイプリストから削除します。

新しいウィンドウ・タイプを定義するには、新規をクリックし、その属性を構成します。構成できる属性は次のとおりです。

10.11.1 ウィンドウの識別情報

ウィンドウ・タイプの定義ページの識別情報タブでは、ウィンドウの名前とタイトルを定義できます。

図10-14 OHJオーサリング・ウィザード: ウィンドウ・タイプの識別情報のプロパティ

「図10-14 OHJオーサリング・ウィザード: ウィンドウ・タイプの識別情報のプロパティ」の説明

次の情報を使用して、ウィンドウ・タイプの定義ページの識別情報タブの各フィールドにデータを入力します。

フィールド

説明

名前

一意のウィンドウ名を指定します。

タイトル

ウィンドウ・タイトルを指定します。

指定がない場合はこのウィンドウ・タイプを使用する

このチェック・ボックスを選択すると、このウィンドウがデフォルト・ウィンドウになります。

10.11.2 配置の属性

ウィンドウ・タイプの定義ページの配置タブでは、画面上でのウィンドウのサイズと位置を構成できます。

図10-15 OHJオーサリング・ウィザード: ウィンドウ・タイプの配置のプロパティ

「図10-15 OHJオーサリング・ウィザード: ウィンドウ・タイプの配置のプロパティ」の説明

次の情報を使用して、ウィンドウ・タイプの定義ページの配置タブの各フィールドにデータを入力します。

フィールド

説明

高さ

ウィンドウの高さを指定します。また、使用する単位としてピクセルまたはパーセントを選択します。

幅

ウィンドウの幅を指定します。また、使用する単位としてピクセルまたはパーセントを選択します。

X位置

ウィンドウのX座標を指定します。また、使用する単位としてピクセルまたはパーセントを、方向として左からまたは右からを選択します。

Y位置

ウィンドウのY座標を指定します。また、使用する単位としてピクセルまたはパーセントを、方向として上からまたは下からを選択します。

10.11.3 スタイルの属性

ウィンドウ・タイプの定義ページのスタイルタブでは、ウィンドウの配色(テキスト色と背景色)を定義できます。

図10-16 OHJオーサリング・ウィザード: ウィンドウ・タイプのスタイルのプロパティ

「図10-16 OHJオーサリング・ウィザード: ウィンドウ・タイプのスタイルのプロパティ」の説明

次の情報を使用して、ウィンドウ・タイプの定義ページのスタイルタブの各フィールドにデータを入力します。

フィールド

説明

テキストの前景色

ウィンドウに表示されるテキストの色を16進カラー・コードで指定します。色を選択するには、選択をクリックし、目的のテキスト色を選択します。

リンクの前景色

ウィンドウに表示されるリンクの色を16進カラー・コードで指定します。色を選択するには、選択をクリックし、目的のリンク・テキスト色を選択します。

ページの背景色

ウィンドウのページの背景の色を16進カラー・コードで指定します。色を選択するには、選択をクリックし、目的のページ色を選択します。

10.11.4 ツールバー・ボタン

ウィンドウ・タイプの定義ページのツールバー・ボタンタブでは、ヘルプ・トピック・ウィンドウで使用できるツールバー・ボタンを構成できます。

図10-17 OHJオーサリング・ウィザード: ウィンドウ・タイプのツールバー・ボタンのプロパティ

「図10-17 OHJオーサリング・ウィザード: ウィンドウ・タイプのツールバー・ボタンのプロパティ」の説明

次の情報を使用して、ウィンドウ・タイプの定義ページのツールバー・ボタンタブの各フィールドにデータを入力します。

フィールド

説明

ボタンのデフォルト・セットを表示する

ツールバー・ボタンのデフォルト・セットを表示するには、このチェック・ボックスを選択します。デフォルトでは、すべてのツールバー・ボタンを使用できます。ツールバー・ボタンをカスタマイズするには、このチェック・ボックスの選択を解除します。

「ナビゲータ」ボタン

「ナビゲータ」ツールバー・ボタンをウィンドウに追加するには、このチェック・ボックスを選択します。「ナビゲータ」ボタンを使用すると、「ヘルプ・ナビゲータ」ウィンドウが開きます。

「検索」ボタン

「検索」ツールバー・ボタンをウィンドウに追加するには、このチェック・ボックスを選択します。「検索」ボタンを使用すると、ヘルプ・ページ全体に対してテキストを検索できます。

「印刷」ボタン

「印刷」ツールバー・ボタンをウィンドウに追加するには、このチェック・ボックスを選択します。「印刷」ボタンを使用すると、トピックを印刷できます。

「進む」および「戻る」ボタン

「進む」および「戻る」ツールバー・ボタンをウィンドウに追加するには、このチェック・ボックスを選択します。「進む」ボタンと「戻る」ボタンを使用すると、前に開いたトピックにナビゲートし、現在のトピックに戻ってくることができます。

「ドッキング」および「ドッキング解除」ボタン

「ドッキング」および「ドッキング解除」ツールバー・ボタンをウィンドウに追加するには、このチェック・ボックスを選択します。「ドッキング」ボタンおよび「ドッキング解除」ボタンを使用すると、ヘルプ・トピック・ウィンドウと「ヘルプ・ナビゲータ」ウィンドウのドッキングおよびドッキング解除ができます。

10.12 ヘルプセットの作成

OHJオーサリング・ウィザードの終了ページでは、ウィザードで選択したオプションに基づいて、ヘルプセットが作成されます。

図10-18 OHJオーサリング・ウィザード: ヘルプセットの作成

「図10-18 OHJオーサリング・ウィザード: ヘルプセットの作成」の説明

次の情報を使用して、ヘルプセットの作成ページの各フィールドにデータを入力します。

フィールド

説明

ベース名

ヘルプ・セットのベース名を指定します。ベース名は、ファイル名拡張子なしで、制御ファイルの名前を定義します。たとえば、ベース名がmyprojectの場合、制御ファイル名はmyproject.hhc、myproject.hhk、myproject.idxなどのようになります。

バックアップ・コピーを作成する

更新されたファイルのバックアップ・コピーを作成することを指定します。ファイルは、.bakという拡張子で保存されます。

バックアップ・コピーを作成しない

更新されたファイルのバックアップ・コピーを作成しないことを指定します。

完了した後、終了をクリックして、ヘルプセット・ファイルを生成します。

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

この章では、テキスト検索インデクサについて説明します。また、テキスト検索インデクサを使用して索引ファイルを生成する方法について説明します。

この項の構成は、次のとおりです。

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

- 第11.2項「Javaの要件」

- 第11.3項「インデクサの実行」

- 第11.4項「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

オプション(推奨)の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

オプション(推奨)の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のインストール方法について説明します。

この章の構成は、次のとおりです。

- 第12.1項「Oracle Help for Java Developer's Kitについて」

- 第12.2項「JDeveloperのOracle Help for Javaランタイム」

- 第12.3項「OHJDKを使用する前に」

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

Oracle Help for Java Developer's Kit (OHJDK)は、HTMLベースのヘルプ・コンテンツをJava環境で開発および表示するためのJavaコンポーネントおよびAPIのセットです。これには、Oracle Help for Java (OHJ)エンジンと、Javaアプレットおよびアプリケーションでの状況依存ヘルプの実装に必要なその他のツールが含まれています。

Oracle Help for Javaエンジンは、Javaアプリケーションおよびアプレット用のJavaベースのフル機能ヘルプ・システムです。状況依存ヘルプをナビゲートおよび表示するのためのPure Javaコンポーネントを提供します。Oracle Help for Javaは無料で利用でき、開発したアプリケーションのヘルプ・システムとして再配布できます(このリリースのライセンス情報を参照してください)。

Oracle Help for Javaは、JavaHelpやMicrosoftのHTML Help標準の拡張形式など、いくつかのファイル形式のヘルプ・コンテンツをサポートします。ヘルプ・コンテンツの作成にヘルプ・オーサリング・ツールを使用しない場合は、「Oracle Helpのファイル形式」を参照することをお薦めします。サード・パーティのOHJ対応ヘルプ・オーサリング・システムを使用している場合は、そのドキュメントを参照してください。

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

JDeveloperの一部として、Oracle Help for Javaのランタイム・ライブラリohj.jarが配布されます。開発者がOracle Help for Javaを独自のアプリケーションに統合する際には、プロジェクト設定を変更してOracle Help for Javaライブラリへの依存性を追加できます。次の場所にあるOracle Technology NetworkのOracle Helpページから、サンプル・コード、ヘルプセット・オーサリング・ウィザードおよびデモを含む、Oracle Help for Javaの完全なリリースを無料で入手できます。

http://www.oracle.com/technetwork/topics/index-083946.html

12.3 OHJDKを使用する前に

Oracle Help for Java Developer's Kit (OHJDK)は、HTMLベースのヘルプ・コンテンツをJava環境で開発および表示するためのJavaコンポーネントおよびAPIのセットです。これには、Oracle Help for Java (OHJ)エンジンと、Javaアプレットおよびアプリケーションでの状況依存ヘルプの実装に必要なその他のツールが含まれています。

この項では、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のバイナリ

ファイル

内容

helpversion_num.jar

ヘルプ・エンジンの最適化済バイナリ。

oracle_ice.jar

ICEsoft Technologies, Inc.のICEbrowserをOracleがカスタマイズしたバージョン。OHJエンジンは、HTMLトピックの表示にICEbrowserを使用します。

12.3.2.2 オーサリング・ツール

次のJARファイルには、ヘルプセット・オーサリング・ウィザードおよびテキスト検索インデクサの実装が含まれています。これらのファイルは、製品アプリケーションとともに再配布するためのものではありません。

表12-2 OHJのオーサリング・ツール

ファイル

内容

helpwizard-version_num.jar

ヘルプセット・オーサリング・ウィザードの実装。ヘルプセット・オーサリング・ウィザードの実行には、OHJDKインストールのbinディレクトリに作成されるバッチ・ファイルを使用できます。

helpindexer-version_num.jar

OHJテキスト検索インデクサの実装。この全文検索インデクサを使用してOracle Helpの検索索引(.idx)ファイルを作成できます。

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

次のJARファイルには、OHJDKとともに配布されるデモンストレーション・プログラムが含まれています。このファイルは、製品アプリケーションとともに再配布するためのものではありません。

表12-3 OHJのデモンストレーションJARファイル

ファイル

内容

helpdemo-version_num.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オブジェクトの構成および作成方法、ヘルプ・データの追加、タブの追加方法およびトピックの表示方法について説明します。

この章の構成は、次のとおりです。

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

- 第13.2項「Helpオブジェクトの構成」

- 第13.3項「ヘルプ・データの追加」

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

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

- 第13.6項「ナビゲータ・ウィンドウの表示」

- 第13.7項「トピックの表示」

- 第13.8項「ヘルプ・オブジェクトの破棄」

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パラメータは、複数の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を終了します。JavaアプリケーションからOHJを起動する場合は、standAloneModeパラメータをfalseに設定します(そうしないと、ヘルプを閉じたときにアプリケーションも終了します)。

パラメータ:

- htmlBrowserClass: トピック表示コンポーネントとして使用するHTMLBrowserサブクラス。

- combineBooks: trueの場合、ヘルプ・システムに追加されたブックからのすべてのビューが1つのタブ・パネルに表示されます。falseの場合、ブックごとに個別のタブ・パネルが作成され、どのブックを表示するかをエンド・ユーザーが選択できます。

- useLabelInfo: trueの場合、表示とビューのマージに作成者定義のラベル情報が使用されます。falseの場合、標準のデフォルト・ラベルが使用されます。

- standAloneMode: trueの場合、ヘルプ・ウィンドウがすべて閉じられるとヘルプ・システムはJVMを終了します。OHJをJavaアプリケーションから起動する場合は、falseに設定してください。

13.3 ヘルプ・データの追加

Helpオブジェクトを作成した後、1つ以上のBookオブジェクトを追加する必要があります。Bookオブジェクトは、ヘルプ・コンテンツの集まり、すなわちブックをカプセル化します。

HelpSetブック実装によって、「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をマップする方法について説明します。

この章の構成は、次のとおりです。

- 第14.1項「状況依存ヘルプについて」

- 第14.2項「ヘルプ・トピックへのトピックIDのマップ」

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

- 第14.4項「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)

コンポーネントをヘルプ・マネージャに登録します。デフォルトのBookを使用してtopicIdが検索されます。このメソッドが呼び出されたときにデフォルトのBookが登録されていない場合、コンポーネントはヘルプマネージャに登録されず、その後このコンポーネントに対してshowHelpForComponent()がコールされても、ヘルプは表示されません。このメソッドを使用して登録されたコンポーネントに対しては、[F1]キー押下イベントまたはマウスの右クリック・イベントに対応した、CSHManagerによるヘルプの表示は行われません。

パラメータ:

- 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ファイルを作成する方法についても説明します。

この章の構成は、次のとおりです。

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

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

- 第15.3項「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 the Webの使用方法について説明します。次の章で構成されます。

- 第16章「OHWデモ・ファイルのデプロイ」
この章では、OHWデモ・ファイルのデプロイ方法について説明します。初めてOHWを使用する場合は、独自のヘルプ・システムのデプロイを開始する前に、デモ・ファイルをデプロイするようお薦めします。

- 第17章「OHWのデプロイの理解」
この章では、OHWのデプロイメント・プロセスについて説明します。

- 第18章「Webアプリケーションでの状況依存ヘルプの実装」
この章では、Webアプリケーションで状況依存OHWヘルプを実装する方法について説明します。

- 第19章「ADFリッチ・クライアント・ヘルプ・プロバイダ」
この章では、ADFリッチ・クライアント・ヘルプ・プロバイダと、OHWをヘルプ・プロバイダとして使用する方法について説明します。

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

この章では、OHWのデモ・ファイルをスタンドアロンのOracle WebLogic ServerとJDevelolperが統合されたOracle WebLogic Serverにデプロイする方法、およびそのデモ・ファイルの実行方法について説明します。

この章の構成は、次のとおりです。

- 第16.2項「OHWのデモ・ファイルの理解」

- 第16.3項「スタンドアロンのOracle WebLogic ServerでのOHWのデモEARファイルのインストール」

- 第16.4項「JDeveloperが統合されたOracle WebLogic ServerでのOHWのデモEARファイルのインストール」

- 第16.5項「OHWのデモEARファイルの実行」

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

OHWのデモEARファイルには、デモの表示とリリースの試用のために必要なすべてのクラス・ライブラリが格納されています。サンプル・ヘルプセット、OHWサーブレット・ファイルおよびXML構成ファイルが含まれています。デモ・ファイルをデプロイすることによって、OHWインタフェースを体験できます。また、既存のヘルプセットを独自のヘルプセットに置き換えることもできます。

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

OHWのデモ・ファイルには、ohw-rcf-demo-thin.earおよびohw-rcf-demo-thick.earの2つのバリアントが用意されています。

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.earおよびohw-rcf-demo-thick.earのどちらか一方をOracle WebLogic Serverにデプロイしてください。両方デプロイすると、デモEARファイルの実行時に競合が発生します。

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 Server管理コンソールを起動し、「デプロイメント」ページに移動します。

3. 「デプロイメント」ページで、「インストール」をクリックしてデプロイ・ウィザードを起動します。

4. 「パス」フィールドにohw-rcf-demo-thick.earファイルの保存先を入力するか、「現在の場所」でEARファイルを参照して選択します。
「次」をクリックして続行します。

5. ターゲット指定スタイルの選択ページで、このデプロイメントをアプリケーションとしてインストールするを選択し、「次へ」をクリックします。

6. 「オプション設定」ページで、設定を確認します。設定はデフォルトのままにしておくことをお薦めします。「Next」をクリックして続行するか、「終了」をクリックしてデプロイメントを完了します。

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オプション」ページで、設定を確認します。設定はデフォルトのままにしておくことをお薦めします。「Next」をクリックして続行するか、「終了」をクリックしてデプロイメントを完了します。

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アプリケーションとしてのOHWのデプロイ方法、および別のWebアプリケーションの一部としてのOHWのデプロイ方法について説明します。

この章の構成は、次のとおりです。

- 第17.1項「OHWのデプロイについて」

- 第17.2項「要件および依存性の検証」

- 第17.3項「OHWライブラリ・ファイルの検証」

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

- 第17.5項「OHW構成ファイルの理解」

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

- 第17.7項「OHW-RCのアクセスURLの変更」

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

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

- 第17.10項「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 Fusion Middleware管理者ガイド』を参照してください。

Oracle WebLogic Serverを使用しない場合は、ADF、JSF、JSTLのすべてのライブラリ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-RCのフィルタおよびフィルタ・マッピング

- ヘルプ・インスタンスのサーブレットおよびサーブレット・マッピング

注意:

Oracle Helpのシステム・ファイルを以前のリリースからアップグレードした場合、既存のOHWヘルプ・アプリケーションも更新および再ビルドする必要があります。ヘルプセット・ファイルと構成ファイルを、以前のOHWヘルプ・アプリケーションの場所から新しいOHWヘルプ・アプリケーションの場所へコピーして、次のサーブレット・マッピング情報を追加するようにweb.xmlファイルを更新します。

<!-- Route the OHW-RC resources through the resource servlet. -->
<servlet-mapping>
<servlet-name>resources</servlet-name>
<url-pattern>/ohr/*</url-pattern>
</servlet-mapping>

次に、サンプル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>
<!-- Route the OHW-RC resources through the resource servlet. -->
<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-RCフロント・サーブレットの初期化パラメータとして設定されています。このパラメータは、サーブレット・コンテナごとに異なる方法で処理されます。初期化パラメータ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-RCのアクセスURLの変更」を参照してください。

9. <OHW-RC_deployment_name>ディレクトリをWARファイルに圧縮します。

10. application.xmlをohw-rc-thick-demo\META-INFディレクトリからコピーして、<OHW-RC_HOME>\META-INFディレクトリに保存します。必要に応じてファイルを編集します。このファイルで、デプロイする各製品のWebモジュール名を指定します。
手順9で<web-uri></web-uri>要素内に作成したWARファイル名を指定することもできます。アプリケーションのアクセス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-RCのアクセス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をスタンドアロンWebアプリケーションとしてデプロイするには、OHWの実行に必要なすべてのファイルを含むOHWのWARファイルを、専用のコンテキスト・パスを持つアプリケーション・サーバーの個別のデプロイ・ディレクトリにコピーする必要があります。

次に説明するように、OHW管理者は、主要なタスクを実行してから、スタンドアロンWebアプリケーションとしてOHWヘルプ・システムをデプロイする必要があります。タスクの詳細は、第17章「OHWのデプロイの理解」を参照してください。

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

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パラメータはweb.xmlで定義され、param-valueを指定します。

この構成ファイルの詳細は、第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つとしてデプロイできるようになります。

OHWを既存のWebアプリケーションの一部としてデプロイすると、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ファイルによって、表示するヘルプセットとその表示方法が指定されます。ロケール、ブランド情報およびその他の各種設定も指定できます。このファイルの名前および場所は、サーブレット初期化パラメータohwConfigFileURLとして設定されています(web.xmlで定義)。このパラメータは、サーブレット・コンテナごとに異なる方法で処理されます。この構成ファイルの詳細は、第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をマップする方法について説明します。

この章の構成は、次のとおりです。

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

- 第18.2項「ヘルプ・トピックへのトピックIDのマップ」

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

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のヘルプ・プロバイダとしての登録方法について説明します。

この章の構成は、次のとおりです。

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

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

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

- 第19.4項「HelpTopicId属性の使用」

- 第19.5項「その他のヘルプ・プロバイダの使用」

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

ご使用のADF Facesアプリケーションにオンライン・ヘルプを組み込む場合、ADF Faces (ADFリッチ・クライアントとも呼ばれる)には、そのための簡単な方法が用意されています。オンライン・ヘルプ・システムを作成して、アプリケーションのコンポーネントにヘルプ・トピックを統合できます。

この章では、ヘルプ・プロバイダとしてのOHWの構成方法、ADFリッチ・クライアントのその他のヘルプ・プロバイダ、およびHelpTopicId属性を使用してヘルプ・トピックをアプリケーションに関連付ける方法について説明します。

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

ヘルプ・トピックをADF Facesコンポーネントと統合すると、そのコンポーネントにヘルプ・アイコン(疑問符を青色の円で囲んだもの)が表示されます。ヘルプ・アイコンをクリックすると、図19-1に示すように、関連するヘルプ・トピックが新しいウィンドウに表示されます。

図19-1 ADF Facesアプリケーションのヘルプ・アイコン

「図19-1 ADF Facesアプリケーションのヘルプ・アイコン」の説明

オンライン・ヘルプとアプリケーションの統合は、次の手順で実行する簡単なプロセスです。

- ヘルプ・プロバイダのアプリケーションでの登録

- 各ヘルプ・トピックのトピックIDおよびヘルプ・テキストを含むプロパティ・ファイルの作成

- HelpTopicId属性を使用した、UIコンポーネントのヘルプ・トピックへの関連付け

オンライン・ヘルプとアプリケーションとの統合方法の詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Webユーザー・インタフェース開発者ガイド』のコンポーネントへのヘルプの表示に関する項を参照してください。

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

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にコードを入力します。例:

<adf-settings xmlns="http://xmlns.oracle.com/adf/settings">

<help-provider>

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

<property>
<property-name>ohwConfigFileURL</property-name>
<value>/helpsets/ohwconfig.xml</value>
</property>

<!--property>
<property-name>group</property-name>
<value>null</value>
</property-->

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

</help-provider>

</adf-settings>

このadf-settings.xmlファイルを、次のように設定してください。

- OHWをヘルプ・プロバイダとして使用する場合は、この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-RCの登録」を参照してください。

HelpTopicId属性の詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Webユーザー・インタフェース開発者ガイド』のコンポーネントへのヘルプの表示に関する項を参照してください。

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

ADFリッチ・クライアントの一般的な2つのヘルプ・プロバイダは、ResourceBundleHelpProviderとELHelpProviderです。ResourceBundleHelpProviderでは、リソース・バンドルに定義されているヘルプをADF Facesアプリケーションに表示できます。リソース・バンドルは、ヘルプ・ファイル、制御ファイル、グラフィックおよびその他の関連ファイルのコンテナです。ELHelpProviderでは、XLIFFファイルに定義されているヘルプ・テキストをADF Facesアプリケーションに表示できます。XLIFFファイルはマップに変換されるか、ヘルプ・テキスト文字列のマップを含むマネージドBeanを作成します。ELHelpProviderではヘルプ・ファイルは作成されませんが、このファイルをADF Facesアプリケーションに関連付けるのに役立ちます。

これらおよびその他のヘルプ・プロバイダの詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Webユーザー・インタフェース開発者ガイド』のコンポーネントへのヘルプの表示に関する項を参照してください。

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

この付録では、JavaHelp仕様に基づいたOracle Helpのファイル形式について説明します。オラクル社では、追加機能に対応するためにJavaHelpのファイル定義を拡張しています。

この付録の構成は、次のとおりです。

- 第A.1項「ヘルプセット・ファイル」

- 第A.2項「マップ・ファイル」

- 第A.3項「目次ファイル」

- 第A.4項「索引ファイル」

- 第A.6項「リンク・ファイル」

- 第A.5項「検索索引ファイル」

- 第A.7項「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 マップ・ファイルの要素

要素

属性

由来

サポート

<toc>

-

JH

OHおよびJH: 相違点については以下を参照

-

xml:lang

JH

JHのみ

-

version

JH

JHのみ

<tocitem>

-

JH

相違点については以下を参照

-

target

JH

OHおよびJH

-

text

JH

OHおよびJH

-

image

JH

OHおよびJH

-

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

-

text

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

-

text

JH

OHおよびJH

<indexentry>

-

OH

OHのみ

-

target

OH

OHのみ

-

text

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でそのモーダル・ウィンドウがどのように処理されるかについて説明します。モーダル・ウィンドウとは、そのウィンドウから制御を移動できないウィンドウのことです。モーダルではないウィンドウとは、他のウィンドウに制御の切替えが可能なウィンドウのことです。

この付録の構成は、次のとおりです。

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

- 第B.2項「ウィンドウの登録」

- 第B.3項「ウィンドウの登録解除」

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オブジェクトをまだ使用しており、ヘルプセットを使用していない場合は、次の項のヘルプ・ブック固有の情報を参照してください。

この付録の構成は、次のとおりです。

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

- 第C.2項「OHJへのHelpデータの追加」

- 第C.3項「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ブラウザで表示されるため、数多くのユーザーがヘルプの単一のインストールにアクセスします。

この付録の構成は、次のとおりです。

- 第D.1項「Oracle Help for the Web-UIXについて」

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

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

- 第D.4項「OHW-UIXのデプロイの理解」

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

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

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

Oracle Help for the Web-UIX (OHW-UIX)は、HTMLに基づくヘルプ・コンテンツをWeb環境で開発し、配信するためのJavaサーブレットおよびファイル形式仕様です。OHW-UIXを使用すると、Webアプリケーションの状況依存ヘルプを提供したり、独立したHTMLコンテンツの構造化されたビューをWebで処理および表示できます。OHW-UIXでは、ユーザーに必要となるのは、ヘルプ・コンテンツをナビゲートし、表示するためのWebブラウザのみです。処理は、OHW-UIXサーブレットを介してサーバー上で行われます。ヘルプ・コンテンツは1台のサーバーで管理され、任意の数のWebブラウザで表示されるため、数多くのユーザーがヘルプの単一のインストールにアクセスします。

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 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アプリケーションでは重要な機能です。次の各トピックでは、OHW-UIXのユーザー・インタフェース要素について、OHJと比較しながら詳しく説明します。

- OHW-UIXの目次

- OHW-UIXの索引

- OHW-UIXの検索

- OHW-UIXのトピック

D.2.1 OHW-UIXの目次

OHJでは目次(TOC)がツリーとして表示されるのに対し、OHW-UIXのTOCではヘルプ・システムの階層が一連のページとして表示されます。各ページは階層内の1つのノードを示し、ページごとにトピックおよび子ノード(つまり現在のノードに含まれるノード)の両方を表示できます。トピック・タイトルを選択すると、タブが「トピックの表示」タブに切り替わり、そのトピックのコンテンツが表示されます。「目次」タブでノードのタイトルをクリックすると、ページがリフレッシュされ、そのノードのリストが表示されます。階層内を移動すると、ページ上部に一連のリンクとしてナビゲーション追跡(ブレッドクラム)が表示されます。ここから、階層内の上位レベルにすばやく戻ることができます。

図D-2 OHW-UIXの「目次」ビュー

「図D-2 OHW-UIXの「目次」ビュー」の説明

図D-3 ナビゲーション・リンク

「図D-3 ナビゲーション・リンク」の説明

D.2.2 OHW-UIXの索引

OHW-UIXのキーワード索引も、OHJのキーワード索引とは若干異なっています。OHJと同様、OHW-UIXの索引にも、「移動先」というラベルが付けられた、索引で見つける語句を入力するためのテキスト・フィールドがあります。ただし、OHJとは異なり、関連する語句が表示されるようにするには、「移動」を選択するか、または[Enter]キーを押す必要があります。OHW-UIXで一度に表示される項目は10個のみですが、「移動先」フィールドに入力した語句と一致する項目のリスト内を移動するためのコントロールも表示されます。「移動先」フィールドに何も入力しない場合は、キーワード・リスト全体での移動が可能です。

キーワード・リストから項目を選択すると、ページがリフレッシュされ、選択したキーワードに関連するトピックのリストが表示されます。このリストは、OHJの「索引」タブの下部に表示される、見つかったトピックのリストに相当します。このリストから項目を選択すると、タブが「トピックの表示」に切り替えられ、そのトピックが表示されます。

索引のトピックの対象ページの上部には、目次の項で説明したものと同様のナビゲーション・リンクが表示されます。ただし、このリンクを使用した場合、常に、キーワード・リストに戻ります。

図D-4 OHW-UIXの「索引」ビュー

「図D-4 OHW-UIXの「索引」ビュー」の説明

D.2.3 OHW-UIXの検索

OHW-UIXのテキスト検索は、索引に似ています。「検索」テキスト・フィールドに単語または句を入力して[Enter]を押すと、関連するトピックのリストが表示されます。最初の10項目が表示され(リストはランクに応じてソートされます)、リストの他の項目にさらに移動できます。「拡張検索」モードでは、検索オプション(大/小文字の区別、すべての単語に一致する、いずれかの単語に一致する、など)を指定したり、ブール式を使用することもできます。

索引と同様、見つかったトピックのリストから項目を選択すると、「トピックの表示」タブにトピックが表示されます。

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

「図D-5 OHW-UIXの「検索」ナビゲータ」の説明

図D-6 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-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には、OHW-UIXの3つのサンプル・ヘルプセットが、それぞれのヘルプ・トピック、ヘルプセット・ファイルおよび制御ファイルとともに格納されています。また、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 Server管理コンソールを起動し、「デプロイメント」ページに移動します。

3. 「デプロイメント」ページで、「インストール」をクリックしてデプロイ・ウィザードを起動します。

4. 「パス」フィールドにohw-uix-demo.earファイルの保存先を入力し、「次へ」をクリックします。

5. ターゲット指定スタイルの選択ページで、このデプロイメントをアプリケーションとしてインストールするを選択し、「次へ」をクリックします。

6. 「オプション設定」ページで、設定を確認します。設定はデフォルトのままにしておくことをお薦めします。「Next」をクリックして続行するか、「終了」をクリックしてデプロイメントを完了します。

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ファイルから新規アプリケーションを作成します。「ファイル」メニューから、「新規」を選択します。「新規ギャラリ」ダイアログ・ボックスで、「一般」カテゴリの下の「アプリケーション」を選択し、「項目」リストから「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を使用する場合は、JDeveloper 10.1.2以前のリリースをOTNアーカイブからダウンロードしてください。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データ・プロバイダとして表示されます。HelpProviderはUIXのページで宣言する必要がないという点で特別であり、構成オブジェクトに一度登録すると、すべてのページで使用できるようになります。

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-RCヘルプ・システムへのアップグレード

OHW-UIXからOHW-RCにアップグレードする場合、ヘルプセット・コンテンツの変更は不要ですが、OHW-RCを使用するために、次の2つを実行する必要があります。

- OHW-RCのJARファイルを、WEB-INF/libディレクトリにコピーします。

- WEB-INF/ディレクトリにあるweb.xmlファイルを変更します。これを行う最良の方法は、OHW-RCのデモ・バンドルからweb.xmlを取り出し、サーブレットとリソースの定義およびマッピングをコピーすることです。

OHW-RCの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>

- OHW-RCの基本構成
OHW-RCのフィルタを定義し、そのフィルタを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-RCのクラス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-RCでは、1つのWebアプリケーションで複数のOHW-RCインスタンスをサポートします。次に、2つのOHW-RCインスタンスをデプロイする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 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>

Copyright © 2002, 2013, Oracle and/or its affiliates. All rights reserved.