(original version in Struts Wiki from 2006-03-17 18:20:27 by NiallPemberton)

Shale Home

Wiki Home

User Docs

Index

Guidelines

Go Up


Shale Commons Validator Integration

Validation error messages and the <s:validatorVar> tag

The parameters used to format the error messages that are shown when a validation error occurs include the incorrect value and any validator-specific 'var' parameters.

When the <s:validatorVar> tag is used for validator-specific 'var' parameters, the order in which the 'var's are declared is the order that will be used to format the error message.

For a 'range' validator, such as 'floatRange', the error message pattern is:

errors.range={0} is not in the range {1} through {2}.

Therefore, when using a "range" validator with the <s:validatorVar> tags, specify the "min" var before the "max" var:

<s:commonsValidator type="floatRange"
                     arg="#{msgs.amount}"
                  server="true"
                  client="false">
    <s:validatorVar name="min" value="10"/>
    <s:validatorVar name="max" value="1000"/>
</s:commonsValidator>

Using Custom Validation Rules with Shale

To use a custom validation rule in your application, complete the following steps:

1. Define an xml file conforming to the Commons Validator 1.3.0 dtd.

In this example, the file will be named 'custom-rules.xml' and will be placed in /WEB-INF.

<!DOCTYPE form-validation PUBLIC
          "-//Apache Software Foundation//DTD Commons Validator Rules Configuration 1.3.0//EN"
          "http://jakarta.apache.org/commons/dtds/validator_1_3_0.dtd">
<form-validation>
   <global>
       <validator name="evenInteger"
             classname="com.example.ValidationUtil"
             method="isEven"
             methodParams="int"
             msg="errors.even">
       </validator>
   </global>

   <formset>

      <!-- the 'form name' is always 'org.apache.shale.validator' plus the 'validator name' -->
      <form name="org.apache.shale.validator.evenInteger">

          <!-- the 'field property' always matches the 'validator name' -->
          <field property="evenInteger">

              <!-- validation error message replacement parameters -->
              <arg position="0" name="message" key="submittedValue" resource="false"/>

              <!-- validation method parameters -->
              <arg position="0" name="parameter" key="submittedValue" resource="false"/>

          </field>
        </form>
    </formset>

</form-validation>

2. Write the validation method.

package com.example;
public class ValidationUtil implements Serializable
{
    public static boolean isEven( int value ) {
       return (value % 2 == 0);
    }
}

3. Configure the validation rules in web.xml.

Include the default rule set by listing "/org/apache/shale/validator/validator-rules.xml" in addition to your custom rules.

    <!-- Shale Validator Configuration Resources -->
    <context-param>
       <param-name>org.apache.shale.validator.VALIDATOR_RULES</param-name>
       <param-value>
           /org/apache/shale/validator/validator-rules.xml,
           /WEB-INF/custom-rules.xml
       </param-value>
    </context-param>

4. Provide a resource bundle for messages. (Optional)

The CommonsValidator class reads the messages from the application's resource bundle, then from the 'messages' bundle in org.apache.shale.validator (the (localized) messages.properties file inside shale-core.jar).

If you can use one of the provided messages for your validator, then no action is necessary.

If you need to provide additional messages or override any of the provided messages, here's how:

Configure a resource bundle for your application in faces-config.xml. For example:

    <application>
        <message-bundle>ApplicationResources</message-bundle>
        <locale-config>
            <default-locale>en</default-locale>
            <supported-locale>en</supported-locale>
        </locale-config>
    </application>

And add your message to it. In this example, the file would be '/WEB-INF/classes/!ApplicationResources.properties'.

     errors.even={0} is not an even number.

5. Attach your new validation rule to a component.

In this example, we have a text field called "Priority" which will only accept an even number.

    <h:outputText value="#{messages['prompt.priority']}"/>
    <h:inputText     id="priority"
                  value="#{priority}">
          <s:commonsValidator
                   type="evenNumber"
                 server="true"
                 client="false"/>
    </h:inputText>
     <h:message           for="priority" styleClass="errors"/>

6. Reminders

Be sure to add the <s:validatorScript> at the end of your form, and to set the the 'onsubmit' attribute of the <h:form> tag.

  <h:form onsubmit="return validateForm(this);">
     ...
     <s:validatorScript functionName="validateForm"/>
  </h:form>

ATTENTION: There is an issue with client-side validation in conjunction with using a commandButton for wizard-style "back" navigation. You have to remove the "onsubmit" handler from the form and attach it to the normal "next" commandButton ("onclick" handler) instead. Otherwise the client-side validation will be executed in the "back" navigation case, too (which is not wanted in most cases).

  <h:form>
     ...
     <!-- immediate="true" skips server-side validation -->
     <h:commandButton action="back" immediate="true" ... />
     <h:commandButton action="#{wizard.gotoPage2}" onclick="return validateForm(this.form);" ... />
     <s:validatorScript functionName="validateForm"/>
  </h:form>

Required Validator

The 'required' validator is a special case. The JSF framework will only call a Validator if a value was submitted. Usually, you would set required="true" as an attribute on the input component.

So that you don't have to remember to do something different for 'required', Shale allows <s:validator type="required">, which works by setting the required attribute of the surrounding input component to true.

The 'required' validator is defined in validator-rules.xml as:

      <validator name="required"
            classname="org.apache.shale.validator.CommonsValidator"
               method="isSupplied"
         methodParams="java.lang.String"
                  msg="errors.required">
         <javascript>...</javascript>
      </validator>

However, neither the 'isSupplied' method in CommonsValidator, nor the 'errors.required' message is ever used.

To override the message that is displayed when a required field is missing, add an entry for "javax.faces.component.UIInput.REQUIRED" to your application's message bundle.

References


Enhancements


Please address questions about Shale's Commons Validator integration to the shale-user list.

ShaleValidation (last edited 2009-09-20 21:52:45 by localhost)