| Oracle® Fusion Middleware Oracle Help開発者ガイド 11gリリース2 (11.1.2.4.0) B71911-02 |
|
 前 |
 次 |
この章では、OHJとOHWで使用する、トピック・ファイル、トピックIDと関連リンク、ポップアップ、ウィンドウ・タイプおよびカスタム・プロトコル・リンクについて説明します。
この章の構成は、次のとおりです。
トピック・ファイルは、ヘルプ・システムのコンテンツが含まれる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としてユーザーのブラウザにストリーミングされます。
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を渡します。
ポップアップは、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章「ヘルプセット・オーサリング・ウィザード」を参照してください。
ヘルプセット・ファイルには、WinTypeセクションを含めることができます。このセクションでは、サイズ、位置、背景色などの特性を指定して、1つ以上の名前付きウィンドウを定義できます。マップ・ファイルでトピック(およびトピック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を設定しなくてもヘルプ・システムは破損しませんが、パフォーマンスは低下します。
