VelocityStruts - ErrorsTool

VelocityStruts

その他のサブプロジェクト

This tool deals with Struts error messages. Errors may stem from the validation of a submitted form or from the processing of a request. If there are errors, they are made available to the view to render. A few important aspects about errors are:

Error message strings are looked up in the message resources. Support for internationalized messages is provided.
Error messages can have up to five replacement parameters.
Errors have an attribute property that describes the category of error. This allows the view designer to place error messages precisely where an error occurred. For example, errors that apply to the entire page can be rendered at the top of the page, errors that apply to a specific input field can be rendered next to this input field. Several methods of this tool provide a parameter property that allows to select a specific category of errors to operate on. Without the property parameter, methods operate on all error messages.

このツールは Struts のエラーメッセージを提供します。エラーはサブミットされたフォームの検証中、あるいはリクエストの処理中に発生します。エラーが起きた場合、ビューへの出力を生成できるようになります。エラーについて抑えておくべき重要な点は:

エラーメッセージはメッセージリソースから取得されます。国際化されたメッセージの提供がサポートされています。
エラーメッセージは置換パラメータを5つまで持つことができます。
エラーはエラーカテゴリを示す property 属性を持ちます。これはビューデザイナがエラーが発生した場所に適切にエラーメッセージを配置することを可能にします。例えば、ページの全体に対してのエラーはページの一番上に表示し、特定の入力フィールドに対してのエラーはこの入力フィールドの隣りに表示することができます。このツールのいくつかのメソッドは、処理対象とする特定のエラーカテゴリを選択できる property パラメータを提供します。 property パラメータを指定しない場合、これらのメソッドは全てのエラーメッセージを処理します。

See the Struts User's Guide, section Building View Components for more information on this topic.

この話題のより詳細については Struts ユーザガイドの Building View Components の章を参照してください。

Class
	org.apache.velocity.tools.struts.ErrorsTool
Name
	$errors (Velocityコンテキスト内での推奨名)
Toolbox設定例
	<tool> <key>errors</key> <scope>request</scope> <class>org.apache.velocity.tools.struts.ErrorsTool</class> </tool>
作者
	Gabriel Sidler

Method Overview

exist()	Returns `true` if there are errors queued, otherwise `false`.
getSize()	Returns the number of error messages queued.
getGlobal()	This a convenience method and the equivalent of `$errors.get($errors.globalName)`
getAll()	Returns a list of localized error messages for all errors queued.
get()	Returns a list of localized error messages for a particular category of errors.
getMsgs()	Renders the queued errors messages.

Method Overview

exist()	エラーメッセージがある場合に`true`を返却、その他の場合`false`。
getSize()	エラーメッセージの数を返却します。
getGlobal()	これは`$errors.get($errors.globalName)`と同等の簡易メソッドです。
getAll()	全てのメッセージについての地域化されたエラーメッセージのリストを返却します。
get()	指定されたカテゴリのエラーについての地域化されたエラーメッセージのリストを返却します。
getMsgs()	エラーメッセージを表示します。

exist()

Returns true if there are errors queued, otherwise false.

boolean exist()

boolean exist(String property)

Parameters

property: The category of errors to check for.

Returns: true if there are error messages queued. false otherwise.

Calling exist() without the property parameter checks for error messages of any category. The property parameter can be used to limit the check to error messages of a specific category.

$errors.exist()
$errors.exist("password")

エラーメッセージがある場合にtrueを返却、その他の場合false。

boolean exist()

boolean exist(String property)

Parameters

property: チェックするエラーのカテゴリ。

Returns: エラーメッセージがある場合にtrueを返却、その他の場合false。

property パラメータを指定せずに exist() を呼び出すと全てのカテゴリのエラーメッセージがチェックされます。 property パラメータは特定カテゴリのエラーメッセージのチェックに使用します。

$errors.exist()
$errors.exist("password")

getSize()

Returns the number of error messages queued.

int getSize()

int getSize(String property)

Parameters

property: The category of errors to operate on.

Returns: The number of error messages.

Calling getSize() without the property parameter returns the total number of queued error messages. The property parameter can be used to obtain the number of queued error messages for a specific category.

$errors.getSize()
$errors.size
$errors.getSize("password")

エラーメッセージの数を返却します。

int getSize()

int getSize(String property)

Parameters

property: 対象とするエラーのカテゴリ。

Returns: エラーメッセージの数を返却します。

property パラメータを指定せずに getSize() を呼び出すと全てのカテゴリのエラーメッセージの総数を返却します。 property パラメータは特定カテゴリのエラーメッセージの数を取得するときに使用します。

$errors.getSize()
$errors.size
$errors.getSize("password")

getGlobal()

This a convenience method and the equivalent of $errors.get($errors.globalName)

List getGlobal()

Returns: A list of all errors stored under the "global" property.

See the section on get() for more information.

これは$errors.get($errors.globalName)と同等の簡易メソッドです。

List getGlobal()

Returns: "global"プロパティの全てのエラーのリスト

より詳細についてはget()セクションを参照してください。

getAll()

Returns a list of localized error messages for all errors queued.

List getAll()

List getAll(String bundle)

Parameters

bundle: The (non-default) message-resources bundle that holds the error messages.

Returns: If the message resources are lacking an error message for a particular message key, the key itself is used as an error message and a warning is logged.

The following example shows a macro to render the error messages:

#macro (errorMarkup)
    #if ($errors.exist)
        <ul>
        #foreach ($e in $errors.all )
            <li>$e</li>
        #end
        </ul>
    #end
#end

This produces output similar to the following:

<ul>
    <li>The field Expiration Date is required.</li>
    <li>The provided number is not a valid credit card number</li>
</ul>

全てのメッセージについての地域化されたエラーメッセージのリストを返却します。

List getAll()

List getAll(String bundle)

Parameters

bundle: エラーメッセージを保持する(デフォルトではない)メッセージリソースバンドル。

Returns: 特定のメッセージキーのエラーメッセージがメッセージリソースに無かった場合、そのキー自体がエラーメッセージとして使用され、このとき警告がロギングされます。

以下の例はエラーメッセージを表示するマクロです:

#macro (errorMarkup)
    #if ($errors.exist)
        <ul>
        #foreach ($e in $errors.all )
            <li>$e</li>
        #end
        </ul>
    #end
#end

これは以下のような出力を生成します:

<ul>
    <li>フィールドExpiration Dateは必須です。</li>
    <li>入力された番号は有効なクレジットカード番号ではありません。</li>
</ul>

get()

Returns a list of localized error messages for a particular category of errors.

List get(String property)

List get(String property, String bundle)

Parameters

property: The category of error messages to return.
bundle: The (non-default) message-resources bundle that holds the error messages.

Returns: A java.util.List of java.lang.String. If no error messages exist for the specified category, null is returned. If the message resources are lacking an error message for a particular message key, the key itself is used as an error message and a warning is logged.

The following example shows a macro to render the error messages for a particular category of errors:

#macro (errorMarkup $property)
    #if ($errors.exist($property))
        <ul>
        #foreach ($er in $errors.get($property) )
            <li>$er</li>
        #end
        </ul>
    #end
#end

This produces output similar to the following:

<ul>
    <li>The field Expiration Date is required.</li>
    <li>The provided number is not a valid credit card number</li>
</ul>

指定されたカテゴリのエラーについての地域化されたエラーメッセージのリストを返却します。

List get(String property)

List get(String property, String bundle)

Parameters

property: 返却するエラーメッセージのカテゴリ。
bundle: エラーメッセージを保持する(デフォルトではない)エラーリソースバンドル。

Returns: java.lang.String の java.util.List 。指定されたカテゴリにエラーメッセージが無い場合には、 null を返却します。特定のメッセージキーのエラーメッセージがメッセージリソースに無かった場合、そのキー自体がエラーメッセージとして使用され、このとき警告がロギングされます。

以下の例は特定のエラーカテゴリのエラーメッセージを表示するマクロです:

#macro (errorMarkup $property)
    #if ($errors.exist($property))
        <ul>
        #foreach ($er in $errors.get($property) )
            <li>$er</li>
        #end
        </ul>
    #end
#end

これは以下のような出力を生成します:

<ul>
    <li>フィールドExpiration Dateは必須です。</li>
    <li>入力された番号は有効なクレジットカード番号ではありません。</li>
</ul>

getMsgs()

Renders the queued errors messages.

String getMsgs()

String getMsgs(String property)

String getMsgs(String property, String bundle)

Parameters

property: The category of errors messages to render.
bundle: The (non-default) message-resources bundle that holds the error messages.

Returns: The formatted error messages. If no errors are queued, an empty String is returned.

This method renders the queued error messages as a list. If the method is called without a parameter, all queued errors are rendered. With the parameter property the list of rendered messages can be limited to a specific category of errors. Error message texts are looked up in the message resources. If a message text cannot be found, the message key will be displayed instead.

The method expects a message header and a message footer to be defined in the message resources. The corresponding message keys are errors.header and errors.footer.

Assuming that the message resources contain the following definitions:

errors.header=Please correct the following errors:<ul>
errors.footer=</ul>
error01=<li>The field Expiration Date is required.</li>
error02=<li>The input is not a valid credit card number.</li>
...

an error message would be rendered as follows:

Please correct the following errors before proceeding:<ul>
    <li>The field Expiration Date is required.</li>
    <li>The input is not a valid credit card number.</li>
</ul>

エラーメッセージを表示します。

String getMsgs()

String getMsgs(String property)

String getMsgs(String property, String bundle)

Parameters

property: 表示するエラーメッセージのカテゴリ。
bundle: エラーメッセージを保持する(デフォルトではない)メッセージリソースバンドル。

Returns: フォーマットされたエラーメッセージ。エラーが無い場合、空の String が返却されます。

このメソッドはエラーメッセージをリストとして表示します。パラメータ無しで呼び出した場合、全てのエラーが表示されます。 property パラメータを指定した場合、特定のカテゴリのエラーのメッセージリストを表示します。エラーメッセージの文字列はメッセージリソースから取得されます。メッセージが見つからなかった場合、メッセージのキーを代わりに表示します。

このメソッドはメッセージヘッダとメッセージフッタがメッセージリソースに定義されていることを前提とします。これらのメッセージのキーは errors.header と errors.footer です。

メッセージリソースが以下のように定義されている場合:

errors.header=以下のエラーを修正して下さい:<ul>
errors.footer=</ul>
error01=<li>フィールドExpiration Dateは必須です。</li>
error02=<li>入力された番号は有効なクレジットカード番号ではありません。</li>
...

エラーメッセージは以下のように表示されます:

以下のエラーを修正して下さい:<ul>
    <li>フィールドExpiration Dateは必須です。</li>
    <li>入力された番号は有効なクレジットカード番号ではありません。</li>
</ul>

[訳注: この文書は Shinobu Kawai 木村貴由が翻訳しました。日本語訳に対するコメントがあれば、report@jajakarta.orgに送って下さい。]