Differences between revisions 7 and 8
Revision 7 as of 2006-09-30 19:19:57
Size: 8876
Editor: WendySmoak
Comment: Fix the validator name and add comments
Revision 8 as of 2009-09-20 21:52:45
Size: 8905
Editor: localhost
Comment: converted to 1.6 markup
Deletions are marked like this. Additions are marked like this.
Line 6: Line 6:
||<rowbgcolor="#FFFFE0">[http://struts.apache.org/struts-shale/index.html Shale Home]||[:Shale:Wiki Home]||[:Shale/UserDocs:User Docs]||[:Shale/SiteMap:Index]||[:Shale/WikiGuidelines:Guidelines]||[:../:Go Up]|| ||<rowbgcolor="#FFFFE0">[[http://struts.apache.org/struts-shale/index.html|Shale Home]]||[[Shale|Wiki Home]]||[[Shale/UserDocs|User Docs]]||[[Shale/SiteMap|Index]]||[[Shale/WikiGuidelines|Guidelines]]||[[../|Go Up]]||
Line 15: Line 15:
The parameters used to format the [http://svn.apache.org/repos/asf/struts/shale/trunk/core-library/src/java/org/apache/shale/validator/messages.properties error messages] that are shown when a validation error occurs include the incorrect value and any validator-specific 'var' parameters. The parameters used to format the [[http://svn.apache.org/repos/asf/struts/shale/trunk/core-library/src/java/org/apache/shale/validator/messages.properties|error messages]] that are shown when a validation error occurs include the incorrect value and any validator-specific 'var' parameters.
Line 195: Line 195:
  * [http://shale.apache.org/shale-core/apidocs/org/apache/shale/validator/CommonsValidator.html CommonsValidator API]
  * [http://shale.apache.org/shale-core/apidocs/org/apache/shale/component/ValidatorScript.html ValidatorScript API]
  * [[http://shale.apache.org/shale-core/apidocs/org/apache/shale/validator/CommonsValidator.html|CommonsValidator API]]
  * [[http://shale.apache.org/shale-core/apidocs/org/apache/shale/component/ValidatorScript.html|ValidatorScript API]]
Line 199: Line 199:
  * [http://jakarta.apache.org/commons/validator/api-1.2.0/org/apache/commons/validator/ValidatorResources.html ValidatorResources API]
  * [http://jakarta.apache.org/commons/validator/api-1.2.0/org/apache/commons/validator/GenericValidator.html GenericValidator API]

 * David and Mike explaining about the 'required' validator on [http://marc.theaimsgroup.com/?l=struts-dev&m=113624114424542&w=2 MARC] or [http://www.mail-archive.com/dev%40struts.apache.org/msg16825.html mail-archive].

 * Gary's summary of Shale Validator changes on [http://www.nabble.com/Shale-validation-with-custom-rules-t2333950.html#a6500400 nabble].
  * [[http://jakarta.apache.org/commons/validator/api-1.2.0/org/apache/commons/validator/ValidatorResources.html|ValidatorResources API]]
  * [[http://jakarta.apache.org/commons/validator/api-1.2.0/org/apache/commons/validator/GenericValidator.html|GenericValidator API]]

 * David and Mike explaining about the 'required' validator on [[http://marc.theaimsgroup.com/?l=struts-dev&m=113624114424542&w=2|MARC]] or [[http://www.mail-archive.com/dev%40struts.apache.org/msg16825.html|mail-archive]].

 * Gary's summary of Shale Validator changes on [[http://www.nabble.com/Shale-validation-with-custom-rules-t2333950.html#a6500400|nabble]].
Line 210: Line 210:
 * [http://issues.apache.org/bugzilla/show_bug.cgi?id=38042 Bug 38042] - The default validator-rules.xml file is included in shale-core.jar (Since 1.0.1).

 * [http://issues.apache.org/bugzilla/show_bug.cgi?id=38044 Bug 38044] - The filename and location of validator rules files are configurable (Since 1.0.1).
 * [[http://issues.apache.org/bugzilla/show_bug.cgi?id=38042|Bug 38042]] - The default validator-rules.xml file is included in shale-core.jar (Since 1.0.1).

 * [[http://issues.apache.org/bugzilla/show_bug.cgi?id=38044|Bug 38044]] - The filename and location of validator rules files are configurable (Since 1.0.1).
Line 215: Line 215:
''Please address questions about Shale's Commons Validator integration to the [http://shale.apache.org/mail-lists.html shale-user] list.''' ''Please address questions about Shale's Commons Validator integration to the [[http://shale.apache.org/mail-lists.html|shale-user]] list.'''

(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

  • Bug 38042 - The default validator-rules.xml file is included in shale-core.jar (Since 1.0.1).

  • Bug 38044 - The filename and location of validator rules files are configurable (Since 1.0.1).


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)