| Oracle® Fusion Middleware Oracle Helpによるヘルプ・システムの開発 12c(12.1.2) E48092-01 |
|
 前 |
 次 |
この章では、Oracle Help for the Web構成ファイルと、このファイルの各種要素(helpConfiguration、brandings、locales、parameters、navigatorAliasesなど)について説明します。
この章には次の項が含まれます:
Oracle Help for the Web構成ファイルは、OHW構成を定義するXMLファイルです。この構成により、OHWサーブレットの調整可能なすべての機能を制御します。通常、このファイルの名前はohwconfig.xmlですが、サーブレットの初期化パラメータconfigFileNameの値として名前を指定することで、任意の名前を付けることができます。OHWのデモンストレーション・ファイルでは、ohwconfig.xmlを使用します。
<helpConfiguration>要素は、ヘルプ構成ファイルのトップレベル要素です。次で説明する構成の要素はすべて、<helpConfiguration>タグと</helpConfiguration>タグの間にある必要があります。helpConfiguration要素には、versionとdebugModeという2つの属性があります。
helpConfiguration要素のversion属性は、常に設定する必要があります。Oracle Help for the Webの場合、この属性の値は2.0になります。
次に例を示します。
<helpConfiguration version="2.0">
ohwconfig.xmlの<helpConfiguration>要素でdebugMode="true"を設定してデバッグ・モードを有効にします。これにより、ヘルプセットをデバッグ・モードでロードできます。このモードでは、不正なヘルプセットがスキップされます。デバッグ・テキストは、画面の左上端およびブラウザのタイトル・バーに、ブランド情報とともに表示されます。デバッグ・テキストは、アプリケーションの実行中にスキップされた不正なヘルプセットの数を示します。
不正なヘルプセットが存在しないときには、ブランド表示領域に次のメッセージが表示されます。図8-1も参照してください。
Debug Mode: 0 Missing Helpsets".
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
<brandings>要素は、タブ・バー上に表示される製品のブランド・テキストまたはイメージを指定します。<brandings>に属性はありません。すべてのブランド情報のプレースホルダになります。
<brandings>要素には、次の表に示す要素のいずれか1つのみを含めることができます。ブランド情報が指定されていない場合は、デフォルトのブランド・テキストが使用されます。
表8-1 <brandings>の子要素
| 要素 | 説明 |
|---|---|
|
|
属性情報からブランド情報をレンダリングします。また、特定のロケールを使用するようにこの要素を指定できます。この要素でサポートされる属性は、次のとおりです。
OHWは、使用されるロケールを絞り込みますが、拡張はしません。たとえば、ロケール |
|
|
OHWは、使用されるロケールを絞り込みますが、拡張はしません。たとえば、ロケール |
|
注意: XLIFFリソース・バンドルを使用する場合、リソース・バンドル・サポート(
|
次に例を示します。
<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>
国際化を実装する場合、変換が必要になるヘルプセットに対して次のベスト・プラクティスを使用すると、ohwconfig.xmlを変換する必要がなくなります。
ohwconfig.xmlにブランド情報を直接入力せずに、<brandingFromResource>を使用して、すべてのロケール用に変換されたバンドルを参照します。ブランド情報は標準のJavaリソース・バンドルにあるため、このバンドルは、通常の変換プロセスで変換されます。
すべてのヘルプ制御ファイル(マップ、TOC、索引およびヘルプセット・ファイル)の先頭にXML宣言を入力します。この場合、<controlFileEncoding>を使用しないでください。指定されたローカライズ済ヘルプセット内のすべての制御ファイルには、同じエンコーディングを使用します。ヘルプセット・ファイルで指定したエンコーディングは、すべての制御ファイルでの読取りに使用されます。
|
注意: 旧バージョンのOHJを使用している場合は、ヘルプセットでXML宣言が認識されず、 |
ファイルは変換する必要がないため、ロケールごとに個別のファイルを使用する必要がなくなります。一部のサイトでは、別の理由から、個別のファイルを使用することがあります。
ohwconfig.xmlファイルの<locales>セクションには、1つまたは複数のロケールを指定できます。localesセクションには、システムの1つのロケールを指定するタグが1つ以上あります。これらのタグのタイプは、<locale>要素または<localeFromFile>要素のいずれかです。要素名が示すとおり、<locale>要素はロケール・インラインを指定し、<localeFromFile>要素はロケールの宣言を外部ファイルに委譲します。外部ファイルには、1つの<locale>要素が含まれます。
表8-2 <locales>の子要素
| 要素 | 説明 |
|---|---|
|
|
|
|
|
ロケールに依存する操作に対応するJava Localeを構築するために使用されるISO言語、国および(オプション)バリアント・コードを指定します。また、Oracle Help制御ファイルのキャラクタ・セット・エンコーディングのJavaでサポートされるエンコーディング名(ISO8859_1など)を指定します。 リストされる最初の この要素でサポートされる属性は、次のとおりです。
|
次に例を示します。
<locales>
<locale language="en">
... set of books for this locale ...
</locale>
</locales>
<books>要素は、Oracle Help for the Webで表示されるコンテンツを指定します。<books>要素には、任意の数のヘルプセットを含めることができます。ヘルプセットはブックとも呼ばれます。
<books>要素には、次の要素を含めることができます。
表8-3 <books>の子要素
| 要素 | 説明 |
|---|---|
|
|
OHWのこのインスタンスに含めるヘルプセット。この要素の属性は、次のとおりです。
|
次に例を示します。
<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(ゼロ)個以上含めることができます。
デフォルトでは、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
構成ファイルのこのセクションのサンプルでは、英語と日本語の構成ファイルを指定しています。
<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>
同じイメージ、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ファイルがディレクトリとみなされるため、追加の..が必要になります。
<parameters>要素は、その他の様々なOHWパラメータの値を指定します。すべてのパラメータで、大/小文字が区別されます。
表8-4 <parameters>の子要素
| 要素 | 説明 |
|---|---|
|
|
|
|
|
|
|
|
|
combineBooksがtrueの場合、「索引」タブのように、同じラベルを持つ同じタイプのナビゲータのみが1つのナビゲータにマージされます。useLabelInfoをtrueに設定している場合は、予期しない結果が発生することがあります。たとえば、1つのヘルプセットにキーワード索引で上書きされたデフォルトの「索引」ラベルとデフォルトのままの他のラベルがある場合、索引は同じタブにマージされません。これを変更するには、ヘルプセットを同じ(ヘルプセットのヘルプセット・ファイルで)になるように設定するか、または構成ファイルのuseLabelInfoをfalseに設定します。
次に例を示します。
<parameters> <combineBooks>true</combineBooks> <useLabelInfo>false</useLabelInfo> </parameters>
他に、次のような重要なパラメータがあります。
表8-5 <parameters>キーワード子要素
| 要素 | 説明 |
|---|---|
|
|
1ページに表示されるキーワードの数。デフォルト値は |
|
|
1ページに表示されるトピックの数。デフォルト値は |
|
|
1ページに表示される検索結果の数。デフォルト値は |
これらの要素は、パフォーマンス・チューニングをサポートしたり、デフォルト以外のエラー、状態、ロケール処理を指定する場合に使用します。
表8-6 <parameters>パフォーマンス子要素
| 要素 | 説明 |
|---|---|
|
|
OHWで検索を実行するために使用できるスレッドの最大数。デフォルト値は 多数のユーザーがヘルプ・システムに接続して、同時に検索機能を使用すると予測できる場合は、maxSearchThreadsの値を10よりも大きくしてもかまいませんが、お薦めはできません。ヘルプ・システムが検索中に応答しない場合は、 |
|
|
トピックが見つからない場合に、OHWでは、このトピックがかわりに表示されます。このパラメータの値はトピックIDです。値が設定されていない場合、OHWでは、標準のエラー・ページが提供されます。 |
|
|
OHWが使用する必要がある状態マネージャを指定します。 |
|
|
OHWでは、特定のロケール限定子を使用して、ユーザー・リクエストに基づきローカライズ済ヘルプセットを選択します。OHWには、値が設定されていない場合にブラウザ設定を使用してロケールを決定する、デフォルトのロケール限定子があります。 |
|
|
メモリーに同時に保存されるアクティブなローカライズ済ヘルプセットの数。デフォルト値は |
オプションの<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ナビゲータでは、 |
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によって、ユーザーが明示的にコンバータを登録しなくても、リンクが作動します。
OHWは、OHW構成ファイルの<locale>タグをサポートします。このファイルは、OHWがサポートするロケールの単一インスタンスを定義します。<locale>タグは、ロケールが影響する操作のJava Localeの構築に使用されるISO言語、国およびバリアント・コード(オプション)を指定します。また、Oracle Help制御ファイルのキャラクタ・セット・エンコーディングのJava対応エンコーディング名(ISO8859_1など)を指定します。リストされる最初の<locale>要素がデフォルト・ロケールとなります。
OHWでは、ヘルプセットは別の方法でロードされます。RCFアプリケーションとしてのOHWでは、ヘルプセット内の単一ファイルに指定された定義テキスト・コンテンツとともに、50のコンポーネントが画面に表示されることがあります。すべてのヘルプセットがロードされないようにして、ユーザーが画面を開いたときにヘルプセットのロードにより発生するラグを削減するには、選択したヘルプセットの事前ロードを有効にします。
このため、OHWの場合、構成ファイルでは、<locale>タグのオプションの属性preloadがサポートされています。この属性の可能な値は、NONE、ALLおよびTOPICMAPです。値が指定されていない場合、デフォルト値はNONEです。
各値の動作は、次のとおりです。
表8-7 preloadの値の動作
| preloadの値 | OHWの初期起動 | トピックにアクセスしたときの動作 | UIにアクセスしたときの動作 |
|---|---|---|---|
|
|
処理は必要ありません。 |
要求されたトピックが見つかるまでトピック・マップがロードされます。 |
選択されたヘルプセット内のすべてのビューおよびナビゲータがロードされます。 |
|
|
ロケールのすべてのヘルプセットがロードされ(すべてのビューおよびナビゲータが起動します)、トピック・マップもすべてロードされます。 |
キャッシュからのアクセス。 |
キャッシュからのアクセス。 |
|
|
ロケールのすべてのヘルプセットのトピック・マップのみがロードされます。 |
キャッシュからのアクセス。 |
選択されたヘルプセット内のすべてのビューおよびナビゲータがロードされます。 |
構成ファイルは、次のようになります。
<?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>
OHWには、ヘルプ・システムの実行中にファイルの変更を含めるように、Oracle Help for the Web構成ファイルを実行時にリロードするメソッドがあります。この変更の例として、ヘルプ・システムを再デプロイせずに、将来パッチを適用するヘルプセットなどがあります。構成ファイルをリロードすると、キャッシュが空になり再構築されます。
ユーザーが実行時に構成ファイルリロードできるようにする場合、web.xmlで新規パラメータohwConfigAutoUpdateを追加します。
実行時にOracle Help for the Web構成ファイルをリロードするには:
web.xmlで新規パラメータohwConfigAutoUpdateを作成し、それをtrueに設定します。
たとえば、web.xmlファイルは、次のようになります。
<?xml version = '1.0' encoding = 'UTF-8'?>
...
<init-param>
<param-name>ohwConfigAutoUpdate</param-name>
<param-value>true</param-value>
</init-param>
構成ファイルを必要に応じて更新します。
構成ファイルの更新後に、ヘルプ・アプリケーションのデフォルトのホーム・ページを開きます。
ヘルプ・アプリケーションのホーム・ページを開くと、古い構成設定が消去され、新しい設定が有効になります。
