ヒント、メッセージおよびヘルプの表示

19 ヒント、メッセージおよびヘルプの表示

この章では、shortDesc属性を使用してヒントを表示する方法と、ADF Facesのコンポーネントに対するメッセージを表示する方法を説明します。この章では、ユーザーのために様々なレベルのヘルプ情報を提供する方法も説明します。

この章の内容は次のとおりです。

ヒントおよびメッセージの表示について

ADF Facesには、アプリケーションで情報テキストを表示する際に使用できる多くのコンポーネントが用意されています。たとえば、shortDesc属性を使用すると、ユーザーがカーソルを置いたときにヒント情報を表示でき、inputTextコンポーネントを使用するとユーザーに対するポップアップ・メッセージを表示できます。

ADF Facesでは、様々な方法でアプリケーションに情報テキストを表示できます。精巧なヘルプ・システムだけでなく、簡単なヒント・テキスト、検証および変換のヒント・テキストやエラー・メッセージも作成できます。

図19-1 ADFメッセージング・コンポーネント

ADF Facesの多くのコンポーネントではshortDesc属性がサポートされており、この属性は大部分のコンポーネントで、ユーザーがコンポーネント上にカーソルを置いたときにヒント情報を表示します。図19-2に、ツールバー・ボタンに構成されたヒントを示します。

図19-2 マウスを置いたときにヒントに情報が表示される

ヒントと同様に、ADF Facesのコンポーネントの中にも、たとえばinputTextコンポーネントや選択コンポーネントのように、ポップアップ・ヒント・メッセージや失敗メッセージを表示できるものがあり、検証や変換に使用されます。作成できるメッセージのタイプは2つあります。1つはコンポーネント・レベル・メッセージで、特定のコンポーネントに適用されます。もう1つはグローバル・レベル・メッセージで、特定のページに、またはコンポーネントのグループに適用されます。図19-3に示すヒント・メッセージは、入力日付フィールドに対して構成されています。

図19-3 ヒント・メッセージに入力日付のフォーマットを表示

個々のコンポーネント・インスタンスにメッセージを構成するとともに、アプリケーション全体で再利用可能な情報を提供する個別のヘルプ・システムを作成できます。ヘルプ情報はタイプの異なるプロバイダを使用して作成し、UIコンポーネントからヘルプ・テキストを参照します。次に、ADF Facesでサポートされている3つのタイプのヘルプを示します。

定義: 図19-4に示すように、ユーザーがアイコン上にマウスを置くと、ヘルプ・テキストが表示されるヘルプ・アイコン(疑問符が表示された青い丸)を表示します。

図19-4 アイコン上にマウスを置くと表示される定義メッセージ
説明: このタイプのヘルプはコンポーネントに応じて、(panelHeaderコンポーネントのように)コンポーネント内に説明テキストを表示するか、図19-5に示すように、ユーザーがコンポーネントをクリックした際に開かれる注意ウィンドウにテキストを表示します。テキストの長さの制限はありません。

図19-5 注意ウィンドウに表示されている説明メッセージ
外部URL: 別のブラウザ・ウィンドウで開く、外部アプリケーションに存在するヘルプ・トピックを作成できます。たとえば、図19-6では、説明ヘルプを表示するかわりに、スキンに関するヘルプ・トピックを開くよう構成された、スキン選択のselectOneChoiceコンポーネントが表示されています。ユーザーがselectOneChoiceコンポーネントをクリックすると、ヘルプ・トピックが開きます。

図19-6 新しいウィンドウに開かれている外部URLヘルプ

ヘルプ・システムの作成の詳細は、「コンポーネントへのヘルプの表示」を参照してください。

メッセージング・コンポーネントのユースケースおよび例

通常、メッセージは、アプリケーションでエラーが発生した場合(ユーザーが互換性のない情報を入力した場合など)に表示されるエラー・メッセージのタイプと、コンポーネントの使用やページでのタスクの完了に関するヒントなどを提供する情報メッセージのタイプに分けられます。

情報メッセージは、単純なツールチップから複雑なヘルプ・システムまで多岐にわたります。ヒントまたは情報を表示するコンポーネントでヘルプ・テキストがサポートされていない場合には、ツールチップを使用する必要があります。ただし、ツールチップ・テキストは簡潔にする必要があります。より詳細な情報を表示する必要がある場合、または多数のコンポーネント・インスタンス間でテキストが再利用される場合は、ヘルプ・テキストの使用を検討してください。

ツールチップは、コンポーネントにshortDesc属性を構成して作成します。これで、ユーザーがコンポーネントにカーソルを置くかコンポーネントをクリックしたときに(たとえばinputTextコンポーネントの場合)、その属性の値がノート・ウィンドウに表示されるようになります(図19-7を参照)。

図19-7 コンポーネントのツールチップ

ツールチップの詳細は、「コンポーネントのヒントの表示」を参照してください。

エラー・メッセージでは、JSFメッセージングAPIが使用されます。エラー・メッセージには、メッセージが特定コンポーネントにのみ当てはまるコンポーネント・メッセージと、複数のコンポーネントやページ全体に当てはまるグローバル・メッセージの2つのタイプがあります。

デフォルトでは、noteWindowコンポーネントはコンポーネント・エラー・メッセージに使用されます。入力コンポーネントに変換や検証を構成すると、noteWindowコンポーネントに、検証および変換のヒントやエラーが自動的に表示されます。ページにコンポーネントを追加する必要はありません。

たとえば、File Explorerアプリケーションでユーザーが「Help」 > 「Give Feedback」をクリックすると、カスタマ・サービスの担当者が連絡する日時を入力可能なダイアログが表示されます。inputDateコンポーネントにはコンバータが含まれているため、ユーザーがフィールドをクリックすると、図19-8に示すように、予想されるパターンを示すヒントが注意ウィンドウに表示されます。inputDateコンポーネントに最小値または最大値も構成されている場合は、その情報もヒントに表示されます。これらのヒントは、コンバータおよびバリデータにより自動的に表示されます。

図19-8 アタッチされている、メッセージを含むコンバータおよびバリデータ

図19-8に表示されているフィールドにユーザーが入力した日付が正しくない場合は、図19-9に示すようにエラー・メッセージが表示されます。エラー・メッセージは、ヒントともに注意ウィンドウに表示されることに注意してください。

図19-9 注意ウィンドウに表示されている検証および変換のエラー

ADF Facesコンポーネント以外にエラー・メッセージを表示する場合、または注意ウィンドウではなく、インラインでメッセージを表示する場合は、ADF Faces messageコンポーネントを使用します。このコンポーネントを使用するときは、メッセージはコンポーネントの隣に表示されます(図19-10を参照)。

図19-10 messageコンポーネントを使用したメッセージのインラインでの表示

グローバル・メッセージはデフォルトで、図19-11に示すように、ダイアログ内に表示されます。ページにポップアップ・コンポーネントを追加する必要はありません。

図19-11 ポップアップ・ウィンドウに表示されているグローバル・メッセージ

エラー・メッセージをページに直接表示する場合は、messagesコンポーネントを使用します。このコンポーネントを使用すると、図19-12に示すように、ページ上部のリストにメッセージが表示されます。

図19-12 messagesコンポーネントを使用した、ページへのグローバル・メッセージの表示

エラー・メッセージの詳細は、「検証および変換用のヒントとエラー・メッセージの表示」を参照してください。

ツールチップに収まる量を超える情報を表示する必要がある場合は、定義ヘルプを使用します。定義ヘルプを構成すると、大部分のコンポーネントで、そのコンポーネントの隣にヘルプ・アイコンが表示されます。図19-13に示すように、コンポーネント上にマウスが置かれると、ヘルプ・テキストが表示されます。

図19-13 列コンポーネントの定義ヘルプ

定義ヘルプの詳細は、「コンポーネントへのヘルプの表示」を参照してください。

フィールドレベル・ヘルプを表示する場合は、説明テキストを使用するように入力コンポーネントを構成します。ユーザーがコンポーネントをクリックすると、図19-14に示すように、注意ウィンドウにヘルプ・テキストが表示されます。

図19-14 コンポーネントの説明テキスト

タスクの説明を表示する場合は、コンテナ・コンポーネントに説明ヘルプを構成します。図19-15に示すように、コンポーネントのヘッダーにテキストが表示されます。

図19-15 panelHeaderコンポーネントの説明テキスト

ベスト・プラクティス:

入力コンポーネントの説明テキストは、説明なしでは、通常のユーザーがタスクに失敗する可能性がある場合にのみ使用します。説明テキストを多用すると、ページが指示で煩雑になったり、関連するページ要素が注意ウィンドウで見えにくくなり、ユーザーの注意が散漫になったりします。

複雑なヘルプを作成する必要がある場合は、ヘルプ・アイコンを使用して、URLを介してアクセス可能な外部ヘルプ・システムにリンクできます。

説明および外部ヘルプの詳細は、「コンポーネントへのヘルプの表示」を参照してください。

メッセージ・コンポーネントのその他の機能

メッセージ・コンポーネントおよびヘルプ機能を実装する前に、ADF Facesのその他の機能を理解しておくと役に立ちます。また、ページにこれらのコンポーネントを追加してから、アイコンを変更するためのスキニング、アクセシビリティ、およびメッセージ・テキストを格納するためのリソース・バンドルの使用などの機能の追加が必要なことに気が付く場合もあります。次に、メッセージ・コンポーネントで使用できるその他の機能へのリンクを示します。

テキストでのパラメータの使用: コンポーネントに表示されるテキストに、実行時に解決されるパラメータを含める場合は、ADF Faces EL書式タグを使用できます。「EL書式タグの使用方法」を参照してください。
クライアント・イベント: JavaScriptを使用してヘルプ・トピックを起動する場合は、クライアント・イベントにリスナーを使用します。クライアント側イベントの詳細は、「ADF Facesクライアント・イベントに対するJavaScriptの使用」を参照してください。
スキニング: メッセージおよびヘルプに表示されるアイコンは、アプリケーションに使用されているスキンによって決まります。アイコンは、新しいスキンを作成することで変更できます。「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。
ローカライゼーション: メッセージに直接テキストを入力するかわりに、プロパティ・ファイルを使用できます。これらのファイルにより、これらの文字列の翻訳を管理できます。「ページの国際化およびローカライズ」を参照してください。

コンポーネントのヒントの表示

ADF Facesのコンポーネントに用意されているshortDescを使用すると、ヒント、ノート、ポップアップ・メッセージなどで短いテキストを表示できます。このテキストは、ユーザーがinputTextコンポーネントにカーソルを置いたときに表示されます。

ADF Facesコンポーネントでは、ユーザーがコンポーネント上にマウスを置いた場合、shortDesc属性を使用してヒントが表示されます。入力コンポーネントでは、注意ウィンドウにヒントが表示されます。その他のコンポーネント・タイプでは、標準のヒント・ボックスにヒントが表示されます。このテキストは短くする必要があります。より詳細な情報を表示する必要がある場合、または多数のコンポーネント・インスタンス間でテキストが再利用される場合は、「コンポーネントへのヘルプの表示」で説明されているように、ヘルプ・テキストの使用を検討してください。

図19-16に、inputTextコンポーネント上にカーソルが置かれた際の様子を示します。

図19-16 inputTextコンポーネントのヒント

図19-17に、showDetailItemコンポーネントに表示されたヒントを示します。

図19-17 showDetailItemコンポーネントのヒント

コンポーネントへのヒントの表示方法

ヒントを表示するには、コンポーネントにshortDesc属性を使用します。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。「コンポーネントのヒントの表示」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。「メッセージ・コンポーネントのその他の機能」を参照してください。

コンポーネントにヒントを定義する手順:

構造ウィンドウで、ヒントを表示するコンポーネントを選択します。
「プロパティ」ウィンドウの「外観」セクションを開き、shortDesc属性の値を入力します。

ヒント

80文字を超えると、ブラウザによってはヒントが切り捨てられてしまうため、値は80文字未満にする必要があります。

使用するテキストがリソース・バンドルに格納されている場合は、ドロップダウン・リストを使用して「テキスト・リソースの選択」を選択します。「テキスト・リソースの選択」ダイアログを使用して、既存のバンドル内の適切なテキストを検索するか、既存のバンドル内に新しいエントリを作成します。リソース・バンドルの使用方法の詳細は、「ページの国際化およびローカライズ」を参照してください。

検証および変換用のヒントとエラー・メッセージの表示

ADF Facesでは、ユーザーに値の検証を許可した場合、または値が変換される場合に、適切な値を使用するよう促すデフォルトのエラー・メッセージとヒントが表示されます。ただし、バリデータとコンバータのデフォルトのヒントとエラー・メッセージはオーバーライドできます。

バリデータおよびコンバータには、関連するフィールドがクリックされた際にユーザーに表示されるデフォルトのヒントがあります。デフォルトのヒントは自動的にノート・ウィンドウに表示されます。コンバータの場合、ヒントは、使用する適切な書式をユーザーに示します。バリデータの場合、ヒントは有効な値を示すために使用されます。

たとえば、図19-18に示すように、File Explorerアプリケーションでは、ユーザーが「カスタマ・サービスに連絡」ページの日付入力フィールドをクリックすると、使用する正しい書式が示されたヒントが表示されます。

注意:

入力フィールドに関するヒントはすべて、コンテキスト・パラメータoracle.adf.view.rich.component.DEFAULT_HINT_DISPLAYをnoneに設定してオフにできます。デフォルトでは、このパラメータはautoに設定されており、コンポーネント・ヒントの表示モードはフレームワークで決定できるようになっています。デフォルトの動作では、コンポーネントがフォーカスを取得したときに、ノート・ウィンドウ・ヒントとして表示されます。

図19-18 組込みメッセージのあるバリデータおよびコンバータ

ADF Facesコンポーネントの値が検証に失敗した場合、またはコンバータで変換できない場合は、コンポーネントに結果のFacesMessageインスタンスが表示されます。

たとえば、図19-19に示されているように、コンバータのdateStyle属性に一致しない日付を入力すると、エラー・メッセージが表示されます。

図19-19 実行時の検証エラー

デフォルトのバリデータおよびコンバータのヒントとエラー・メッセージを、1つのコンポーネント・インスタンスに対して、またはすべてのインスタンスに対してグローバルにオーバーライドできます。コンポーネント・インスタンスにカスタム・メッセージを定義するには、表示する詳細なメッセージに属性を設定します。実際の属性は、バリデータまたはコンバータによって異なります。図19-20に表示されている属性の値を入力すると、「プロパティ」ウィンドウに表示される、convertDateTimeコンバータのメッセージがオーバーライドされます。

図19-20 コンバータのメッセージ属性

「図19-20 コンバータのメッセージ属性」の説明

コンポーネントのすべてのインスタンスで使用されるエラー・メッセージを定義するには、デフォルト・メッセージをオーバーライドするリソース・バンドルにエントリを作成する必要があります。

注意ウィンドウにメッセージを表示しない場合は、messageコンポーネントを使用すると、メッセージがコンポーネントにインラインで表示されます。図19-21に、messageコンポーネントを使用してメッセージがどのように表示されるかを示します。

図19-21 messageコンポーネントを使用したメッセージのインラインでの表示

ADF FacesアプリケーションのJSFページでは、特にポップアップ・ウィンドウへのすべてのグローバル・メッセージ(コンポーネントに関連付けられていないメッセージ)の表示を処理するdocumentタグが使用されています。ただし、グローバル・メッセージをページに表示する場合は、messagesコンポーネントを使用します。

注意:

HTMLタグを使用してメッセージの書式を設定するには、メッセージを<html></html>タグで囲む必要があります。次に例を示します。

<html>error message details</html>

エラー・メッセージでは、次のHTMLタグを使用できます。



<a>


 
<hr>
<li>
<ol>
<ul>

<tt>
<big>

<pre>

コンポーネント・インスタンスへのバリデータおよびコンバータのカスタム・メッセージの定義方法

単一のコンポーネント・インスタンスのデフォルトのバリデータおよびコンバータのメッセージをオーバーライドするには、異なるメッセージ属性に値を設定します。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。「検証および変換用のヒントとエラー・メッセージの表示」を参照してください。

バリデータまたはコンバータのメッセージを定義する手順:

構造ウィンドウで、エラー・メッセージを作成するコンバータまたはバリデータを選択します。
「プロパティ」ウィンドウの「メッセージ」セクションを開き、メッセージを表示する属性の値を入力します。
値には、{0}、{1}、{2}などのパラメータ・プレースホルダを使用して、動的コンテンツを含めることができます。たとえば、convertDateTimeコンバータのmessageDetailConvertDate属性には、次のパラメータが使用されます。
- {0}: コンポーネントを識別するラベル
- {1}: ユーザーによって入力される値
- {2} : コンポーネントで想定される書式の例
ヒント:
- アプリケーションで双方向または右から左への表示を使用する場合は、想定書式パラメータ{2}をメッセージの先頭に置かないでください。Internet Explorerでは正しく表示されない可能性があるからです。
- 書式パラメータ{1}をメッセージ内に表示することはできるだけ避けてください。ユーザー入力を表示することは、セキュリティ違反とみなされることがあります。
これらのパラメータを使用すると、次のメッセージを作成できます。
```
The date you have entered in the \"{0}\" field is not using the correct date format. Please enter the date as follows: {2}. 
```
エラー・メッセージは、図19-22のように表示されます。コンバータのType属性の値をパラメータに合せて変更することが必要になる可能性があります。

図19-22 実行時の詳細なメッセージ

ヒント

メッセージで使用されたパラメータを含むプロパティ・ヘルプを表示するには、ドロップダウン・メニューを使用します。

使用するテキストがリソース・バンドルに格納されている場合は、ドロップダウン・リストを使用して「テキスト・リソースの選択」を選択します。「テキスト・リソースの選択」ダイアログを使用して、既存のバンドル内の適切なテキストを検索するか、既存のバンドル内に新しいエントリを作成します。リソース・バンドルの使用方法の詳細は、「ページの国際化およびローカライズ」を参照してください。

注意:

メッセージ・テキストは、FacesMessageオブジェクトの詳細なメッセージ用です。サマリー(メッセージの上部に表示されるテキスト)をオーバーライドする場合は、グローバルにのみ実行できます。「コンポーネントの全インスタンスのバリデータおよびコンバータのカスタム・メッセージの定義方法」を参照してください。

コンポーネントの全インスタンスのバリデータおよびコンバータのカスタム・メッセージの定義方法

messageDetail[XYZ]属性を使用してコンポーネント・インスタンスごとにメッセージの文字列を変更するかわりに、カスタム文字列がすべてのインスタンスに表示されるように文字列をグローバルにオーバーライドできます。グローバル・メッセージは、メッセージ・バンドルのキーと値のペアによって処理されます。サマリー、詳細およびヒント・メッセージをオーバーライドできます。

デフォルトのバリデータまたはコンバータのメッセージをグローバルにオーバーライドする手順:

オーバーライドするメッセージのメッセージ・キーを定義するには、「コンバータおよびバリデータ・メッセージのメッセージ・キー」を参照してください。たとえば、入力値が最大の値の長さを超えた場合に表示される詳細メッセージをオーバーライドするには、「af:validateLength」に示すように、キーorg.apache.myfaces.trinidad.validator.LengthValidator. MAXIMUM_detailを使用します。
メッセージ・バンドルを作成するか開きます。メッセージ・バンドルを作成する手順は、「リソース・バンドルをプロパティ・ファイルまたはXLIFFファイルとして作成する方法」を参照してください。
メッセージ・バンドルにキー・オーバーライドを追加します。たとえば、入力値の長さに関するメッセージをオーバーライドするには、次のような内容を追加します。
```
org.apache.myfaces.trinidad.validator.LengthValidator.MAXIMUM_detail: Your value exceeds the limit.
```
メッセージ・バンドルが新しいリソース・バンドルである場合、「アプリケーションへのリソース・バンドルの登録方法」の手順に従い、faces-config.xmlファイルを使用して、バンドルをアプリケーションに登録する必要があります。ただし、<resource-bundle>タグではなく、<message-bundle>タグを使用します。

コンポーネントのメッセージをインラインで表示する方法

コンポーネントで注意ウィンドウにメッセージを表示するかわりに、messageコンポーネントを使用して、ページにインラインでメッセージを表示できます。messageコンポーネントで正しいメッセージが表示されるようにするには、特定のコンポーネントと関連付けます。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。「検証および変換用のヒントとエラー・メッセージの表示」を参照してください。

コンポーネントのメッセージをインラインで表示する手順:

構造ウィンドウで、messagesコンポーネントを使用してメッセージを表示するコンポーネントを選択します。まだ設定されていない場合は、コンポーネントのIDを入力します。
「コンポーネント」ウィンドウの「テキストおよび選択」パネルから、「メッセージ」をドラッグし、ページ上のメッセージを表示する場所にドロップします。
ドロップダウン・メニューを使用してfor属性に「編集」を選択します。
「プロパティの編集」ダイアログで、messagesコンポーネントでメッセージを表示するコンポーネントを探します。IDの設定されているコンポーネントのみが有効な選択肢です。

注意:

表示されるメッセージ・アイコンとメッセージ・コンテンツは、FacesMessageオブジェクトの作成時に指定されたものに基づきます。messageコンポーネントにmessageTypeまたはmessage属性を設定すると、エラーが発生したかどうかに関係なく、実行時にmessageTypeまたはmessage属性の値が表示されます。これらの属性は、ページのレンダリング時に必ずコンテンツを表示する場合にのみ移入します。

グローバル・メッセージをインラインで表示する方法

グローバル・メッセージをページのポップアップ・ウィンドウに表示するかわりに、messagesコンポーネントを使用してインラインで表示します。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。「検証および変換用のヒントとエラー・メッセージの表示」を参照してください。

グローバル・メッセージをインラインで表示する手順:

「コンポーネント」ウィンドウの「テキストおよび選択」パネルから、「メッセージ」をドラッグし、ページ上のメッセージを表示する場所にドロップします。
「プロパティ」ウィンドウで次の属性を設定します。
- globalOnly: デフォルトでは、ADF Facesはグローバル・メッセージ(コンポーネントに関連付けられていないメッセージ)を表示し、次に個々のコンポーネントのメッセージを表示します。ボックスにグローバル・メッセージのみを表示する場合は、この属性をtrueに設定します。コンポーネント・メッセージは、関連付けられたコンポーネントに引き続き表示されます。
- inline: ページの上部にメッセージを表示する場合にtrueに設定します。そうしない場合、メッセージはダイアログに表示されます。

実行時の処理: メッセージの表示

ADF Facesでは、標準のJSFメッセージングAPIが使用されています。JSFでは、addMessage(java.lang.String clientId, FacesMessage message)メソッドを使用してFacesContextオブジェクトにFacesMessageインスタンスを追加できるようにすることで、メッセージング用の組込みのフレームワークがサポートされています。コンポーネント・レベルのメッセージは、特定のコンポーネントに関連付けられます。この関連付けの基準になるのは、addMessageメソッドに渡されたクライアントIDです。グローバル・レベルのメッセージには、コンポーネントは関連付けられません。addMessageメソッドにクライアントIDは渡されないからです。

EditableValueHolder ADF Facesコンポーネントで変換または検証が失敗すると、FacesContextインスタンスのメッセージ・キューにFacesMessagesオブジェクトが自動的に追加され、コンポーネントのIDが渡されます。これらのメッセージは、コンポーネントの注意ウィンドウに表示されます。ADF Facesコンポーネントには、独自のメッセージを表示できます。タグを追加する必要はありません。

FacesMessagesコンポーネントのみでなく、documentタグも、すべてのグローバルなFacesMessagesオブジェクト(関連付けられているコンポーネントIDがない)の処理および表示を行います。コンポーネント・メッセージと同様に、メッセージを表示するために開発者がタグを追加する必要はありません。グローバル・メッセージ(または複数のコンポーネント・メッセージ)が作成されると、キュー内のすべてのメッセージがポップアップ・ウィンドウに表示されます(図19-23を参照)。

図19-23 documentにより表示されるグローバル・メッセージおよびコンポーネント・メッセージ

ヒント

ADF Facesには検証および変換用のメッセージがありますが、標準のJSFメッセージングAPIを使用して、キューにFacesMessagesオブジェクトを追加できます。追加すると、ADF Facesにより、メッセージ・レベルに基づいて、次のようなアイコンがメッセージとともに表示されます。

単一のラベルおよびメッセージを使用したコンポーネントのグループ化

ADF Faces panelLabelAndMessageコンポーネントを使用すると、コンポーネントをグループ化して1つのラベルを使用できます。この属性を使用すれば、任意のコンポーネントをグループ化し、そのグループに1つのラベルを使用できます。

ADF Facesの入力および選択コンポーネントには、デフォルトで、ラベルおよびメッセージの表示用に組込みサポートが用意されています。コンポーネントをグループ化して単一のラベルを使用する場合は、panelLabelAndMessageコンポーネントを使用してコンポーネントをラップします。

たとえば、File Explorerアプリケーションでは、別々のinputTextコンポーネントを4つ(市外局番、市内局番、最後の4桁、および内線のそれぞれに1つずつ)使用して電話番号を収集します。単一のラベルが必要なため、4つのinputTextコンポーネントはpanelLabelAndMessageコンポーネントにラップされ、ラベルの値はそのコンポーネントに設定されます。ただし、内線の入力コンポーネントには追加のラベルが必要なため、outputTextコンポーネントが使用されます。次の例に、panelLabelAndMessageコンポーネントのJSFコードを示します。

<af:panelLabelAndMessage labelAndAccessKey="#{explorerBundle['help.telephone']}"
                         helpTopicId="HELP_TELEPHONE_NUMBER"
                         labelStyle="vertical-align: top;  
                         padding-top: 0.2em;">
  <af:inputText autoTab="true" simple="true" maximumLength="3"
                columns="3">
    <af:convertNumber type="number" integerOnly="true"/>
  </af:inputText>
  <af:inputText autoTab="true" simple="true" maximumLength="3"
                columns="3">
    <af:convertNumber type="number" integerOnly="true"/>
  </af:inputText>
  <af:inputText autoTab="true" simple="true" maximumLength="4"
                columns="4">
    <af:convertNumber type="number" integerOnly="true"/>
  </af:inputText>
  <af:outputText value="#{explorerBundle['help.extension']}"/>
  <af:inputText simple="true" columns="4">
    <af:convertNumber type="number" integerOnly="true"/>
  </af:inputText>
</af:panelLabelAndMessage>

図19-24に、panelLabelAndMessageおよびネストしたコンポーネントがブラウザにどのように表示されるかを示します。

図19-24 panelLabelAndMessageコンポーネントの使用例

「図19-24 panelLabelAndMessageコンポーネントの使用例」の説明

panelLabelAndMessageコンポーネントには、グループの最後に追加のコンポーネントを表示するために使用できるEndファセットも含まれます。図19-25に、EndファセットにoutputTextコンポーネントが移入されている場合に、電話番号フィールドがどのように表示されるかを示します。

図19-25 panelLabelAndMessageコンポーネント内のEndファセット

panelLabelAndMessageコンポーネント内にpanelGroupLayoutコンポーネントを使用して、必要なレイアウトのコンポーネントをグループ化します。panelGroupLayoutコンポーネントの使用方法の詳細は、「関連する項目のグループ化」を参照してください。

各入力コンポーネントでsimple属性をtrueに設定し、個々のラベルが表示されないようにします。ただし、メッセージ目的およびアクセシビリティ用の各コンポーネントのラベル属性に値を設定することが必要な場合があります。

ヒント

複数のpanelLabelAndMessageコンポーネントを連続して使用する必要がある場合には、ラベルが適切に配置されるよう、af:panelFormLayoutコンポーネントにラップします。panelFormLayoutコンポーネントの使用方法の詳細は、「フォームでのコンテンツの配置」を参照してください。

panelLabelAndMessageコンポーネントを使用して、コンポーネントをグループ化してラップします。panelLabelAndMessageコンポーネントは、通常メッセージやラベルを表示するコンポーネントのみでなく、任意のコンポーネントのラップに使用できます。

単一のラベルおよびメッセージを使用したコンポーネントのグループ化方法

コンポーネントをグループ化し、そのグループに単一のラベルを表示するには、panelLabelAndMessageコンポーネントを使用します。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。「単一のラベルおよびメッセージを使用したコンポーネントのグループ化」を参照してください。

単一のラベルおよびメッセージを使用してフォーム入力コンポーネントを配置する手順:

必要に応じて、入力コンポーネントまたは選択コンポーネントをページに追加します。

各入力および選択コンポーネントに次の設定を行います。
- simple属性をtrueに設定します。
- アクセシビリティの理由から、label属性をコンポーネントのラベルに設定します。
「構造」ウィンドウで、ステップ1で作成した入力または選択のコンポーネントを選択します。選択内容を右クリックし、「囲む」→「パネル・ラベルとメッセージ」を選択します。
panelLabelAndMessageコンポーネントが選択されている状態で、「プロパティ」ウィンドウで次のとおりに設定します。
- label: コンポーネントのグループに表示するラベル・テキストを入力します。
- for: ドロップダウン・メニューを使用して「編集」を選択します。「プロパティの編集」ダイアログで、子入力コンポーネントのIDを選択します。入力コンポーネントが複数ある場合は、最初のコンポーネントを選択します。
  
  アクセシビリティ要件に一致するように、for属性を最初のinputComponentに設定します。
ネストした入力コンポーネントの1つ以上が必須コンポーネントで、これを示すためにマーカーを表示する場合は、showRequired属性をtrueに設定します。
Endファセットにコンテンツを配置するには、必要なコンポーネントをファセットにドラッグ・アンド・ドロップします。

JSPまたはJSPX上のファセットに配置できる子コンポーネントは1つのみであるため、複数の子コンポーネントを追加する場合は、子コンポーネントをコンテナ(たとえばpanelGroupLayoutまたはgroupコンポーネント)の内側にラップする必要があります。Faceletページ上のファセットには、複数のコンポーネントを配置できます。
ヒント

ファセットがビジュアル・エディタに表示されない場合は、次のようにします。
1. 構造ウィンドウで、panelLabelAndMessageコンポーネントを右クリックします。
2. ポップアップ・メニューから、「ファセット - パネル・ラベルおよびメッセージ」→「facet name」を選択します。ページで使用されているファセットは、ファセット名の前にチェックマークが表示されます。

コンポーネントへのヘルプの表示

ADF Facesでは、ヘルプ・メッセージの表示形式を説明ヘルプ、定義ヘルプおよび外部URLヘルプの3つで表示できます。外部ソースからのヘルプ・テキストが表示されます。

ADF Facesには、タイプの異なる3つのヘルプを作成および表示できるフレームワークが用意されており、そのコンテンツは、コンポーネントに構成されたテキストではなく、外部ソースから取得されます。コンテンツがコンポーネントに直接構成されず、複数のコンポーネントに使用できるため、ページ作成時間の節約になり、コンテンツが表示されるすべての場所ではなく、1箇所のコンテンツを変更することも可能です。

ヘルプ・メッセージの表示形式は、説明ヘルプ、定義ヘルプおよび外部URLヘルプの3つがあります。

説明ヘルプ

説明ヘルプとは、フォーカスがコンポーネントにあるときにヘルプ・テキストをノート・ウィンドウに表示するものです。図19-26に、ノート・ウィンドウに表示されているヘルプ・メッセージを示します。

図19-26 コンポーネントの説明テキスト

通常、説明ヘルプはそのコンポーネントの使用方法を説明するために使用します。HTMLタグを使用してヘルプ・メッセージの書式を設定することもできますが、すべてのHTMLタグがサポートされているわけではありません(サポートされるHTMLタグについては、af:outputFormattedコンポーネントのタグの説明を参照してください)。図19-27に、ノート・ウィンドウに表示されているHTML書式設定されたヘルプ・メッセージを示します。

図19-27 HTML書式設定された説明ヘルプ

コンポーネントによっては、説明ヘルプがコンポーネント内の説明として表示されることがあります。説明ヘルプが表示される場所は、関連付けられているコンポーネントによって異なります。たとえば、panelHeaderコンポーネントや検索パネル・コンポーネントでは説明ヘルプがヘッダーの中に表示されます(図19-28を参照)。

図19-28 panelHeaderの説明テキスト

表19-1に、説明ヘルプがサポートされているコンポーネントを示します。

表19-1 説明ヘルプがサポートされているコンポーネント

サポートされているコンポーネント	ヘルプの位置	例
入力コンポーネント、色の選択、日付の選択、クイック問合せ	注意ウィンドウ(フォーカスがある場合のみ)
コンポーネントの選択	注意ウィンドウ(マウスが置かれている場合とフォーカスがある場合)
パネル・ヘッダー、パネル・ボックス、問合せ	ヘッダー・テキストの下のテキスト

定義ヘルプ

定義ヘルプは、メッセージ・ボックスに表示される点が標準のヒントに似ています。ただし、ユーザーがコンポーネント上にマウスを置いたときにヘルプそのものが表示されるのではなく、定義ヘルプの場合はヘルプ・アイコン(疑問符付きの青い円)が表示されます。または、テキストの下に点線を表示させるかわりにスキニング属性を使用することができます(「スキニングおよび定義ヘルプに関する必知事項」を参照してください)。ユーザーがこのアイコンにマウスを置くと、コンテンツが図19-29のように表示されます。

図19-29 コンポーネントの定義テキスト

ヒント・メッセージではHTMLの書式設定がサポートされないことと、ヒント・メッセージの長さは80文字未満でなければならないことに注意してください。古いバージョンのブラウザでは、長いメッセージがサポートされないことがあるからです。表19-2に、定義ヘルプがサポートされるコンポーネントを示します。

表19-2 定義ヘルプがサポートされているコンポーネント

サポートされているコンポーネント	ヘルプ・アイコンの位置	例
すべての入力コンポーネント、選択コンポーネント、色の選択、日付の選択、問合せコンポーネント	ラベルの前。ラベルが存在しない場合は、フィールドの先頭。
パネル・ヘッダー、パネル・ボックス、詳細の表示ヘッダー	ヘッダー・テキストの最後。
パネル・ウィンドウ、ダイアログ	ヘッダーの「閉じる」アイコンの隣。
表およびツリーの列	ヘッダー・テキストの下

外部URLヘルプ

外部URLヘルプを利用すると、ヘルプのコンテンツが掲載されている既存のWebページにリンクすることができます。ヘルプ・アイコンがクリックされると、Webページが別のブラウザ・ウィンドウで開きます(図19-30を参照)。JavaScriptを使用して、任意のクライアント・ベースのイベントに基づいてヘルプ・ウィンドウを開くこともできます。

図19-30 外部URLヘルプ

JavaScriptを使用して、ヘルプ・アイコンではなく外部ヘルプを開く方法の詳細は、「外部ヘルプ・ウィンドウを起動するためのJavaScriptの使用方法」を参照してください。

ヘルプ・プロバイダ

ヘルプ・プロバイダとは、アプリケーションのヘルプのテキスト(外部ヘルプの場合はURL)を格納するものであり、META-INF/adf-settings.xmlファイル内で登録されます。ADF Facesでは、次に示すヘルプ・プロバイダが説明ヘルプおよび定義ヘルプに対してサポートされます。

ResourceBundleHelpProviderヘルプ・プロバイダを使用すると、ヘルプ・コンテンツを保持するリソース・バンドルを作成できます。
ELHelpProviderヘルプ・プロバイダを使用すると、マップに変換されるXLIFFファイルを作成できます。
ヘルプ・テキストの文字列のマップが格納されているマネージドBean。

外部URLヘルプでは、getExternalURLメソッドを実装するクラスが使用されます。

ヘルプ・プロバイダの作成の詳細は、「ヘルプ・プロバイダの作成方法」を参照してください。

複数のヘルプ・プロバイダの組合せを使用することや、独自のヘルプ・プロバイダ・クラスを作成することもできます。

ヘルプの作成

ヘルプ・メッセージを作成するには、次の手順を実行します。

説明ヘルプおよび定義ヘルプの場合は、使用するヘルプ・プロバイダのタイプ(リソース・バンドル、XLIFFファイルまたはマネージドBean)を決定してから、必要なアーティファクトを実装します。このヘルプ・プロバイダに実際のヘルプ・テキストが格納されます。「ヘルプ・プロバイダの作成方法」を参照してください。
外部ヘルプの場合は、外部コンテンツへのURLが格納される外部ヘルプ・プロバイダを作成する必要があります。「外部URLヘルプ・プロバイダを作成する方法」を参照してください。
ヘルプ・プロバイダを登録し、一意の接頭辞を指定します。この接頭辞は、このプロバイダのヘルプへのアクセスに使用されます。「ヘルプ・プロバイダの登録方法」を参照してください。
コンポーネントのhelpTopicId属性を使用して、UIコンポーネントがプロバイダに含まれるヘルプにアクセスできるようにします。helpTopicId属性には、次の情報が格納されます。
- ヘルプ・プロバイダにより使用される接頭辞
- トピック名
「UIコンポーネントからのヘルプ・コンテンツへのアクセス方法」を参照してください。
外部URLヘルプの場合は、ユーザーがヘルプ・アイコンをクリックしたときではなく、イベントへの応答としてヘルプ・ウィンドウを起動することもできます。「外部ヘルプ・ウィンドウを起動するためのJavaScriptの使用方法」を参照してください。

ヘルプ・プロバイダの作成方法

ヘルプ・プロバイダの作成手順は、作成するヘルプ・プロバイダのタイプによって異なります。説明ヘルプおよび定義ヘルプの場合は、リソース・バンドル、XLIFFファイルまたはマネージドBeanを使用できます。外部URLヘルプの場合は、Javaクラスを作成します。カスタム・ヘルプ・プロバイダを作成することもできます。

リソース・バンドル・ベースのプロバイダの作成方法

ResourceBundleHelpProviderクラスによって、基本的なHelpProviderインスタンスが作成されます。標準のリソース・バンドル・プロパティ・ファイルにヘルプ・テキストを格納し、ResourceBundleHelpProviderクラスを使用してコンテンツを送信できます。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。「コンポーネントへのヘルプの表示」を参照してください。

リソース・バンドルベースのヘルプを作成する手順:

各ヘルプ・トピックのトピックIDおよびヘルプ・テキストを含むプロパティ・ファイルの作成トピックIDには次の情報が含まれている必要があります。
- このプロバイダで使用される接頭辞(たとえばBUNDLE)。
- トピック名(たとえばPHONE_NUMBER)。
- DEFINITIONなどのヘルプ・タイプ
トピックIDは、たとえばBUNDLE_PHONE_NUMBER_DEFINITIONとなります。

複数のヘルプ・プロバイダを使用する場合は、必ずヘルプ・プロバイダのそれぞれに一意の接頭辞を使用してください。

注意:

ヘルプ・プロバイダが登録されているすべての接頭辞は一意であることが必要です。また、別の接頭辞と同じ文字で接頭辞を開始することはできません。たとえば、AABおよびACの2つの接頭辞にヘルプ・プロバイダが登録されている場合、AABC、A、AA、AC、ACBという接頭辞はすべて無効で、登録時に例外がスローされます。ただし、AAD、ABなどは有効です。

UIコンポーネントはトピック名に基づいてヘルプ・コンテンツにアクセスします。したがって、同じトピック名が2つの異なるタイプのヘルプに使用されている場合は、両方のタイプのヘルプがUIコンポーネントによって表示されます。

次の例に、2つのトピックIDを持つリソース・バンドルのプロパティ・ファイルの例を示します。
```
BUNDLE_CUST_SERVICE_EMAIL_DEFINITION=For security reasons, we strongly discourage the submission of credit card numbers.
BUNDLE_PHONE_NUMBER_DEFINITION=We only support calling phone numbers in the United States at this time.
```
リソース・バンドルをヘルプ・プロバイダとしてadf-settings.xmlファイル内で登録してから、ヘルプを使用するようにADF Facesのコンポーネントを構成します。「ヘルプ・プロバイダの登録方法」および「UIコンポーネントからのヘルプ・コンテンツへのアクセス方法」を参照してください。

XLIFFプロバイダの作成方法

XLIFF XMLファイルにヘルプ・テキストを格納し、ELHelpProviderクラスを使用してコンテンツを送信できます。このクラスでは、XLIFFファイルが、ヘルプのテキストとして使用される文字列のマップに変換されます。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。「コンポーネントへのヘルプの表示」を参照してください。

XLIFFヘルプを作成する手順:

<body>タグ内に次の要素を使用して、ヘルプ・テキストを定義するXLIFFファイルを作成します。
- <trans-unit>: トピックIDを入力します。これには、接頭辞、トピック名およびヘルプ・タイプが含まれている必要があります。たとえば、HELP_PHONE_NUMBER_DEFINITIONです。この例では、HELPがXLIFFファイルへのアクセスに使用される接頭辞となります。PHONE_NUMBERがトピック名で、DEFINITIONがヘルプのタイプです。複数のヘルプ・プロバイダを使用する場合は、必ずヘルプ・プロバイダのそれぞれに一意の接頭辞を使用してください。
 
 注意:
 
 ヘルプ・プロバイダが登録されているすべての接頭辞は一意であることが必要です。また、別の接頭辞と同じ文字で接頭辞を開始することはできません。たとえば、AABおよびACの2つの接頭辞にヘルプ・プロバイダが登録されている場合、AABC、A、AA、AC、ACBという接頭辞はすべて無効で、登録時に例外がスローされます。ただし、AAD、ABなどは有効です。
 
 UIコンポーネントはトピック名に基づいてヘルプ・コンテンツにアクセスします。したがって、同じトピック名が2つの異なるタイプのヘルプに使用されている場合は、両方のタイプのヘルプがUIコンポーネントによって表示されます。
- <source>: <trans-unit>要素の直接の子要素として作成し、ヘルプ・テキストを入力します。
- <target>: <trans-unit>要素の直接の子要素として作成し、空白のままにします。この要素は、変換されたヘルプ・テキストの保持に使用されます。
- <note>: <trans-unit>要素の直接の子要素として作成し、ヘルプ・テキストの説明を入力します。
次の例に、2つのトピックを含むXLIFFファイルの例を示します。
```
<?xml version="1.0" encoding="UTF-8" ?>
<xliff version="1.1" xmlns="urn:oasis:names:tc:xliff:document:1.1">
 <file source-language="en" original="this" datatype="xml">
 <body>
 <trans-unit id="HELP_PHONE_NUMBER_DEFINITION">
 <source>Phone Number Definition</source>
 <target/>
 <note>
 We only support calling phone numbers in the United States at this time.
 </note>
 </trans-unit>
 <trans-unit id="HELP_CUST_SERVICE_EMAIL_INSTRUCTIONS">
 <source>Customer Service Email Instructions</source>
 <target/>
 <note>
 For security reasons, we strongly discourage the submission of credit
 card numbers.
 </note>
 </trans-unit>
 </body>
 </file>
</xliff>
```
XLIFFファイルをヘルプ・プロバイダとしてadf-settings.xmlファイル内で登録してから、ヘルプを使用するようにADF Facesのコンポーネントを構成します。「ヘルプ・プロバイダの登録方法」および「UIコンポーネントからのヘルプ・コンテンツへのアクセス方法」を参照してください。

マネージドBeanプロバイダの作成方法

マネージドBeanプロバイダを実装するには、マネージドBeanを作成し、ヘルプのテキストとして使用される文字列のマップをその中に格納します。マネージドBeanヘルプ・プロバイダでは、ELHelpProviderクラスを使用してヘルプが送信されます。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。「コンポーネントへのヘルプの表示」を参照してください。

マネージドBeanヘルプの作成方法:

文字列のマップを戻すマネージドBeanを作成しますが、次の例に示すように、いずれもIDおよびヘルプ・トピックのコンテンツです。
```
public class ELHelpProviderMapDemo
{
 public ELHelpProviderMapDemo()
 {
 }
 
 /* To use the ELHelpProvider, the EL expression must point to a Map, otherwise
 * you will get a coerceToType error. */

 public Map<String, String> getHelpMap()
 {
 return _HELP_MAP;
 }
 
 static private final Map<String, String> _HELP_MAP = 
 new HashMap<String, String>();
 static
 {
 _HELP_MAP.put("HELP_CUST_SERVICE_EMAIL_DEFINITION", "For security reasons, 
 we strongly discourage the submission of credit card numbers");
 _HELP_MAP.put("HELP_PHONE_NUMBER_DEFINITION", "We only support calling phone 
 numbers in the United States at this time");
 }
 
}
```
最初の文字列には、接頭辞、トピック名およびヘルプ・タイプが含まれている必要があります。たとえば、HELP_CUST_SERVICE_EMAIL_DEFINITIONです。この例では、HELPがBeanへのアクセスに使用される接頭辞となります。CUST_SERVICE_EMAILがトピック名で、DEFINITIONがヘルプのタイプです。2つ目の文字列はヘルプ・テキストです。複数のヘルプ・プロバイダを使用する場合は、必ずヘルプ・プロバイダのそれぞれに一意の接頭辞を使用してください。

注意:

ヘルプ・プロバイダが登録されているすべての接頭辞は一意であることが必要です。また、別の接頭辞と同じ文字で接頭辞を開始することはできません。たとえば、AABおよびACの2つの接頭辞にヘルプ・プロバイダが登録されている場合、AABC、A、AA、AC、ACBという接頭辞はすべて無効で、登録時に例外がスローされます。ただし、AAD、ABなどは有効です。

UIコンポーネントはトピック名に基づいてヘルプ・コンテンツにアクセスします。したがって、同じトピック名が2つの異なるタイプのヘルプに使用されている場合は、両方のタイプのヘルプがUIコンポーネントによって表示されます。

注意:

外部URLヘルプを使用する場合は、ELHelpProviderクラスのサブクラスを作成します。「外部URLヘルプ・プロバイダを作成する方法」を参照してください。
マネージドBeanをヘルプ・プロバイダとしてadf-settings.xmlファイル内で登録してから、ヘルプを使用するようにADF Facesのコンポーネントを構成します。「ヘルプ・プロバイダの登録方法」および「UIコンポーネントからのヘルプ・コンテンツへのアクセス方法」を参照してください。

外部URLヘルプ・プロバイダを作成する方法

外部URLをヘルプとして使用するには、getExternalURLメソッドを実装する必要があります。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。「コンポーネントへのヘルプの表示」を参照してください。

外部URLヘルプを使用するには

getExternalURLメソッドを実装するクラスを作成します。

リソース・バンドル・ベースのヘルプを使用する場合は、getExternalURLメソッドを実装するクラスがResourceBundleHelpProviderクラスを拡張していることを確認してください。

XLIFFベースまたはマネージドBeanベースのヘルプを使用する場合は、getExternalURLメソッドを実装するクラスがELHelpProviderクラスを拡張していることを確認してください。

次の例に示すDemoHelpProviderクラスは、ResourceBundleHelpProviderクラスを拡張しています。

import javax.faces.component.UIComponent;
import javax.faces.context.ExternalContext;
import javax.faces.context.FacesContext;
import oracle.adf.view.rich.help.ResourceBundleHelpProvider;

public class DemoHelpProvider extends ResourceBundleHelpProvider
{
  public DemoHelpProvider()
  {
  }
  
  @Override
  protected String getExternalUrl(FacesContext context, UIComponent component, 
                                                        String topicId)
  {
    if (topicId == null)
      return null;
    
        if (topicId.contains("HELP_CONTACT_URL"))
        {
                return "http://www.oracle.com/us/corporate/contact/index.html";
        }
        else
          return null;

        if (topicId.contains("HELP_OTN_URL") )
        {
                return "http://www.oracle.com/technetwork/index.html";
        }
        else
          return null;
  }
}

次の例に示すDemoELHelpProviderクラスは、ELHelpProviderクラスを拡張しています。

import javax.faces.component.UIComponent;
import javax.faces.context.ExternalContext;
import javax.faces.context.FacesContext;
import oracle.adf.view.rich.help.ResourceBundleHelpProvider;

public class DemoELHelpProvider extends ELHelpProvider
{
  public DemoELHelpProvider()
  {
  }
  
  @Override
  protected String getExternalUrl(FacesContext context, UIComponent component, 
                                                        String topicId)
  {
    if (topicId == null)
      return null;
    
        if (topicId.contains("HELP_CONTACT_URL"))
        {
                return "http://www.oracle.com/us/corporate/contact/index.html";
        }
        else
          return null;

        if (topicId.contains("HELP_OTN_URL") )
        {
                return "http://www.oracle.com/technetwork/index.html";
        }
        else
          return null;
  }
}

前述の例では、Oracleのお問合せホーム・ページを開くためにHELP_CONTACT_URLというトピックIDを使用しています。別のURLが返されるようにするには、別のif文を作成します。また、Oracle Technology Networkホーム・ページを開くためにHELP_OTN_URLというトピックIDを使用しています。

クラスをヘルプ・プロバイダとしてadf-settings.xmlファイル内で登録してから、ヘルプを使用するようにADF Facesのコンポーネントを構成します。「ヘルプ・プロバイダの登録方法」および「UIコンポーネントからのヘルプ・コンテンツへのアクセス方法」を参照してください。

カスタムJavaクラス・ヘルプ・プロバイダの作成方法

ADF Facesヘルプ・プロバイダのいずれかを使用するかわりに、独自のプロバイダを作成します。ヘルプ・プロバイダがアクセスして表示できるファイルに実際のテキストを作成します。Javaクラス・ヘルプ・プロバイダを作成するには、HelpProviderクラスを拡張します。このクラスの詳細は、Oracle ADF Faces Java APIリファレンスを参照してください。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。「コンポーネントへのヘルプの表示」を参照してください。

Javaクラス・ヘルプ・プロバイダを作成する手順:

oracle.adf.view.rich.help.HelpProviderを拡張するJavaクラスを作成します。
パラメータなしでpublicコンストラクタを作成します。また、ヘルプ・トピックにアクセスして戻すロジックも実装する必要があります。

このクラスは、このプロバイダの登録時にadf-settings.xmlファイルに設定されたプロパティおよび値にアクセスできます。たとえば、すべてのADF Facesプロバイダは、あるプロパティを使用してヘルプ文字列の実際のソースを定義しています。
adf-settings.xmlファイル内のプロパティにアクセスするには、String型のプロパティを設定するメソッドを作成します。
次に例を示します。
```
public void setMyCustomProperty(String arg)
```
プロバイダを登録するには、META-INFノードからadf-settings.xmlファイルを開いて、次の要素を追加します。
- <help-provider>: prefix属性を使用して、UIコンポーネントがこのヘルプ・プロバイダにアクセスする際に使用する接頭辞を定義します。これは、アプリケーション内で一意である必要があります。
 
 注意:
 
 prefix属性がないか、空である場合、そのヘルプ・プロバイダは、特別なデフォルトのヘルプ・プロバイダとして登録されます。これは、その他のどのヘルプ・プロバイダとも一致しないヘルプ・トピックIDのヘルプの生成に使用されます。許可されるデフォルトのヘルプ・プロバイダは1つのみです。ヘルプ・プロバイダが登録されているすべての接頭辞は一意であることが必要です。また、別の接頭辞と同じ文字で接頭辞を開始することはできません。たとえば、AABおよびACの2つの接頭辞にヘルプ・プロバイダが登録されている場合、AABC、A、AA、AC、ACBという接頭辞はすべて無効で、登録時に例外がスローされます。ただし、AAD、ABなどは有効です。
- <help-provider-class>: <help-provider>要素の子要素として作成し、ステップ1で作成したクラスへの完全修飾クラス・パスを入力します。
- <property>: <help-provider>要素の子要素として作成し、ステップ3で作成したメソッドの引数として使用されるプロパティの定義に使用されます。
- <property-name>: <property>要素の子要素として作成し、プロパティ名を入力します。
- <value>: <property>要素の子要素として作成し、プロパティ値を入力します。

ヘルプ・プロバイダの登録方法

リソース、XLIFFおよびマネージドBeanのヘルプ・プロバイダ、および外部URLヘルプ・プロバイダの登録はadf-settings.xmlファイル内で行います。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。「コンポーネントへのヘルプの表示」を参照してください。

ヘルプ・プロバイダを登録するには:

「アプリケーション」ウィンドウのMETA-INFノードからadf-settings.xmlファイルを開きます。
「ソース」タブをクリックし、次の要素を追加します。
- <help-provider>: prefix属性を使用して、UIコンポーネントがこのヘルプ・プロバイダにアクセスする際に使用する接頭辞を定義します。これは、アプリケーション内で一意である必要があります。
 
 注意:
 
 prefix属性がないか、空である場合、そのヘルプ・プロバイダは、特別なデフォルトのヘルプ・プロバイダとして登録されます。これは、その他のどのヘルプ・プロバイダとも一致しないヘルプ・トピックIDのヘルプの生成に使用されます。許可されるデフォルトのヘルプ・プロバイダは1つのみです。
- <help-provider-class>: <help-provider>要素の子要素として作成します。
 - リソース・バンドルを使用する場合は、値をoracle.adf.view.rich.help.ResourceBundleHelpProviderと入力します。
 - XLIFFファイルを使用する場合は、値をoracle.adf.view.rich.help.ELHelpProviderと入力します。
 - マネージドBeanまたは外部URLのプロバイダを使用する場合は、完全修飾クラス・パスを入力します。
 注意:
 
 外部URLヘルプの場合は、プロバイダが拡張したクラスがプロバイダ・クラスに反映されている必要があります。
- <property>: <help-provider>要素の子要素として作成します。プロパティは、実際のヘルプ・ソースを定義します。
- <property-name>: <property>要素の子要素として作成し、ソースの名前を入力します。
- <value>: <property>要素の子要素として作成し、ヘルパーの完全修飾クラス名を入力します。たとえば、ADF Facesコンポーネント・デモ・アプリケーションで使用されるリソース・バンドルの修飾クラス名はoracle.adfdemo.view.resource.DemoResourcesです。
 - リソース・バンドルを使用する場合は、リソース・バンドルの完全修飾クラス名を入力します。たとえば、ADF Facesコンポーネント・デモ・アプリケーションで使用されるリソース・バンドルの修飾クラス名はoracle.adfdemo.view.resource.DemoResourcesです。
 - XLIFFファイルを使用する場合は、解決結果がXLIFFファイルとなるEL式を入力し、adfBundle EL関数の中にラップします。たとえば、#{adfBundle['project1xliff.view.Project1XliffBundle']}です。
 - マネージドBeanを使用する場合は、解決結果がマネージドBean上のヘルプ・マップとなるEL式を入力します。
 - 外部URLヘルプを使用する場合は、作成したプロバイダ・クラスの完全修飾クラス名を入力します。

次の例に、adf-settings.xmlファイル内で登録されているリソース・バンドルを示します。

<adf-settings xmlns="http://xmlns.oracle.com/adf/settings">
<adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/settings">
  <help-provider prefix="HELP_">
    <help-provider-class>
      oracle.adf.view.rich.help.ResourceBundleHelpProvider
    </help-provider-class>
    <property>
        <property-name>baseName</property-name>
        <value>oracle.adfdemo.view.resource.fileExplorer.helpStrings</value>
    </property>
  </help-provider>
</adf-faces-config>
</adf-settings>

次の例に、adf-settings.xmlファイル内で登録されているXLIFFファイルを示します。

<adf-settings xmlns="http://xmlns.oracle.com/adf/settings">
<adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/settings">
  <help-provider prefix="HELP">
    <help-provider-class>
      oracle.adf.view.rich.help.ELHelpProvider
    </help-provider-class>
    <property>
      <property-name>helpSource</property-name>
      <value>#{adfBundle['project1xliff.view.Project1XliffBundle']}</value>
      </property>
    </help-provider>
  </adf-faces-config>
</adf-settings>

次の例に、adf-settings.xmlファイル内で登録されているBeanを示します。

<adf-settings xmlns="http://xmlns.oracle.com/adf/settings">
<adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/settings">
   <help-provider prefix="HELP_">
   <help-provider-class>
     oracle.adf.view.rich.help.ELHelpProvider
   </help-provider-class>
   <property>
     <property-name>helpSource</property-name>
     <value>#{helpTranslationMap.helpMap}</value>
   </property>
 </help-provider>
 </adf-faces-config>
</adf-settings>

次の例に、adf-settings.xmlファイル内で登録されている外部ヘルプ・プロバイダを示します。

<adf-settings xmlns="http://xmlns.oracle.com/adf/settings">
<adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/settings">
  <help-provider prefix="HELP_">
  <help-provider-class>
    oracle.adf.view.rich.help.ResourceBundleHelpProvider
  </help-provider-class>
  <property>
    <property-name>baseName</property-name>
    <value>oracle.adfdemo.view.resource.DemoHelp</value>
  </property>
  </help-provider>
 </adf-faces-config>
</adf-settings>

次の例に、adf-settings.xmlファイル内で登録されているカスタム・ヘルプ・プロバイダ・クラスの例を示します。

<adf-settings xmlns="http://xmlns.oracle.com/adf/settings">
<adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/settings">
  <help-provider prefix="MYAPP">
    <help-provider-class>
      oracle.adfdemo.view.webapp.MyHelpProvider
    </help-provider-class>
    <property>
      <property-name>myCustomProperty</property-name>
      <value>someValue</value>
    </property>
  </help-provider>
</adf-faces-config>
</adf-settings>

UIコンポーネントからのヘルプ・コンテンツへのアクセス方法

コンポーネントのHelpTopicId属性を使用して、ヘルプへのアクセスおよび表示を行います。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。「コンポーネントへのヘルプの表示」を参照してください。

コンポーネントからヘルプにアクセスする手順:

構造ウィンドウで、ヘルプを追加するコンポーネントを選択します。ヘルプがサポートされているコンポーネントのリストは、表19-1および表19-2を参照してください。
「プロパティ」ウィンドウの「外観」セクションを開き、helpTopicId属性の値を入力します。
定義ヘルプおよび説明ヘルプの場合は、この値に、正しいヘルプ・プロバイダにアクセスするための接頭辞とトピック名が含まれている必要があります。ヘルプ・タイプが含まれていてはなりません。その名前で登録されているすべてのヘルプ・タイプが返されて表示されるからです。

次に例を示します。
```
<af:inputText label="Customer Service E-Mail" helpTopicId="HELP_CUST_SERVICE_EMAIL"/>
```
この例では、「XLIFFプロバイダの作成方法」の例のXLIFFファイルに定義されている定義ヘルプと説明ヘルプの両方が戻されます。
ヘルプがサポートされていないコンポーネントにヘルプを表示する場合は、outputTextコンポーネントを追加してヘルプ・テキストを表示し、次のようにして、そのコンポーネントをヘルプ・プロバイダにバインドできます。
```
<af:outputFormatted
 value="#{adfFacesContext.helpProvider['HELP_CUST_SERVICE_ EMAIL'].instructions}"/>
```
これは、説明ヘルプ・テキストにアクセスします。

外部ヘルプ・ウィンドウを起動するためのJavaScriptの使用方法

外部URLヘルプを使用する場合は、デフォルトではユーザーがヘルプ・アイコンをクリックしたときにヘルプ・ウィンドウが起動されます。かわりに、特定のコンポーネントのイベントにJavaScriptとクライアント・イベント・リスナーを使用して、ヘルプ・ウィンドウを起動できます。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。「コンポーネントへのヘルプの表示」を参照してください。

JavaScriptを使用して外部ヘルプ・ウィンドウを起動する手順:

特定のURLまたはページの起動に、launchHelp APIを使用するJavaScript関数を作成します。
次の例に、helpClient.jspxの起動に使用されるlaunchHelp関数を示します。
```
<af:resource type="javascript">
 function launchHelp(event)
 {
 AdfPage.PAGE.launchHelpWindow("helpClient.jspx");
 }
</af:resource>
```
ADF Facesページで、launchHelp関数を呼び出すクライアント・イベントを持つコンポーネントをドラッグ・アンド・ドロップします。このコンポーネントのclientIdをtrueに設定する必要があります。
「コンポーネント」ウィンドウの「操作」パネルから「クライアント・リスナー」を、ステップ2で作成したコンポーネントに子としてドラッグ・アンド・ドロップします。ステップ1で作成した関数を起動するclientListenerを構成します。clientListenerタグの使用方法の詳細は、「クライアント・イベントのリスニング」を参照してください。
次の例に示すコードは、helpClient.jspxページを起動するためにbuttonコンポーネントのclickイベントを割り当てるのに使用されるものです。
```
<af:toolbar id="tb1">
 <af:button text="Launch help window" id="ctb1"
 icon="/images/happy_computer.gif">
 <af:clientListener method="launchHelp" type="click"/>
 </af:button>
</af:toolbar>
<af:resource type="javascript">
 function launchHelp(event)
 {
 AdfPage.PAGE.launchHelpWindow("helpClient.jspx");
 }
</af:resource>
```

スキニングおよび定義ヘルプに関する必知事項

デフォルトで、定義ヘルプがコンポーネントと関連している場合、疑問符のアイコンが表示されます。ユーザーはそのアイコンをクリックしてヘルプを表示します。コンポーネントのラベルの下に点線を表示させるかわりにカスタム・スキンを構成することができます。この線は、そのテキストがクリック可能であることを示します。ユーザーがテキストをクリックするとヘルプが表示されます。

注意:

コンポーネントにラベル・テキストがない場合、アイコンだけが表示されます。

図19-31に、デフォルトの疑問符アイコンの付いたinputTextコンポーネントを示します。

図19-31 定義ヘルプ・アイコン

図19-32に、同じinputTextコンポーネントを示しますが、これは疑問符のかわりにリンクを表示するように構成されています。

図19-32 定義ヘルプ・テキスト・リンク

-tr-help-def-locationスキン・セレクタ・キーを使用して表示を構成します。アイコンを表示するにはこれをiconに設定します。下線を表示するにはこれをlabelに設定します。次の例に、下線を表示するように構成したヘルプを示します。

af|help {
  -tr-help-def-location: label; 
}

注意:

外部URLヘルプもラベル・テキストの下にリンクを表示します。コンポーネントに定義ヘルプとそれに関連する外部ヘルプの両方がある場合、アイコンは定義ヘルプに対して表示されます。

複数のメッセージ・タイプの組合せ

ADF Facesでは、検証と変換の際の表示メッセージを組み合せることができます。これを利用すると、1つのウィンドウで一度に様々なメッセージを表示できますが、メッセージが表示されるのは、エラー・メッセージ、ヒント、説明ヘルプなどデフォルトの優先順です。

検証および変換に関するメッセージを表示する入力コンポーネントにヘルプ・メッセージを追加すると、ADF Facesにより、注意ウィンドウ内に次の順序でメッセージが表示されます。

検証および変換のエラー・メッセージ。
検証および変換のヒント。
入力および選択コンポーネントの場合のみ、説明ヘルプ。panelHeaderコンポーネントの場合、説明ヘルプは常にヘッダーの下に表示されます。
shortDesc属性の値。

図19-33に、コンバータ、説明ヘルプおよびヒント・メッセージを含むinputDateコンポーネントを示します。

図19-33 一度に表示されている異なるメッセージ・タイプ