JavascriptValidator Plugin

Last updated by pdelahun 3 years ago

Javascript Validation Plugin

Overview

This plugin provides client side javascript validation for domain and command objects. The javascript validation is generated from the constraints closure. The client side javascript is all based on the apache commons validator javascript libs.

Author: Peter Delahunty

blog: http://blog.peterdelahunty.com

twitter: http://twitter.com/peterdelahunty

email: peter.delahunty@gmail.com

Compatibility

The plugin is currently compatible with version 1.1 of grails. I will look into making it backward compatible with 1.0x versions.

Installation

Installation is very simple as is all grails plugin installations;

grails install-plugin javascript-validator

Documentation

Usage of the javascript validator plugin is very simple. All you need to do is add the following gsp tag within the html head element of your page.

Example tag:

<jv:generateValidation domain="book" form="bookForm"/>

The example above shows the minimum attributes required for the tag. This example will get the book domain object and generate javascript validation based on its constraints object. You also need to tell the tag the form name that you want to validate against. This expects you have a form tag like so:

Form tag

<form id="bookForm" name="bookForm" onsubmit="return validateForm(this);" action="">

Important! onsubmit attribute

You must also supply the onsubmit attribute on the form. This must call the validateForm function. Just copy the example above. If you don't do this then nothing will work :)

Supported constraints

The following constraints are currently supported.

blank

email

creditCard

matches

nullable

range

Important! try not to use blank.

The plugin supports blank but you might get into a muddle using it. By default grails add the nullable=false constraint to all attributes of a domain object. For all intents and purposes nullable=false and blank=false are the same thing. So DON'T USE BLANK rather rely on the default nullable constraint when you require a field. Also note that nullable=false is NOT default for command object so you must set it explicitly.

Attributes

The jv:generate tag has the following attributes:

form:(required)

This is the name of the form you want to validate against.

domain:(required for domain object validation)

This is the name of the domain object you want to generate validation against. This attribute is required if you want to generate validation for a domain object.

command: (required for command object validation)

This is the full name of the command object. Eg if it is called SearchQueryCommand. Then the command attribute name is searchQueryCommand.

controller: (required for command object validation)

Command objects are associated with controllers to you must supply the controller name that uses this command object.

display:(optional)

Currently the plugin supports two options for displaying the validation error messages to the. These are alert and list.

display=alert:

This is the default display type and will show a popup alert box with the error messages.

display=list:

This will write the errors as ul (list) to the dom of the html page. To use this option you MUST also supply the container attribute.

display=custom:

This will write the errors as ul (list) to the dom of the html page. To use this option you MUST also supply the container attribute.

container(required for display type list)

This is the name of the container element (i recommend a div) where you want the html list of error written to.

handler(required for display type custom)

This is the name of the function to call when validation errors are found. The function should take a single parameter.

order:(optional)

This is a list of field names in the order you would like them displayed. This only works with the list and alert display options.

ignore:(optional)

This is a list of field to ignore. Grails automatically creates nullable constraints for all attributes of a domain class. However you may not be setting them using the form so you can list the ones that you do not want to include in validation generation.

examples

So here are some examples:

1) Domain object Book with alert display

<jv:generateValidation domain="book" form="bookForm"/>

2) Domain object Book with list display

<jv:generateValidation domain="book" form="bookForm" display="list" container="errors"/>

3) Command object DemoCommand on demo controller with alert display

<jv:generateValidation command="demoCommand" controller="demo" form="demoForm" display="alert"/>

4) Command object DemoCommand on demo controller with list display

<jv:generateValidation command="demoCommand" controller="demo" form="demoForm" display="list" container="errors" ignore="['user','account']"/>

5) Command object DemoCommand on demo controller with list display

and ordering

<jv:generateValidation command="demoCommand" controller="demo" form="demoForm" display="list" container="errors" order="['name','email']"/>

6) Command object DemoCommand on demo controller with custom display

<jv:generateValidation command="demoCommand" controller="demo" form="demoForm" display="custom" handler="myHandler" ignore="['user','account']"/><script type="text/javascript">
function myHandler(messagesMap) {    
    for (fieldName in messagesMap) {
        alert( messagesMap[fieldName] );
    }
};
</script>

Important! Errors container recommendations

I recommend that you use a div for your error container element and that you auto hide it by default. The plugin will make it visible when displaying errors.

<div id="errors" class="errors" style="display:none;">
</div>

Internationalization support

Internationalization is supported as normal. The only issue at the moment is entered values cannot be shown as parameters in the error message. I think i can fix this though. Wait for next version.

Road map

Support for validating data types. {DONE FROM VERSION 0.3}

Currently the plugin only support generating validation based on the constraints closure. The first update i am going to add is support for data type validation. It will validate a user is entering an number for an int value etc.

Support for a custom error handling function. {DONE FROM VERISON 0.5}

The java script code taken from Commons validation needs a bit of rework to pass in the field name along with the associated error messages. This would allow you to write custom a javascript error handling function to highlight problem fields on the form.

Support ordering of error messages.{DONE FROM VERISON 0.5}

Order error messages by the field name.

Compressed javascript for production environments

This is really easy as the javascript comes in a compressed form already. I have just not implemented it yet.

Support for more validation constraints

The plugin does not support all constraint validations. So i will try to add them all.

Support for custom validators

You will be able to supply a custom validation function for handling custom validations per field.

Plugin version history

version: 0.1 : released 14 march 2009 First version of the javascript validation plugin. Supports generation of javascript validation based on constraints of domain and command objects.

version: 0.2 : released 14 march 2009 Added support to make error container visible by setting display to block.

version: 0.3 : released 15 march 2009 Added support to for validation data type conversion. Currently only number conversion validation is supported.

version: 0.4 : released 15 march 2009 Added support for a new attribute: ignore. This allows you to specify a list of attributes that you do not want to have javascript validation generated for. This get around the problem of grails auto generating nullable contraints for all properties by default. So simply list the attributes that that are not relevant to the form.

version: 0.5 : released 16 march 2009 Added support for providing an order to your field error messages. Added support for providing a custom callback function for handling error messages.