| Oracle® Fusion Middleware Oracle Helpによるヘルプ・システムの開発 12c(12.1.2) E48092-01 |
|
 前 |
 次 |
この章では、OHJとOHWで使用する、トピック・ファイル、トピックIDと関連リンク、ポップアップ、ウィンドウ・タイプおよびカスタム・プロトコル・リンクについて説明します。
この章には次の項が含まれます:
トピック・ファイルは、ヘルプ・システムのコンテンツが含まれるHTMLファイルです。このHTMLファイルでサポートされる機能は、ファイルの表示に使用されるブラウザ(またはHTML表示コンポーネント)によって異なります。
OHJに付属のHTML表示コンポーネントは、ICEsoft Technologies社製のICEbrowserを、Oracle用に変更したものです。バージョン5.01以降のICEbrowserは、HTML 4.0標準に準拠しているため、表とフレームの表示や、Javaアプレットの実行も可能です。ただし、標準のICEbrowserでは、すべての機能を備えたヘルプ・システムにとっていくつかの重要な機能がサポートされません。そのため、オラクル社では、ICEsoft Technologies社の許可を得て、Oracleで開発された規則に対応して次の機能を提供するようにICEbrowserを改良しています。
これらの機能をOHJで使用するには、OHJのデフォルト・バージョンのICEbrowserを使用する必要があります。別のHTML表示コンポーネントを使用すると、これらの機能が動作しません。また、HTMLトピック・ファイルを直接Webブラウザで表示すると、このページに記載されているプロトコルおよびメタデータがブラウザで認識されず、機能が動作しません。
OHWはこれらの機能をサポートします。ただし、プロセスはOHJとは異なります。Oracle Help for the Webヘルプ・システムは、最新のどのWebブラウザでも表示できますが、これらのブラウザでは、このような規則は直接サポートされません。そのため、これらのカスタム機能は、WebサーバーのOHWサーブレットで処理され、標準HTMLリンクやブラウザに固有のJavaScriptとしてユーザーのブラウザに渡されます。
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アンカーの位置にジャンプします。
関連リンクは、複数のターゲットに関連付けられているリンクです。ユーザーがトピックの関連リンクを選択すると、そのリンクに関連付けられているすべてのトピックのリストが表示され、ユーザーはリストからトピックを選択できます。
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項「リンク・ファイル」を参照してください。
Oracle Help for Javaでは、Oracle Helpのcustomプロトコルによって、カスタム・プロトコルのリンクがサポートされています。たとえば、myProtocolというカスタム・プロトコルを使用するリンクは次のように指定します。
<a href="custom:myProtocol:myValue">Link to activate custom protocol</a>
カスタム・プロトコルを定義することは、ヘルプ・システムがアプリケーションにコールバックできる強力な方法です。HelpインスタンスにCustomProtocolHandlerを登録すると、アプリケーションでカスタム・プロトコル・リンクを処理できます。oracle.help.CustomProtocolHandlerの実装を作成し、registerCustomProtocolHandlerメソッドを使用してoracle.help.Helpインスタンスに登録します。このリンクの例では、registerCustomProtocolHandlerメソッドの最初の引数として文字列myProtocolを使用して、CustomProtocolHandlerのインスタンスを登録します。
Oracle Help for Javaは、カスタム・プロトコル・リンクを見つけると、識別子myProtocolを使用して、Helpオブジェクトに登録されているCustomProtocolHandlerを検索します。CustomProtocolHandlerが見つかると、そのhandleValue(String value)メソッドが起動し、値としてmyValueを渡します。
|
注意: 外部URLのリンクを指定する場合、カスタム・プロトコル・ハンドラの登録は必要ありません。OHJには、これに相当する、登録済カスタム・プロトコル たとえば、次のコードでは、OHJブラウザではなくデフォルトのインターネット・ブラウザでOTNページに移動するリンクが作成されます。
|
ポップアップは、Oracle Helpのpopupプロトコルによってサポートされます。次に例を示します。
<a href="popup:sheetdefinition">Sheet Definition</a>
popupプロトコルの後のキーワードは、ヘルプセットのマップ・ファイルで指定されているトピックIDです。ポップアップ・リンクをクリックすると、トピックIDに関連付けられているファイルのコンテンツが軽量ポップアップ・ウィンドウに表示されます。
次に例を示します。
<a href="popup:ohff_popupdemo_html">this link</a>
Oracle HelpトピックIDはマップ・ファイルで保持されているため、Oracle Helpは、トピックIDを参照する必要がある場合にマップ・ファイルのデータを使用します。ただし、トピック・ファイルにトピックIDを指定し、ヘルプセット・オーサリング・ウィザードを使用してトピック・ファイルの情報からマップ・ファイルを生成できます。トピック・ファイルでトピックIDを定義するには、次の構文を使用してMETAタグを挿入します。
<META name="topic-id" content="topic_id_name">
topic_id_nameは、マップ・ファイルで使用されるトピックIDを指定します。
|
注意: サード・パーティのヘルプ・オーサリング・ツールには、マップ・ファイルの生成にMETAタグを使用するものもあります。 |
ヘルプセット・オーサリング・ウィザードの詳細は、第10章「ヘルプセット・オーサリング・ウィザード」を参照してください。
ヘルプセット・ファイルには、サイズ、位置および背景色などの特徴を含む1つ以上の指定ウィンドウを定義できるWinTypeセクションを含めることができます。トピック(およびトピックID)とこれらのウィンドウ・タイプは、マップ・ファイルで関連付けることができるため、トピックが表示される場合は、常に指定したウィンドウに表示されます。
|
注意: ウィンドウ・タイプは、OHJでのみ使用可能です。 |
ヘルプセット・オーサリング・ウィザードを使用する場合は、トピック・ファイル内に含まれるトピックにウィンドウ・タイプを関連付けできますが、それと同時にトピックのtopic-id METAタグでトピックIDも指定する必要があります。OHJオーサリング・ウィザードでは、両方のMETAタグの情報を使用してマップ・ファイルが生成されます。
ウィンドウをトピック・ファイル内のトピックに関連付けるには、次の構文を使用してMETAタグを挿入します。
<META name="window-type" content="window_name">
window_nameは、ヘルプセット・ファイルで定義されているウィンドウの名前です。
|
注意:
|
ヘルプセットで単純な表記規則を使用してトピック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のカスタム実装を記述できます。
多くの場合、ファイル名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を使用できます。この情報をマップ・ファイル内に保持することによって、このマップ・ファイルを、これらの割当てを管理するための集中リポジトリにすることができます。
<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に解決されます。
トピック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を設定しなくてもヘルプ・システムは破損しませんが、パフォーマンスは低下します。
