Oracle® Fusion Middleware Oracle Application Development Framework Webユーザー・インタフェース開発者ガイド 11gリリース1 (11.1.1.7.0) B52029-07 |
|
前 |
次 |
この章では、ADF Facesコンポーネントにヒントおよびメッセージを定義および表示する方法と、様々なレベルのヘルプ情報をユーザーに提供する方法を説明します。
この章では、次の項目について説明します。
ADF Facesでは、様々な方法でアプリケーションに情報テキストを表示できます。精巧なヘルプ・システムだけでなく、簡単なヒント・テキスト、検証および変換のヒント・テキストやエラー・メッセージも作成できます。
多くのADF Facesコンポーネントでは、shortDesc
属性がサポートされています。この属性は、ユーザーがコンポーネントの上にカーソルを置いたときに、ほとんどのコンポーネントにヒント情報を表示します。図17-1に、ツールバー・ボタンに構成されているヒントを示します。ヒントの作成の詳細は、コンポーネントのヒントの表示に関する項を参照してください。
ヒントと同様に、EditableValueHolder
コンポーネント(inputText
コンポーネントまたは選択コンポーネントなど)も、検証および変換に使用するヒントを表示できます。検証または変換を構成すると、デフォルトのヒントにより注意ウィンドウが自動的に表示されます(詳細は、第6章「入力の検証および変換」を参照してください)。たとえば、ユーザーがFile Explorerアプリケーションの「ヘルプ」→フィードバックを報告をクリックしたとき、ダイアログに、技術サポートが連絡する日時を入力できる場所が表示されます。inputDate
コンポーネントにはコンバータが含まれているため、ユーザーがフィールドをクリックすると、図17-2に示すように、予想されるパターンを示すヒントが注意ウィンドウに表示されます。inputDate
コンポーネントに最小値または最大値も構成されている場合は、その情報もヒントに表示されます。これらのヒントは、コンバータおよびバリデータにより自動的に表示されます。
ADF Facesでは、標準のJSFメッセージングAPIが使用されます。JSFでは、addMessage(java.lang.String clientId, FacesMessage message)
メソッドを使用して、FacesMessage
インスタンスをFacesContext
オブジェクトに追加できるようにすることで、メッセージング用の組込みフレームワークがサポートされています。通常、作成されるメッセージは2種類です。1つは、コンポーネント・レベルのメッセージで、これはaddMessage
メソッドに渡された任意のクライアントIDに基づいて特定のコンポーネントに関連付けられています。もう1つは、グローバル・レベルのメッセージで、これは、クライアントIDがaddMessage
メソッドに渡されなかったため、コンポーネントに関連付けられていません。変換または検証がEditableValueHolder
のADF Facesコンポーネントで失敗した場合、FacesMessages
オブジェクトがFacesContext
インスタンスのメッセージ・キューに自動的に追加され、そのコンポーネントのIDが渡されます。これらのメッセージは、コンポーネントの注意ウィンドウに表示されます。ADF Facesコンポーネントは、独自のメッセージを表示できます。タグに追加する必要はありません。
たとえば、図17-2に表示されているフィールドにユーザーが不適切な日付を入力した場合、図17-3に示すようにエラー・メッセージが表示されます。エラー・メッセージは、ヒントともに注意ウィンドウに表示されることに注意してください。
ADF Facesコンポーネント以外にメッセージを表示する場合、または注意ウィンドウではなく、インラインでメッセージを表示する場合は、ADF Faces message
コンポーネントを使用します。
FacesMessages
コンポーネントのみでなく、document
タグも、すべてのグローバルなFacesMessages
オブジェクト(関連付けられているコンポーネントIDがない)の処理および表示を行います。コンポーネント・メッセージと同じように、表示するメッセージにタグを追加する必要はありません。グローバル・メッセージ(または3つ以上のコンポーネント・メッセージ)が作成されると、図17-4に示すように、キューのすべてのメッセージがポップアップ・ウィンドウに表示されます。
ただし、ポップアップ・ウィンドウではなく、ページにメッセージを表示する場合は、ADF Faces messages
コンポーネントを使用できます。コンポーネントのヒントおよびメッセージ表示の詳細は、検証および変換用のヒントとエラー・メッセージの表示に関する項を参照してください。
ヒント: ADF Facesには検証および変換用のメッセージがありますが、標準のJSFメッセージングAPIを使用して、キューに |
コンポーネントごとに独自のメッセージを表示するかわりに、panelLabelAndMessage
コンポーネントを使用してコンポーネントをグループ化し、1つの領域にメッセージを表示できます。コンポーネントをグループ化する必要がある場合に便利です。たとえば、File Explorerアプリケーションには、ユーザーが電話番号を入力するpanelLabelAndMessage
コンポーネントが使用されています。電話番号入力フィールドは、実際には3つの別々のinputText
コンポーネントです。panelLabelAndMessage
コンポーネントに、3つのinputText
コンポーネントがラップされています。それぞれに独自のラベルおよびメッセージを表示するかわりに、図17-3に示すように、3つのコンポーネントにはラベルとメッセージが1つずつあります。詳細は、単一のラベルおよびメッセージを使用したコンポーネントのグループ化に関する項を参照してください。
個々のコンポーネント・インスタンスのメッセージを構成するかわりに、アプリケーション全体で再利用可能な情報を提供する別々のヘルプ・システムを作成できます。ヘルプ情報は異なるタイプのプロバイダを使用して作成し、UIコンポーネントからヘルプ・テキストを参照します。次に、ADF Facesにサポートされている3つのタイプのヘルプを示します。
定義: 図17-5に示すように、ユーザーがアイコン上にマウスを置くと、ヘルプ・テキストが表示されるヘルプ・アイコン(疑問符が表示された青い丸)を表示します。
説明: このタイプのヘルプはコンポーネントに応じて、(panelHeader
コンポーネントのように)コンポーネント内に説明テキストを表示するか、図17-6に示すように、ユーザーがコンポーネントをクリックした際に開かれる注意ウィンドウにテキストを表示します。テキストは任意の長さにできます。
外部URL: 外部アプリケーションに存在するヘルプ・トピックを作成できます。これは、別のブラウザ・ウィンドウで開きます。たとえば、図17-7に、説明ヘルプを表示するかわりに、スキンに関するヘルプ・トピックを開くように構成された、スキン選択のselectOneChoice
コンポーネントを示します。ユーザーがselectOneChoice
コンポーネントをクリックすると、ヘルプ・トピックが開きます。
ヘルプ・システムの作成の詳細は、コンポーネントへのヘルプの表示に関する項を参照してください。
ADF Facesコンポーネントでは、ユーザーがコンポーネント上にマウスを置いた場合、shortDesc
属性を使用してヒントが表示されます。入力コンポーネントでは、注意ウィンドウにヒントが表示されます。その他のコンポーネント・タイプでは、標準のヒント・ボックスにヒントが表示されます。このテキストは短くする必要があります。より詳細な情報を表示する必要がある場合、または多数のコンポーネント・インスタンス間でテキストが再利用される場合は、コンポーネントへのヘルプの表示に関する項で説明されているように、ヘルプ・テキストの使用を検討してください。
図17-8に、inputText
コンポーネント上にフォーカスを置いたときの効果を示します。
図17-9に、showDetailItem
コンポーネントのヒントを示します。
コンポーネントにヒントを定義する手順:
構造ウィンドウで、ヒントを表示するコンポーネントを選択します。
プロパティ・インスペクタで、「外観」セクションを開き、shortDesc
属性に値を入力します。
ヒント: 80文字を超えると、ブラウザによってはヒントが切り捨てられてしまうため、値は80文字未満にする必要があります。 |
使用するテキストがリソース・バンドルに格納されている場合は、ドロップダウン・リストを使用して「テキスト・リソースの選択」を選択します。「テキスト・リソースの選択」ダイアログを使用して、既存のバンドル内の適切なテキストを検索するか、既存のバンドル内に新しいエントリを作成します。リソース・バンドルの使用方法の詳細は、第21章「ページの国際化およびローカライズ」を参照してください。
バリデータおよびコンバータには、関連するフィールドがクリックされた際にユーザーに表示されるデフォルトのヒントがあります。コンバータの場合、ヒントは、使用する適切な書式をユーザーに示します。バリデータの場合、ヒントは有効な値を示すために使用されます。
たとえば、図17-10に示すように、File Explorerアプリケーションでは、ユーザーがカスタマ・サービスに連絡ページの日付入力フィールドをクリックすると、使用する正しい書式が示されたヒントが表示されます。
ADF Facesコンポーネントの値が検証に失敗した場合、またはコンバータで変換できない場合は、コンポーネントに結果のFacesMessage
インスタンスが表示されます。
たとえば、図17-11に示されているように、コンバータのdateStyle
属性に一致しない日付を入力すると、エラー・メッセージが表示されます。
デフォルトのバリデータおよびコンバータのヒントとエラー・メッセージをオーバーライドできます。ADF Facesの各バリデータおよびコンバータ・コンポーネントには、ユーザーに表示する詳細なメッセージの定義に使用できる属性があります。実際の属性は、バリデータまたはコンバータによって異なります。図17-12に、プロパティ・インスペクタに表示されているconvertDateTime
コンバータのメッセージをオーバーライドするために移入できる属性を示します。
注意ウィンドウにメッセージを表示しない場合は、message
コンポーネントを使用すると、メッセージがコンポーネントにインラインで表示されます。図17-13に、message
コンポーネントを使用してメッセージがどのように表示されるかを示します。
ADF FacesアプリケーションのJSFページでは、特にポップアップ・ウィンドウへのすべてのグローバル・メッセージ(コンポーネントに関連付けられていないメッセージ)の表示を処理するdocument
タグが使用されています。ただし、グローバル・メッセージをページに表示する場合は、messages
コンポーネントを使用します。
注意: HTMLタグを使用してメッセージの書式を設定するには、メッセージを
エラー・メッセージでは、次のHTMLタグを使用できます。
|
デフォルトのバリデータおよびコンバータのメッセージをオーバーライドするには、異なるメッセージ属性に値を設定します。
バリデータまたはコンバータのメッセージを定義する手順:
構造ウィンドウで、エラー・メッセージを作成するコンバータまたはバリデータを選択します。
注意: オーバーライドできるのは、ADF Facesコンポーネントのメッセージのみです。ADF Faces以外のコンポーネント( |
プロパティ・インスペクタで、「メッセージ」セクションを開き、メッセージを指定する属性の値を入力します。
値には、{0}、{1}、{2}などのパラメータ・プレースホルダを使用して、動的コンテンツを含めることができます。たとえば、convertDateTime
コンバータのmessageDetailConvertDate
属性には、次のパラメータが使用されます。
{0}: コンポーネントを識別するラベル
{1}: ユーザーによって入力される値
{2}: コンポーネントで想定される書式の例
これらのパラメータを使用して、次のメッセージを作成できます。
{1} is not using the correct date format. Please enter the date as follows: {2}
.
エラー・メッセージは、図17-14のように表示されます。
ヒント: ドロップダウン・メニューを使用して、プロパティ・ヘルプを表示します。これには、メッセージが受け取ったパラメータが含まれています。 |
使用するテキストがリソース・バンドルに格納されている場合は、ドロップダウン・リストを使用して「テキスト・リソースの選択」を選択します。「テキスト・リソースの選択」ダイアログを使用して、既存のバンドル内の適切なテキストを検索するか、既存のバンドル内に新しいエントリを作成します。リソース・バンドルの使用方法の詳細は、第21章「ページの国際化およびローカライズ」を参照してください。
注意: メッセージ・テキストは、 |
messageDetail[XYZ]
属性を使用してコンポーネント・インスタンスごとにメッセージの文字列を変更するかわりに、文字列がすべてのインスタンスに表示されるようにグローバルにオーバーライドします。グローバルにオーバーライドするには、メッセージのキーおよび使用するメッセージ・テキストがコンテンツに含まれるメッセージ・バンドルを作成します。
メッセージ・バンドルは、変換用のリソース・バンドルを作成して使用するのと同じ方法で、Javaクラスまたはプロパティ・ファイルを使用して作成および使用します。手順および詳細は、第21章「ページの国際化およびローカライズ」を参照してください。
メッセージ・キーの情報は、付録B「コンバータおよびバリデータ・メッセージのメッセージ・キー」を参照してください。
コンポーネントで注意ウィンドウにメッセージを表示するかわりに、message
コンポーネントを使用して、ページにインラインでメッセージを表示できます。message
コンポーネントで正しいメッセージが表示されるようにするには、特定のコンポーネントと関連付けます。
コンポーネントのメッセージをインラインで表示する手順:
構造ウィンドウで、messages
コンポーネントを使用してメッセージを表示するコンポーネントを選択します。設定されていない場合、コンポーネントのIDを入力します。
コンポーネント・パレットの「共通コンポーネント」パネルから、「メッセージ」をドラッグし、ページのメッセージを表示する場所にドロップします。
for
属性のドロップダウン・メニューを使用して、「編集」を選択します。
「プロパティの編集」ダイアログで、messages
コンポーネントでメッセージを表示するコンポーネントを探します。IDの設定されているコンポーネントのみが有効な選択肢です。
注意: 表示されるメッセージ・アイコンとメッセージ・コンテンツは、 |
グローバル・メッセージをページのポップアップ・ウィンドウに表示するかわりに、messages
コンポーネントを使用してインラインで表示します。
コンポーネント・パレットの「共通コンポーネント」パネルから、「メッセージ」をドラッグし、メッセージを表示するページにドロップします。
プロパティ・インスペクタで次の属性を設定します。
globalOnly
: デフォルトでは、ADF Facesはグローバル・メッセージ(コンポーネントに関連付けられていないメッセージ)を表示し、次に個々のコンポーネントのメッセージを表示します。ボックスにグローバル・メッセージのみを表示する場合は、この属性をtrue
に設定します。コンポーネント・メッセージは、関連付けられたコンポーネントに引き続き表示されます。
inline
: ページの上部にメッセージを表示する場合にtrue
に設定します。設定しない場合、メッセージはダイアログに表示されます。
ADF Facesの入力および選択コンポーネントには、デフォルトで、ラベルおよびメッセージの表示用に組込みサポートが用意されています。コンポーネントをグループ化して単一のラベルを使用する場合は、panelLabelAndMessage
コンポーネントを使用してコンポーネントをラップします。
たとえば、File Explorerアプリケーションは、4つの別々のinputText
コンポーネントを使用して電話番号を収集します。それぞれ、市外局番、電話局、最後の4桁および内線番号用です。単一のラベルが必要なため、4つのinputText
コンポーネントはpanelLabelAndMessage
コンポーネントにラップされ、ラベルの値はそのコンポーネントに設定されます。ただし、内線番号の入力コンポーネントには追加のラベルが必要なため、outputText
コンポーネントが使用されます。例17-1に、panelLabelAndMessage
コンポーネントのJSFコードを示します。
例17-1 単一のラベルおよびヘルプ・トピックの表示が可能なpanelLabelAndMessage
<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>
図17-15に、panelLabelAndMessage
およびネストしたコンポーネントがブラウザにどのように表示されるかを示します。
panelLabelAndMessage
コンポーネントには、グループの最後に追加のコンポーネントを表示するために使用できるEnd
ファセットも含まれます。図17-16に、End
ファセットにoutputText
コンポーネントが移入されている場合に、電話番号フィールドがどのように表示されるかを示します。
panelLabelAndMessage
コンポーネント内にpanelGroupLayout
コンポーネントを使用して、必要なレイアウトのコンポーネントをグループ化します。panelGroupLayout
コンポーネントの使用方法の詳細は、8.13項「関連する項目のグループ化」を参照してください。
各入力コンポーネントでsimple
属性をtrue
に設定し、個々のラベルが表示されないようにします。ただし、メッセージ目的およびアクセシビリティ用の各コンポーネントのラベル属性に値を設定することが必要な場合があります。
ヒント: 複数の |
panelLabelAndMessage
コンポーネントを使用して、コンポーネントをグループ化してラップします。panelLabelAndMessage
コンポーネントは、通常メッセージやラベルを表示するコンポーネントのみでなく、任意のコンポーネントのラップに使用できます。
単一のラベルおよびメッセージを使用してフォーム入力コンポーネントを配置する手順:
必要に応じて、入力コンポーネントまたは選択コンポーネントをページに追加します。
各入力および選択コンポーネントに次の設定を行います。
simple
属性をtrue
に設定します。
アクセシビリティの理由から、label
属性をコンポーネントのラベルに設定します。
構造ウィンドウで、手順1で作成した入力コンポーネントまたは選択コンポーネントを選択します。選択内容を右クリックし、「囲む」→「パネル・ラベルとメッセージ」を選択します。
panelLabelAndMessage
コンポーネントが選択された状態で、プロパティ・インスペクタにおいて次の属性を設定します。
label: コンポーネントのグループに表示するラベル・テキストを入力します。
for: ドロップダウン・メニューを使用して「編集」を選択します。「プロパティの編集」ダイアログで、子入力コンポーネントのIDを選択します。入力コンポーネントが複数ある場合は、最初のコンポーネントを選択します。
アクセシビリティ要件に一致するように、for
属性を最初のinputComponent
に設定します。
ネストした入力コンポーネントの1つ以上が必須コンポーネントで、これを示すためにマーカーを表示する場合は、showRequired
属性をtrue
に設定します。
End
ファセットにコンテンツを配置するには、必要なコンポーネントをファセットにドラッグ・アンド・ドロップします。
ファセットに配置できる子コンポーネントは1つのみであるため、複数の子コンポーネントを追加する場合は、panelGroupLayout
またはgroup
コンポーネントなどのコンテナで子コンポーネントをラップする必要があります。
ヒント: ファセットがビジュアル・エディタに表示されない場合は、次のようにします。
|
ADF Facesでは、異なる3つのタイプのヘルプを作成および表示できるフレームワークを提供します。これらのヘルプはコンポーネントで構成したテキストではなく、コンテンツが外部ソースから取得されます。コンポーネントに直接構成されていないため、コンテンツは複数のコンポーネントで使用できます。これにより、ページを作成する時間が節約でき、コンテンツが表示されるすべての場所ではなく、1箇所でコンテンツを変更できます。
ADF Facesにより提供される1つ目のタイプの外部ヘルプは、定義ヘルプです。標準のヒント同様、コンテンツはメッセージ・ボックスに表示されます。ただし、ユーザーがコンポーネント上にマウスを置いた場合に表示されるのではなく、定義ヘルプではヘルプ・アイコン(疑問符が表示された青い丸)が表示されます。ユーザーがアイコン上にマウスを置くと、図17-17に示すようにコンテンツが表示されます。
表17-1に、定義ヘルプがサポートされているコンポーネントを示します。
表17-1 定義ヘルプがサポートされているコンポーネント
サポートされているコンポーネント | ヘルプ・アイコンの位置 | 例 |
---|---|---|
すべての入力コンポーネント、選択コンポーネント、色の選択、日付の選択、問合せコンポーネント |
ラベルの前。ラベルが存在しない場合は、フィールドの先頭。 |
|
パネル・ヘッダー、パネル・ボックス、詳細の表示ヘッダー |
ヘッダー・テキストの最後。 |
|
パネル・ウィンドウ、ダイアログ |
ヘッダーの「閉じる」アイコンの隣。 |
|
表およびツリーの列 |
ヘッダー・テキストの下。 |
|
2つ目のタイプのヘルプは説明ヘルプです。説明ヘルプが表示される場所は、関連付けられているコンポーネントによって異なります。panelHeader
および検索パネル・コンポーネントでは、ヘッダー内に説明ヘルプが表示されます。図17-18に、図17-17に示されている、通常は定義ヘルプとして表示されるテキストが、panelHeader
コンポーネント内で説明ヘルプとしてどのように表示されるかを示します。
説明ヘルプがサポートされているその他すべてのコンポーネントでは、図17-19に示すように、注意ウィンドウにテキストが表示されます。ヘルプ・アイコンは表示されないことに注意してください。
表17-2に、説明ヘルプがサポートされているコンポーネントを示します。
表17-2 説明ヘルプがサポートされているコンポーネント
サポートされているコンポーネント | ヘルプの位置 | 例 |
---|---|---|
入力コンポーネント、色の選択、日付の選択、クイック問合せ |
注意ウィンドウ(フォーカスがある場合のみ) |
|
コンポーネントの選択 |
注意ウィンドウ(マウスが置かれている場合とフォーカスがある場合) |
|
パネル・ヘッダー、パネル・ボックス、問合せ |
ヘッダー・テキストの下のテキスト |
|
最後のタイプのヘルプは外部URLヘルプです。外部アプリケーションのWebページのURLを指定します。ヘルプ・アイコンがクリックされると、図17-20.に示すように、Webページが別のブラウザ・ウィンドウで開きます。ヘルプ・アイコンをクリックするかわりに、JavaScriptを使用し、クライアントベースのイベントに基づいてヘルプ・ウィンドウを開くことも可能です。
ADF Facesには、様々なヘルプ・プロバイダがあります。ResourceBundleHelpProvider
ヘルプ・プロバイダを使用すると、ヘルプ・コンテンツを保持するリソース・バンドルを作成できます。ELHelpProvider
ヘルプ・プロバイダを使用すると、マップに変換されるXLIFFファイルの作成、またはヘルプ・テキスト文字列のマップが含まれるマネージドBeanの作成が可能です。異なるヘルプ・プロバイダを組み合せて使用することもできます。また、独自のヘルプ・プロバイダ・クラスの作成も可能です。
アプリケーションにヘルプを作成するには、次のようにします。
使用するヘルプ・プロバイダを決定し、必要なアーティファクトを実装します。
プロバイダのヘルプへのアクセスに使用する接頭辞を指定して、ヘルプ・プロバイダを登録します。各ヘルプ・プロバイダには一意の接頭辞があり、識別子として使用されます。プロバイダが登録されている接頭辞で始まるヘルプ・トピックIDに対してのみヘルプを生成するために、特定のプロバイダがコールされます。
コンポーネントのhelpTopicId
属性を使用して、UIコンポーネントがプロバイダに含まれるヘルプにアクセスできるようにします。helpTopicId
属性には、次の情報が含まれています。
ヘルプ・プロバイダにより使用される接頭辞
トピック名
たとえば、図17-19に示されているinputText
コンポーネントのhelpTopicId
属性の値はRBHELP_FILE_NAME
です。ここで、RBHELP
はリソース・バンドル・ヘルプ・プロバイダの接頭辞で、FILE_NAME
はヘルプ・トピック名です。
標準のリソース・バンドル・プロパティ・ファイルにヘルプ・テキストを格納し、ResourceBundleHelpProvider
クラスを使用してコンテンツを送信できます。
リソース・バンドルベースのヘルプを作成する手順:
各ヘルプ・トピックのトピックIDおよびヘルプ・テキストを含むプロパティ・ファイルを作成します。トピックIDには次の情報が含まれている必要があります。
RBHELP
など、プロバイダにより使用される接頭辞
TELEPHONE_NUMBER
などのトピック名
DEFINITION
などのヘルプ・タイプ
たとえば、トピックIDはRBHELP_TELEPHONE_NUMBER_DEFINITION
のようになります。
注意: ヘルプ・プロバイダが登録されているすべての接頭辞は一意であることが必要です。また、別の接頭辞と同じ文字で接頭辞を開始することはできません。たとえば、 UIコンポーネントはトピック名に基づいてヘルプ・コンテンツにアクセスします。そのため、2つの異なるヘルプ・タイプに同じトピック名を使用すると(例17-2を参照)、UIコンポーネントにより、両方のヘルプ・タイプが表示されます。 |
例17-2に、3つのトピックがあるリソース・バンドルの例を示します。
例17-2 リソース・バンドル・ヘルプ
RBHELP_CUST_SERVICE_EMAIL_DEFINITION=For security reasons, we strongly discourage the submission of credit card numbers. RBHELP_TELEPHONE_NUMBER_DEFINITION=We only support calling telephone numbers in the United States at this time. RBHELP_TELEPHONE_NUMBER_INSTRUCTIONS=Enter a telephone number.
adf-settings.xml
ファイルにヘルプ・プロバイダとしてリソース・バンドルを登録します(存在しない場合にadf-settings.xml
ファイルを作成する方法の詳細は、A.5.1項「adf-settings.xmlでのADF Facesの構成方法」を参照してください)。
プロバイダを登録するには、adf-settings.xml
ファイルを開き、「ソース」タブをクリックして、次の要素を追加します。
<help-provider>
: prefix
属性を使用して、UIコンポーネントがこのヘルプ・プロバイダにアクセスする際に使用する接頭辞を定義します。これは、アプリケーション内で一意であり、リソース・バンドルに使用されている接頭辞に一致する必要があります。
注意:
|
<help-provider-class>
: <help-provider>
要素の子要素として作成し、oracle.adf.view.rich.help.ResourceBundleHelpProvider
を入力します。
<property>
: <help-provider>
要素の子要素として作成します。プロパティは、実際のヘルプ・ソースを定義します。
<property-name>
: <property>
要素の子要素として作成し、baseName
など、ソースの名前を入力します。
<value>
: <property>
要素の子要素として作成し、リソース・バンドルの完全修飾クラス名を入力します。たとえば、ADF Facesデモ・アプリケーションで使用されるリソース・バンドルの修飾クラス名はoracle.adfdemo.view.resource.DemoResources
です。
例17-3に、例17-2のリソース・バンドルが、adf-settings.xml
ファイルにどのように登録されているかを示します。
例17-3 ヘルプ・プロバイダとしてのリソース・バンドルの登録
<adf-settings xmlns="http://xmlns.oracle.com/adf/settings"> <adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/settings"> <help-provider prefix="RBHELP_"> <help-provider-class> oracle.adf.view.rich.help.ResourceBundleHelpProvider </help-provider-class> <property> <property-name>baseName</property-name> <value>oracle.adfdemo.view.resource.DemoResources</value> </property> </help-provider> </adf-faces-config> </adf-settings>
外部URLヘルプを使用する場合は、ResourceBundleHelpProvider
クラスを拡張し、getExternalUrl
メソッドも実装する必要があります。例17-4に、メソッドの例を示します。
例17-4 getExternalURLメソッドのオーバーライド
protected String getExternalUrl(FacesContext context, UIComponent component, String topicId) { if (topicId == null) return null; if (topicId.contains("TOPICID_ALL") || topicId.contains("TOPICID_DEFN_URL") || topicId.contains("TOPICID_INSTR_URL") || topicId.contains("TOPICID_URL")) return http://www.myURL.com; else return null; }
例17-4では、メソッドのすべてのトピックで同じURLが返されます。異なるURLを返すには、if
文を個別に作成する必要があります。
ヘルプ・アイコンから起動されるのではなく、コンポーネントのクライアント・イベントに基づいて起動される外部ウィンドウが必要な場合、JavaScript関数を使用します。詳細は、JavaScriptを使用して外部ヘルプ・ウィンドウを起動する方法に関する項を参照してください。
XLIFF XMLファイルにヘルプ・テキストを格納し、ELHelpProvider
クラスを使用してコンテンツを送信できます。このクラスでは、XLIFFファイルが、ヘルプのテキストとして使用される文字列のマップに変換されます。
XLIFFヘルプを作成する手順:
<body>
タグ内に次の要素を使用して、ヘルプ・テキストを定義するXLIFFファイルを作成します。
<trans-unit>
: トピックIDを入力します。このIDには、XLIFFHELP_CREDIT_CARD_DEFINITION
のように、接頭辞、トピック名およびヘルプ・タイプが含まれている必要があります。この例で、XLIFFHELP
はXLIFFファイルへのアクセスに使用される接頭辞になります。CREDIT_CARD
はトピック名で、DEFINITION
はヘルプ・タイプです。
注意: ヘルプ・プロバイダが登録されているすべての接頭辞は一意であることが必要です。また、別の接頭辞と同じ文字で接頭辞を開始することはできません。たとえば、 UIコンポーネントはトピック名に基づいてヘルプ・コンテンツにアクセスします。そのため、2つの異なるヘルプ・タイプに同じトピック名を使用すると(例17-5を参照)、UIコンポーネントにより、両方のヘルプ・タイプが表示されます。 |
<source>
: <trans-unit>
要素の直接の子要素として作成し、ヘルプ・テキストを入力します。
<target>
: <trans-unit>
要素の直接の子要素として作成し、空白のままにします。これは翻訳済テキストを保持するために使用されます。
<note>
: <trans-unit>
要素の直接の子要素として作成し、ヘルプ・テキストの説明を入力します。
例17-5に、2つのトピックを含むXLIFFファイルの例を示します。
例17-5 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="XLIFF_CREDIT_CARD_DEFINITION"> <source>Credit Card Definition</source> <target/> <note>Credit Card definition text.</note> </trans-unit> <trans-unit id="XLIFF_CREDIT_CARD_INSTRUCTIONS"> <source>Credit Card Instructions</source> <target/> <note>Credit card instruction text.</note> </trans-unit> </body> </file> </xliff>
adf-settings.xml
ファイルにヘルプ・プロバイダとしてXLIFFを登録します(存在しない場合にadf-settings.xml
ファイルを作成する方法の詳細は、A.5.1項「adf-settings.xmlでのADF Facesの構成方法」を参照してください)。
プロバイダを登録するには、adf-settings.xml
ファイルを開き、次の要素を追加します。
<help-provider>
: prefix
属性を使用して、UIコンポーネントがこのヘルプ・プロバイダにアクセスする際に使用する接頭辞を定義します。これは、アプリケーション内で一意であり、XLIFFファイルに使用されている接頭辞に一致する必要があります。
注意:
|
<help-provider-class>
: <help-provider>
要素の子要素として作成し、oracle.adf.view.rich.help.ELHelpProvider
を入力します。
<property>
: <help-provider>
要素の子要素として作成します。プロパティ値は、実際のヘルプ・ソースを定義します。
<property-name>
: <property>
要素の子要素として作成し、helpSource
など、ヘルプの名前を入力します。
<value>
: <property>
要素の子要素として作成し、#{adfBundle['project1xliff.view.Project1XliffBundle']}
のように、adfBundle
EL関数でラップされた、XLIFFファイルに解決されるEL式を入力します。
例17-6に、例17-5のXLIFFファイルが、adf-settings.xml
ファイルにどのように登録されているかを示します。
例17-6 ヘルプ・プロバイダとしてのXLIFFファイルの登録
<adf-settings xmlns="http://xmlns.oracle.com/adf/settings"> <adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/settings"> <help-provider prefix="XLIFF"> <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>
マネージドBeanヘルプを実装するには、ヘルプのテキストとして使用される文字列のマップを含むマネージドBeanを作成します。マネージドBeanヘルプ・プロバイダでは、ELHelpProvider
クラスを使用してヘルプが送信されます。
マネージドBeanヘルプの作成方法:
文字列のマップを戻すマネージドBeanを作成します。例17-7に示すように、いずれもIDおよびヘルプ・トピックのコンテンツです。
例17-7 ヘルプ・テキスト文字列のマップを戻すマネージドBean
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("MAPHELP_CREDIT_CARD_DEFINITION", "Map value for credit card definition"); _HELP_MAP.put("MAPHELP_CREDIT_CARD_INSTRUCTIONS", "Map value for credit card instructions"); _HELP_MAP.put("MAPHELP_SHOPPING_DEFINITION", "Map value for shopping definition"); _HELP_MAP.put("MAPHELP_SHOPPING_INSTRUCTIONS", "Map value for shopping instructions"); } }
最初の文字列には、MAPHELP_CREDIT_CARD_DEFINITION
などのように、接頭辞、トピック名およびヘルプ・タイプが含まれている必要があります。この例で、MAPHELPはBeanへのアクセスに使用される接頭辞になります。
CREDIT_CARD
はトピック名で、DEFINITION
はヘルプ・タイプです。2つ目の文字列はヘルプ・テキストです。
注意: ヘルプ・プロバイダが登録されているすべての接頭辞は一意であることが必要です。また、別の接頭辞と同じ文字で接頭辞を開始することはできません。たとえば、 UIコンポーネントはトピック名に基づいてヘルプ・コンテンツにアクセスします。そのため、2つの異なるヘルプ・タイプに同じトピック名を使用すると(例17-7を参照)、UIコンポーネントにより、両方のヘルプ・タイプが表示されます。 |
faces-config.xml
ファイルにマネージドBeanを登録します。例17-8に、例17-7に示されていて、faces-config.xml
ファイルに登録されているBeanを示します。
例17-8 faces-config.xmlファイルでのマネージドBeanの登録
<managed-bean> <managed-bean-name>helpTranslationMap</managed-bean-name> <managed-bean-class> oracle.adfdemo.view.webapp.ELHelpProviderMapDemo </managed-bean-class> <managed-bean-scope>session</managed-bean-scope> </managed-bean>
マネージドBeanの使用および登録の詳細は、マネージドBeanの作成と使用に関する項を参照してください。
adf-settings.xml
ファイルにヘルプ・プロバイダとしてマネージドBeanを登録します(存在しない場合にadf-settings.xml
ファイルを作成する方法の詳細は、A.5.1項「adf-settings.xmlでのADF Facesの構成方法」を参照してください)。
プロバイダを登録するには、adf-settings.xml
ファイルを開き、次の要素を追加します。
<help-provider>
: prefix
属性を作成および使用して、UIコンポーネントがこのヘルプ・プロバイダにアクセスする際に使用する接頭辞を定義します。アプリケーション内で一意であることが必要です。
注意:
|
<help-provider-class>
: <help-provider>
要素の子要素として作成し、手順1で作成したクラスへの完全修飾クラス・パスを入力します。
<property>
: <help-provider>
要素の子要素として作成します。プロパティは、マネージドBeanのヘルプ文字列のマップを定義します。
<property-name>
: <property>
要素の子要素として作成し、helpSource
など、プロパティ名を入力します。
<value>
: <property>
要素の子要素として作成し、マネージドBeanのヘルプ・マップに解決されるEL式を入力します。
例17-9に、例17-8のBeanが、adf-settings.xml
ファイルにどのように登録されているかを示します。
例17-9 ヘルプ・プロバイダとしてのマネージドBeanの登録
<adf-settings xmlns="http://xmlns.oracle.com/adf/settings"> <adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/settings"> <help-provider prefix="MAPHELP_"> <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>
マネージドBeanプロバイダに外部URLヘルプを使用する場合は、ELHelpProvider
クラスを拡張し、getExternalUrl
メソッドを実装する必要があります。例17-10に、メソッドの例を示します。
例17-10 getExternalURLメソッドのオーバーライド
protected String getExternalUrl(FacesContext context, UIComponent component, String topicId) { if (topicId == null) return null; if (topicId.contains("TOPICID_ALL") || topicId.contains("TOPICID_DEFN_URL") || topicId.contains("TOPICID_INSTR_URL") || topicId.contains("TOPICID_URL")) return http://www.myURL.com; else return null; }
例17-10では、メソッドのすべてのトピックで同じURLが返されます。異なるURLを返すには、if
文を個別に作成する必要があります。
ヘルプ・アイコンから起動されるのではなく、コンポーネントのクライアント・イベントに基づいて起動される外部ウィンドウが必要な場合、JavaScript関数を使用します。詳細は、JavaScriptを使用して外部ヘルプ・ウィンドウを起動する方法に関する項を参照してください。
外部URLヘルプを使用する場合、デフォルトでは、ユーザーはヘルプ・アイコンをクリックして、ヘルプ・ウィンドウを起動します。かわりに、JavaScriptおよびクライアント・イベント・リスナーを使用すると、特定のコンポーネントのイベントがヘルプ・ウィンドウを起動できます。
JavaScriptを使用して外部ヘルプ・ウィンドウを起動する手順:
launchHelp
APIを使用して特定のURLまたはページを起動するJavaScript関数を作成します。
例17-11に、helpClient.jspx
を起動するために使用されるlaunchHelp
関数を示します。
クライアント・イベントによって関数が起動されるコンポーネントをドラッグ・アンド・ドロップします。このコンポーネントのclientId
をtrue
に設定する必要があります。
コンポーネント・パレットの「操作」パネルから、手順2で作成したコンポーネントに、「クライアント・リスナー」を子としてドラッグ・アンド・ドロップします。clientListener
を構成して、手順1で作成した関数を起動します。clientListener
タグの使用の詳細は、クライアント・イベントのリスニングに関する項を参照してください。
例17-12に、commandToolbarButton
コンポーネントのクリック・イベントによってhelpClient.jspx
ページが起動されるように使用されるコードを示します。
例17-12 外部ヘルプ・ウィンドウを起動するために使用されるページ・コード
<af:toolbar id="tb1"> <af:commandToolbarButton text="Launch help window" id="ctb1" icon="/images/happy_computer.gif"> <af:clientListener method="launchHelp" type="click"/> </af:commandToolbarButton> </af:toolbar> <af:resource type="javascript"> function launchHelp(event) { AdfPage.PAGE.launchHelpWindow("helpClient.jspx"); } </af:resource>
ADF Facesヘルプ・プロバイダのいずれかを使用するかわりに、独自のプロバイダを作成します。ヘルプ・プロバイダがアクセスして表示できるファイルに実際のテキストを作成します。Javaクラス・ヘルプ・プロバイダを作成するには、HelpProvider
クラスを拡張します。このクラスの詳細は、ADF FacesのJavadocを参照してください。
Javaクラス・ヘルプ・プロバイダを作成する手順:
oracle.adf.view.rich.help.HelpProvider
を拡張するJavaクラスを作成します。
パラメータなしでpublicコンストラクタを作成します。また、ヘルプ・トピックにアクセスして戻すロジックも実装する必要があります。
このクラスは、このプロバイダの登録時にadf-settings.xml
ファイルに設定されたプロパティおよび値にアクセスできます。たとえば、すべてのADF Facesプロバイダでは、プロパティを使用して、ヘルプ文字列の実際のソースが定義されます。adf-settings.xml
ファイルのプロパティにアクセスするには、String
であるプロパティを設定するメソッドを作成します。次に例を示します。
public void setMyCustomProperty(String arg)
プロバイダを登録するには、adf-settings.xml
ファイルを開き、次の要素を追加します。
<help-provider>
: prefix
属性を使用して、UIコンポーネントがこのヘルプ・プロバイダにアクセスする際に使用する接頭辞を定義します。アプリケーション内で一意であることが必要です。
注意:
|
<help-provider-class>
: <help-provider>
要素の子要素として作成し、手順1で作成したクラスへの完全修飾クラス・パスを入力します。
<property>
: <help-provider>
要素の子要素として作成し、手順3で作成したメソッドの引数として使用されるプロパティの定義に使用されます。
<property-name>
: <property>
要素の子要素として作成し、プロパティ名を入力します。
<value>
: <property>
要素の子要素として作成し、プロパティ値を入力します。
例17-13に、adf-settings.xml
ファイルに登録されているヘルプ・プロバイダ・クラスの例を示します。
例17-13 ヘルプ・プロバイダ・クラスの登録
<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>
コンポーネントのHelpTopicId
属性を使用して、ヘルプへのアクセスおよび表示を行います。
コンポーネントからヘルプにアクセスする手順:
構造ウィンドウで、ヘルプを追加するコンポーネントを選択します。ヘルプがサポートされているコンポーネントのリストは、表17-1および表17-2を参照してください。
プロパティ・インスペクタで、「外観」セクションを開き、helpTopicId
属性に値を入力します。これには、適切なヘルプ・プロバイダおよびトピック名にアクセスする接頭辞が含まれている必要があります。次に示すように、その名前で登録されているすべてのヘルプ・タイプが戻されて表示されるため、ヘルプ・タイプは含めません。
<af:inputText label="Credit Card" helpTopicId="XLIFF_CREDIT_CARD"/>
この例では、例17-5のXLIFFファイルに定義されている定義ヘルプと説明ヘルプの両方が戻されます。
ヘルプがサポートされていないコンポーネントにヘルプを表示する場合は、outputText
コンポーネントを追加してヘルプ・テキストを表示し、次のようにして、そのコンポーネントをヘルプ・プロバイダにバインドできます。
<af:outputFormatted value="#{adfFacesContext.helpProvider['XLIFF_CREDIT_CARD'].instructions}"/>
これは、説明ヘルプ・テキストにアクセスします。
検証および変換に関するメッセージを表示する入力コンポーネントにヘルプ・メッセージを追加すると、ADF Facesにより、注意ウィンドウ内に次の順序でメッセージが表示されます。
検証および変換のエラー・メッセージ。
検証および変換のヒント。
入力および選択コンポーネントの場合のみ、説明ヘルプ。panelHeader
コンポーネントの場合、説明ヘルプは常にヘッダーの下に表示されます。
shortDesc
属性の値。
図17-21に、コンバータ、説明ヘルプおよびヒント・メッセージを含むinputDate
コンポーネントを示します。