JSF Web ページには、フィードバックを提供するため (多くの場合、ページに関する問題をユーザーに通知するため) のエラー・メッセージを表示することができます。それらのエラー・メッセージ・コンポーネントの値は、システム関数 sysLib.setError および sysLib.setErrorForComponentID を使用して、ページの JSF ハンドラーから設定することができます。
JSF ページでは、以下の 2 つのタイプのエラー・メッセージ・コンポーネントを使用します。
- display error コンポーネントは、ページ上の特定の入力コンポーネントに関するメッセージを表示します。そのため、このタイプのコンポーネントでは、ページ上の入力コンポーネントの ID を使用する必要があります。エラー表示コンポーネントは、JSF タグ <h:message> によって表します。また、フィードバック提供のための入力コンポーネントの ID は、その for 属性で指定します。
- display error コンポーネントの動作は、以下の 2 つのうちのいずれかになります。
- ページ上の display error コンポーネントからのエラー・メッセージをすべて結合し、特定のコンポーネントに関連付けられていないエラー・メッセージを付加します。
- 特定のコンポーネントに関連付けられていないエラー・メッセージのみを表示します。
JSF ハンドラーでは、以下の方法で、エラー・メッセージ・コンポーネントの値を設定することができます。
- sysLib.setError システム関数によって、ページ上の入力コンポーネントにバインドされている変数の名前を指定して、display error コンポーネントのメッセージを設定します。つまり、JSF ハンドラー内の EGL 変数の名前がこの関数に渡されて、ページ上の入力コンポーネントに関連付けられている display error コンポーネントを JSF が検出し、指定された EGL 変数になります。
- sysLib.setErrorForComponentID 関数によって、ページ上の入力コンポーネントの ID を指定して、display error コンポーネントのメッセージを設定します。指定された入力コンポーネントに関連付けられている display error コンポーネントに、JSF はエラー・メッセージを表示します。
以下の手順に従い、EGL を使用して Web ページ上にエラー・メッセージを表示します。
- リソース・バンドルの作成の説明を参照して、エラー・メッセージを保持するリソース・バンドルを作成します。つまり、次の形式の名前を持つファイルを作成します。
prefix_locale.properties
- prefix
- リソース・バンドル・ファイル名の接頭部は任意ですが、アプリケーションの各リソース・バンドルで同じものでなければ
なりません。
- locale
- en_US などの、リソース・バンドルのロケール。
ロケールはバンドル内のストリングの言語を示し、オプションで、その言語の特徴に関するより具体的な情報 (方言、種類、または
地理的位置など) を示します。
ロケールについて詳しくは
、リソース・バンドルのロケールを参照してください。
例えば、米国で話されている英語が含まれる
リソース・バンドルは、
resourceBundle_en_US.properties のような名前になります。
次に、
keyname=messageText という形式で、メッセージをファイルに追加します (以下の例を参照)。
error01=The specified value is too short.
オプションで、INSERT をメッセージに含めることもできます。INSERT は、中括弧で囲まれた整数によって表され、エラー・メッセージの表示時に、ユーザーが指定した値に置き換えられます。1 つのエラー・メッセージに複数の INSERT を含めることができます。その場合は、{0}、{1}、{2} というように番号を付けます。
例えば、INSERT が 1 つの場合、リソース・バンドル内のエラー・メッセージは次のようになります。
error02=The specified value is shorter than five characters: {0}
- EGL Web プロジェクト内の Web ページで、入力コンポーネント (入力テキスト・コンポーネントなど) を作成します。入力コンポーネントでは、JSF display error のみを使用することができます。
- その入力コンポーネントを、ページに関連付けられている JSF ハンドラー内の変数にバインドします。
- (オプション) コンポーネントの ID に分かりやすいニーモニックを設定します。コンポーネントをクリックして選択してから、「プロパティー」ビューの「ID」フィールドに、ID を入力してください。
- 「パレット」ビューから、「入力コンポーネント・エラーの表示」コンポーネントをページにドラッグします。
display error コンポーネントは、入力コンポーネントの近くに配置します。こうすることで、どのコンポーネントがエラー・メッセージに関連付けられているかが明確になります。
- display error コンポーネントをクリックして、選択します。
- 「プロパティー」ビューの「コンポーネントのエラー・メッセージを表示」の下で、「ID」フィールドに入力コンポーネントの ID を設定します。
この時点で Web ページのコードを見ると、エラー・メッセージが入力コンポーネントに関連付けられていることが分かります。次の例では、display error コンポーネントの
for 属性に、入力コンポーネントの
id 属性の値が設定されています。
<h:inputText id="inputComponent"
styleClass="inputText"
value="#{errorMessageTest.inputString}"
binding="#{errorMessageTest.inputString_Ref}">
</h:inputText>
<h:message id="message1"
styleClass="message"
for="inputComponent">
</h:message>
- ページを保存します。
- ページに関連付けられている JSF ハンドラーで、JSF ハンドラー・プロパティー msgResource にリソース・バンドルのプレフィックス (ファイル名から拡張子とロケール・コードを除いたもの) を設定します。
handler errorMessageTest type JSFHandler
{view = "errorMessageTest.jsp",
msgResource = "resourceBundle"}
このケースでは、リソース・バンドルに resourceBundle_en_US.properties という名前が付けられています。つまり、msgResource プロパティーは resourceBundle に設定されています。
- システム関数 sysLib.setError または sysLib.setErrorForComponentID を使用して、以下のいずれかの方法でエラー・メッセージを設定します。
- JSF ハンドラーで指定されているストリングを、エラー・メッセージのテキストとして使用する場合は、以下の 3 つのパラメーターを記載されている順序どおりに渡します。
- JSF ハンドラー内の EGL 変数の名前 (引用符なし)。レコード内のフィールドに対して、レコード名、ピリオド、フィールド名という形で指定します (例: myRecord.myField)。
- 空ストリング。2 番目のパラメーターとして、空ストリングを渡します。外部エラー・メッセージ・ファイル内で、このパラメーターがメッセージのキーとして使用されるからです。
- エラー・メッセージのテキスト (ストリングとして)。
この方法の例を、次に示します。
SysLib.setError(inputString, "",
"This is the text of the error message.");
- INSERT をまったく含まないか、または 1 つだけ含むエラー・メッセージを、リソース・バンドルで使用する場合は、以下の 3 つのパラメーターを記載されている順序どおりに渡します。
- JSF ハンドラー内の EGL 変数の名前 (引用符なし)。レコード内のフィールドに対して、レコード名、ピリオド、フィールド名という形で指定します (例: myRecord.myField)。
- リソース・バンドル内のメッセージのキー (引用符付き)。
- INSERT で使用する値 (メッセージに INSERT を含める場合)。このパラメーターには、STRING 型との互換性がなければなりません。
例えば、変数 inputString に関連するエラーが発行されるようにする場合は、キー error02 を含み、同じ変数が INSERT 値として指定されているエラー・メッセージを使用します。その場合の EGL コードの使用例を、以下に示します。
SysLib.setError(inputString, "error02", inputString);
この例のリソース・バンドルには、次のようなメッセージ定義が含まれているものとします。
error02=The specified value is shorter than five characters: {0}
- INSERT を 2 つ以上含むエラー・メッセージを、リソース・バンドルで使用する場合は、sysLib.getMessage を sysLib.setError と組み合わせて使用する必要があります。
なぜならば、sysLib.setError でサポートされるエラー・メッセージは、INSERT が 1 つ以下のものであるためです。
- userMessageFile ビルド記述子オプションに、リソース・バンドル・ファイル名のプレフィックスを設定します。これは、JSF ハンドラー・プロパティー msgResource で設定したものと同じ値になります。
- sysLib.getMessage を使用して、INSERT をメッセージに入れ、完全なメッセージを含むストリングを作成します。
errorMessageString string =
sysLib.getMessage("error03", [inputString, "five"]);
- エラー・メッセージ・ストリングを sysLib.setError に渡します。
SysLib.setError(inputString, "", errorMessageString);
この例では、次のような 2 つの INSERT がリソース・バンドル内のエラー・メッセージに含まれているものとします。
error03=The string {0} is too short.
It must be at least {1} characters long.
- ほとんどの場合、sysLib.setError を使用して、エラー・メッセージを設定します。EGL 変数名をエラー・メッセージの参照点として使用する方が、便利なことが多いためです。ただし、エラー・メッセージを関連付ける入力コンポーネントの ID が分かっていれば、sysLib.setErrorForComponentID を sysLib.setError と同じような方法で使用することも可能です。この場合、EGL 変数の名前ではなく、入力コンポーネントの引用符付き ID (ページ上のフォーム + コロン + 入力コンポーネントの ID) が sysLib.setErrorForComponentID に指定されているケースは除きます。
SysLib.setErrorForComponentId("form1:inputComponent",
"error01", inputString);
この例では、ページ上の入力コンポーネントの ID は inputComponent であり、それに display error コンポーネントが関連付けられるものとしています。また、リソース・バンドル内のメッセージには、前述の例と同様、キー error01 が含まれています。
- 特定の入力コンポーネントに関連付けられている display error コンポーネントを表示するのではなく、エラー・メッセージを display error コンポーネント上に表示する場合は、変数名を指定せずに、該当するエラー・メッセージを sysLib.setError に渡します。
SysLib.setError("The string is too short.");
例えば、次の JSF ハンドラーは、Web ページの入力コンポーネントに入力された値の長さが十分なものであるかどうかをテストするものです。値が短い場合は、JSF ハンドラーによってエラー・メッセージが表示されます。
handler errorMessageTest type JSFHandler
{view = "errorMessageTest2.jsp",
msgResource = "resourceBundle"}
inputString string;
function validateString()
if (StrLib.characterLen(inputString) < 5)
SysLib.setError(inputString, "error02", inputString);
end
end
end
この例では、前述のとおり、エラー・メッセージ・コンポーネントに関連付けられている Web ページ上の入力コンポーネントに、
inputString 変数がバインドされているものとしています。また、リソース・バンドルには
resourceBundle_locale.properties という名前が付けられています。
locale は、ユーザーが使用している言語のロケール・コードを指します。この例では、次のようなメッセージをリソース・バンドル・ファイル内で使用しています。
error02=The specified value is shorter than five characters: {0}
JSF では、エラー・メッセージ・コンポーネントの値を、ユーザー入力検証の一部として設定することもできます。『エラーの表示』を参照してください。