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.
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.

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

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

HashMap getAll()

Returns

If the message resources are lacking an error message for a particular message key, the key itself is used as error message and an error 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.

ArrayList get(String property)

Parameters

property

The category of errors to return.

Returns

A java.util.ArrayList 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 error message and an error 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)

Parameters

property

The category of errors messages to render.

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>