1 Overview

The JQuery Validation UI Plugin brings Javascript Validator, Remote Constraints, Custom Constraints, jQuery Validation plugin, and qTip (jQuery tooltip plugin) under the same root and delivers a solution that is more than the jQuery Validation Engine. In short, when someone asks you what the JQuery Validation UI Plugin is, just show them the following code block:

Javascript Validator + Remote Constraints + Custom Constraints + jQuery Validation plugin + qTip 
> jQuery Validation Engine

I like the Grails's slogan: "The search is really over!"

1.1 Installation

grails install-plugin jquery-validation-ui

Alternatively, declare a plugin dependency in the grails-app/conf/BuildConfig.groovy file:

plugins {
	compile(":jquery-validation-ui:latest.release")
}

Replace latest.release above with the latest version number, or put it in your BuildConfig verbatim and compile your application and the latest version will be installed automatically.

1.2 Person Sample Application

grails install-sampleapp

The command above not supported since 1.3 released, you may download the sample app created for Grails 1.3.9 using Grails standard theme or Grails 2.1.0 using Twitter Bootstrap theme.

2 Usage

2.1 Configuration

// Added by the JQuery Validation UI plugin:
jqueryValidationUi {
        errorClass = 'error'
        validClass = 'valid'
        onsubmit = true
        renderErrorsOnTop = false
        qTip {
          packed = true
          classes = 'ui-tooltip-red ui-tooltip-shadow ui-tooltip-rounded'  
        }
        /*
          Grails constraints to JQuery Validation rules mapping for client side validation.
          Constraint not found in the ConstraintsMap will trigger remote AJAX validation.
        */
        StringConstraintsMap = [
                blank:'required', // inverse: blank=false, required=true
                creditCard:'creditcard',
                email:'email',
                inList:'inList',
                minSize:'minlength',
                maxSize:'maxlength',
                size:'rangelength',
                matches:'matches',
                notEqual:'notEqual',
                url:'url',
                nullable:'required',
                unique:'unique',
                validator:'validator'
        ]
        // Long, Integer, Short, Float, Double, BigInteger, BigDecimal
        NumberConstraintsMap = [
                min:'min',
                max:'max',
                range:'range',
                notEqual:'notEqual',
                nullable:'required',
                inList:'inList',
                unique:'unique',
                validator:'validator'
        ]
        CollectionConstraintsMap = [
                minSize:'minlength',
                maxSize:'maxlength',
                size:'rangelength',
                nullable:'required',
                validator:'validator'
        ]
        DateConstraintsMap = [
                min:'minDate',
                max:'maxDate',
                range:'rangeDate',
                notEqual:'notEqual',
                nullable:'required',
                inList:'inList',
                unique:'unique',
                validator:'validator'
        ]
        ObjectConstraintsMap = [
                nullable:'required',
                validator:'validator'
        ]
        CustomConstraintsMap = [
                phone:'true',
                phoneUS:'true'
        ]
}

The section above is configuration items of the JQuery Validation UI plugin:

• errorClass - This class used by JQuery Validation library to create error labels, to look for existing error labels and to add it to invalid elements.
• validClass - This class is added to an element by JQuery Validation library after it was validated and considered valid.
• onsubmit = true|false - Default is true. JQuery Validation library validates the form on submit. Set to false to use only other events for validation. The following code trigger validation and submit the form if all inputs are valid:

if ($('form:first').validate().form()) {
   $('form:first').submit();
}

• renderErrorsOnTop = true|false - Default is false. Validation messages will display on the right of input element. Set to true to display all validation messages on the top of the form.
• qTip.packed = true|false - Default is true. Set to false to view a readable .js file for development purpose.
• qTip.classes - Specify the styles of qTip. Refer to qTip style documentation.

errorContainer, errorLabelContainer, errorElement, errorWrapper(wrapper), highlight, unhighlight, onkeyup and qtip configuration items supported since 1.3 released. The added configuration items in version 1.3 except qtip have equivalent options of the JavaScript validate method. Please refer to the validate options documentation for more information.

The qtip configuration item is added to enabled or disabled the display of error message as qtip. qtip is disabled (qtip = false) by default to support non-obtrusive error message display and to make it possible to use the plugin in mobile HTML5 application.

Client side validation enabled by JQuery Validation using Constraints Map, these Constraints Maps specify how Grails constraints map to JQuery Validation rules such as StringConstraintsMap, NumberConstraintsMap, CollectionConstraintsMap, DateConstraintsMap and ObjectConstraintsMap (ObjectConstraintsMap is catch-all map if the property is not belongs to any other Constraints Maps). Refer to JQuery Validation documentation for built-in validation rules supported by the library and additional rules written for this plugin.

CustomConstraintsMap configuration supported since 1.1 released. If previous version of the plugin was installed, upgrade to 1.1 version will not update your Config.groovy file, please update it manually. Please see Extensibility in the features section for more information.

2.2 Resources Plugin Modules

<r:require modules="jquery-validation-ui" />

This correctly inserts all the CSS and javascript required to use this plugin.

2.3 Tags

2.4 Features

Supports All Standard Grails Constraints

As you can see in the StringConstraintsMap, all standard Grails constraints are supported by the plugin.

Display Validation Messages on Right or Top

Display on right:

Display on top:

Note: To see the message style like the screen above, you need to edit line 109 of web-app/css/main.css as per following code:

div.errors {
    margin: 10px 0 5px 0;
    padding: 5px 0 5px 0;
}

Otherwise, you will see the message style like the screen below:

Extensibility

Together with the custom constraints plugin, the plugin is fully extensible with your own custom validation logic.

The plugin come with 2 custom constraints, phone and phoneUS (International and US phone number validation) which enabled by the following configuration:

CustomConstraintsMap = [
    phone:'true',
    phoneUS:'true'
]

If you implement new custom constraints (both server-side and Javascript), you can enable it by adding the constraints to the CustomConstraintsMap, for example:

CustomConstraintsMap = [
    phone:'true',
    phoneUS:'true',
    yourCustomConstraint:'Javascript Code'
]

Internationalization Support

classFullName.property.constraint
classFullName.property.constraint.error
classFullName.property.constraint.invalid
className.property.constraint
className.property.constraint.error
className.property.constraint.invalid

If it is not found, it will use the default message.

Type Validation Support

typeMismatch.java.util.Date
typeMismatch.java.lang.Double
typeMismatch.java.lang.Integer
typeMismatch.java.lang.Long
typeMismatch.java.lang.Short
typeMismatch.java.math.BigDecimal
typeMismatch.java.math.BigInteger

3 Appendices

3.1 Release Notes

26-Mar-2013 1.4.4

• Fixed issue #24: issue #15 broke the display of field values in validation error messages. (by jonroler)

22-Mar-2013 1.4.3

• Fixed spock 0.7.0-2.0 is not compatible with grails 2.1 issue #23. (by jbowen7)

03-Mar-2013 1.4.2

• Fixed missing import RequestContextHolder for issue #14. (by Luis Miguel Gonzalez)

22-Feb-2013 1.4.1

• Fixed Issue #14: No such property: request for class: org.grails.jquery.validation.ui.JqueryValidationService. (by bluesliverx)
• Fixed Issue #15: i18n Messages that have single quotes in them are not escaped properly. (by bluesliverx)
• Fixed Issue #22: Mixing private and public/protected methods… error. (by Michael Kimsal)

01-Sep-2012 1.4

• Set onkeyup default to false to fix issue reported at this thread.
• Major code refactoring: move shared codes from JQueryValidationUiTagLib.groovy to JqueryValidationService.groovy.
• Fixed Issue #4: In JQueryValidationUiTagLib.groovy, improve String concatenation using org.codehaus.groovy.grails.web.pages.FastStringWriter.
• Initial jquery-metadata support via jqueryValidationService.getValidationMetadatas and jqueryValidationService.createJavaScriptConstraints.

14-Aug-2012 1.3

• Fixed Issue #7: Links in jquery.qtip.css are not correct.
• Added errorContainer, errorLabelContainer, errorElement, errorWrapper(wrapper), highlight, unhighlight, onkeyup and qtip attributes for renderValidationScript tag and configuration items. qtip = false (disabled), onkeyup = true (enabled) by default.
• As qtip disabled by default, created jquery-validation-ui-qtip resource module to include qtip resources.
• Remove install-sampleapp script and sample app codes.
• Created 2 sample apps: one for Grails 1.3.9 using Grails standard theme, another one for Grails 2.1.0 using Twitter Bootstrap theme.

29-Jul-2012 1.2.4

• Fixed Issue #8: Added backslash escaping for regex matches and updated version. (by bluesliverx)
• Fixed Issue #12: 'jQueryValidatorUI is not defined' error. (by Kevin Stricker)
• Fixed Issue #13: Failed to resolve dependencies net.sf.json-lib:json-lib:2.4.

11-Jan-2012 1.2.3

• Fixed Issue #19: Allow overriding of submitHandler in generated validation block.
• Fixed Issue #20: Add module definitions to use with the resources plugin.
• First published with the project code at GitHub.
• Converted documentation to Grails Docs (no longer at Google Code).

21-May-2011 1.2.2

• Fixed Issue #12: Unique validation doesn't work for update.

18-Mar-2011 1.2.1

• Fixed Issue #9: Validation matches a-zA-Z+ doesn't support single character
• Fixed Issue #10: In java.lang.Bigdecimal also throw an error for unique and range.
• Fixed Issue #11: Type mismatch custom error message not working.

18-Feb-2011 1.2

• Implemented 3 new custom constraints from jquery validation additional methods: alphanumeric, letterswithbasicpunc and lettersonly. (jqueryValidation.additionalMethods in Config.groovy needs to set to true to use these new custom constraints.)

03-Jan-2011 1.1.1

• Fixed issue #2. Unable to submit the form when remote AJAX validation such as unique and validator constraints enabled.

30-Dec-2010 1.1

• Support Grails 1.2.2+.
• Support extensibility by the custom constraints plugin
• Implemented 2 custom constraints: phone and phoneUS (International and US phone number validation).
• Updated person sample application to demo the phone constraints.

22-Dec-2010 1.0.1

• Make custom taglib work with freemarker-tags plugin

15-Dec-2010 1.0

• Support All Standard Grails Constraints
• Display Validation Messages on Right or Top
• Display both server-side and client-side validation messages using tooltip (qTip) and same styles.
• Internationalization Support
• Remote AJAX Validation Support for unique, validator constraints
• Type Validation Support

3.2 Sites Using This Plugin

• ProcessCanvas.com - Create online workflow in minutes.
• Personal Information System of India e-Government.

3.3 To Do

• Validation message (qTip) support with JQuery UI themes
• Support JQuery UI tooltip after it is released.

We welcome your feedback and would like to hear about your comments to the project. You are invited to join the project discussion on GitHub or on Google Code. See you there!