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.

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

<tool>
  <key>errors</key>
  <scope>request</scope>
  <class>org.apache.velocity.tools.struts.ErrorsTool</class>
</tool>

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.

See Also

The Javadoc for more info.

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")

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")

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 Also

The the section on get() for more information.

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>

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>

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, a message footer, a message prefix and a message suffix to be defined in the message resources. The corresponding message keys are errors.header, errors.footer, errors.prefix and errors.suffix.

Assuming that the message resources contain the following definitions:

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

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>