この章では、OHJとOHWで使用する、トピック・ファイル、トピックIDと関連リンク、ポップアップ、ウィンドウ・タイプおよびカスタム・プロトコル・リンクについて説明します。
この章の構成は、次のとおりです。
トピック・ファイルは、ヘルプ・システムのコンテンツが含まれるHTMLファイルです。このHTMLファイルでサポートされる機能は、ファイルの表示に使用されるブラウザ(またはHTML表示コンポーネント)によって異なります。
OHJに同梱されているHTML表示コンポーネントは、ICEsoft Technologies社のICEbrowserをOracle用に変更したものです。バージョン5.01以上のICEbrowserはHTML 4.0標準に準拠しているため、表やフレームの表示やJavaアプレットの実行が可能です。ただし、標準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>
にlocation属性が設定されることを予期し、マップ・ファイルは解析され、旧バージョンの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
を設定しなくてもヘルプ・システムは破損しませんが、パフォーマンスは低下します。