Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 25 Next »

What is GValidation

GValidation is a validation plugin for Griffon - A Grails like application framework for developing desktop applications in Groovy. Like most part of the Griffon framework GValidation's syntax and usage closely resemble its cousin Grails' validation and constraints support. However the similarity pretty much stops here, since Griffon model are very different from Grails' concept of model. In Grails model usually refers to domain classes that are bound to database, however in Griffon models are usually just mere POGOs thus this plugin is designed to work with Griffon models as well as any POGOs.

GValidation is written purely in Groovy while retaining most of the syntax of Grails constraints support.




Released On    

0.9Updated to Griffon 0.9.5 with bug fixesApr 8, 2012


Updated to Griffon 0.9.4

Oct 30, 2011


Fixed multi-error rendering issue

Sept 10, 2011


Updated to Griffon 0.9.3 with RT support

August 19, 2011


Bug fix minor release

May 13, 2011


Introduced error renderer and widgets    

May 04, 2011


Updated to Griffon 0.9.2

Feb 22, 2011


Updated to Griffon 0.9

Jul 20, 2010

Project Page

GitHub Project Page


GValidation plugin depends on the following libraries, and will automatically add them to your application once the plugin is installed.

Installation & Upgrade

Report a Bug

Please use the Bug Tracker to report any bug you find

How does GValidation work?

Once this plugin is installed, an additional annotation @Validatable will become available to you. Once annotated your model object will have a dynamic field errors and a dynamic method validate injected similar to Grails domain class. The errors field encapsulates all errors generated on a particular model, and the validate method performs validation based on the constraints you configure. Here is a typical usage scenario:

First: Delare Constraints on your Model

Second: Perform Validation in your Controller

Error Messages

Model Specific Error Message Code

All built-in and custom validators provided in this plugin follow the same error message code naming convention. Model specific error message code is generated with the following format:

So as in the previous example the blank constraint on email field will generate error message code:

Default Error Message Code (since v0.3)

Each validator built-in or custom also has a global default error message code associated with in the following format:

So as shown in the previous example you can provide a global error message for blank validator by using:

You can then retrieve the error code and default error code from the Error object using the following fields respectively:

Real Time Validation Support (since v0.8)

Since v0.8 release validation plugin now can automatically trigger validation for Griffon model beans if a realTime flag is set to true in @Validatable annotation.

The real time validation feature is implemented relying on the property change support therefore any property value change, for example triggered by bind{}, will invoke the validation logic associated with that particular property. The actual validation is performed in a separate thread using GriffonApplication.execAsync() before it switches back to EDT for error rendering. Currently this flag only works with Griffon MVC model beans if it is  applied to a regular POGO object the flag will be ignored.


GValidation plugin is shipped with a set of built-in validator or constraints as shown in the above example.


Check if the given String field is blank.



Check if the given field is a valid credit card number.



Check if the given field is a valid email address.



Check if the given field is a valid network address. It can be either a host name or an IP address. (This is GValidation specific constraint not available in Grails.)



Check if the given field is contained in the defined list.



Check if the field matches with the given regular expression.



Ensures a value's size does not exceed the given maximum value. This constraint works with collection, array, as well as string.



Ensures a value does not exceed the given maximum value.



Ensures a value's size does not fall below the given minimum value.



Ensures a value does not fall below the given minimum value.



Ensures that a property is not equal to the specified value



Allows a property to be set to null. By default Grails does not allow null values for properties.



Uses a Groovy range to ensure that a property's value occurs within a specified range. Set to a Groovy range which can contain numbers in the form of an IntRange, dates or any object that implements Comparable and provides next and previous methods for navigation.



Uses a Groovy range to restrict the size of a collection or number or the length of a String. Sets the size of a collection or number property or String length.


To validate that a String value is a valid URL. Set to true if a string value is a URL. Internally uses the org.apache.commons.validator.UrlValidator class.


Adds custom validation to a field. Set to a closure or block to use for custom validation. A single or no parameter block receives the value, a two-parameter block receives the value and object reference. The closure can return: null or true to indicate that the value is valid false to indicate an invalid value and use the default message code


Many of the above explanation were borrowed directly from Grails reference guide

Constraint Inheritence (since v0.6)

Since the constraints are defined using static fields following Grails convention, no real inheritance can be implemented. However since 0.6 release Validation plugin will basically copy the parent class' constraints to the child before performing validation, thus additionally you can also override the parent constraint in the child class. See the following example:

In the above example, the ProtocolSpecificServerParameter will not only inherent ServerParameter's serverName and port fields but also their associated constraints. The only restriction you need to be aware of is if the parent constraint generates error for a certain condition then the overriding child constraint has to generate error as well. In other words, validation plugin does not allow error-hiding by using constraint override in the child class, similar to the method exception treatment during inheritance within Java.

Custom Constraint (since v0.3)

The validator mentioned above allows you to specify a closure as a simple custom constraint easily and quickly however there is no easy way to reuse the closure in other scenarios, hence you will be forced to rewrite the validator each time you use them which is inconvenient and a violation of the DRY principle. Since version 0.3, inspired by Grails Custom Constraint plugin, GValidation plugin now provides you ways to define reusable custom constraints in Griffon.

Once you upgrade the plugin to 0.3 version and above a new artifact type will be added to your Griffon application called Constraint. You can create new constraints by using the new script added by the plugin:

Which in turn will create a Groovy classes under griffon-app/constraints folder with a single method validate defined where you can perform your reusable custom validation logic. A simple custom constraint typically looks like this:class MagicConstraint {

Once created a custom constraint pretty much behaves exactly like a built-in constraint, you can easily invoke them in your model by following the simple naming convention, following the above example you can apply the constraint on any field in your model by using the following declaration:

The GValidation plugin will also take care of the error message code generation for you, as soon as your validate method returns false the plugin will automatically generate error for the appropriate field with the error message code generated by following the same convention as the built-in ones:

Perform Validation

Validate All

As mentioned before once installed the plugin will enhance all your model object to have the additional validate() method, once invoked this method will perform a validate-all executing all constraints on the given model, typical usage scenario:

Selective Validation (since v0.3)

Originally proposed by Andres Almiray, since v0.3 GValidation now offers capability to perform validation on only a selected number of fields in the model instead of all. Here is a typical single field validation usage scenario:

Here is how to perform validation on a multiple fields:

Before Validation Callback (since v0.4)

Inspired by Rails before_validation callback, now GValidation provides a similar pre-validation callback to give model developer a chance to manipulate data right before validation. Here is an example how this kind of callback is defined:

GValidation Errors

Although GValidation is not built on top of Spring Validation framework as the Grails constraints do, it still tries to maintain some sort of API consistency when it comes to error generation. However GValidation only provide a subset implementation of the Spring Error objects in Groovy. For API details please see the Errors and Simple Error classes.

Common Validation Error Usage

Detect Validation Errors

Other than the return value of the validation() method itself, once the validation is complete you can use the hasErrors() method that was dynamically injected on your model to check if there is any validation error. For example:

Reject Object or Field

You can generate global error at the instance level by calling the reject() method on the errors property.

Or reject a specific field using the rejectValue() method.

Later on you can iterate through errors using Groovy iterator

Binding Errors (since 0.4)

Since 0.4 release the dynamic errors field has been enhanced to be Bindable which means you can now directly bind it to your component. It is especially handy when building error notification component such as in the built-in ErrorMessagePanel. Here is how the binding can be achieved in the view with the built-in panel:

i18n (updated with 0.5)

Since v0.5 release Validation plugin now is officially depend on i18n plugin, if your project does not have this plugin installed adding Validation plugin will result i18n plugin being added to your project automatically. GValidation is shipped with a simple generic errorMessages widget to help you display error message easily. Of course you can build your own error message feedback component, it is fairly easy to do that, check out the source code for the built-in ErrorMessagePanel for more details. To use the built-in error panel first declare it in your view:

The following example works with v0.4+ binary, if you are using the older version you need to update the errors manually in ErrorMessagePanel

Later in your controller you can update the error messages:

Enhance POGO with Validation Support

Use @Validatable AST Transformation (Since 0.4)

Since 0.4 release now you can enhance any POGO class in your application by adding the @Validatable annotation at the class level, then Groovy AST transformation will take care of the rest.

This kind of annotated classes will go through essentially the same enhancement as any model class. The only difference is that annotated class is enhanced during build time using AST transformation vs. runtime enhancement as what happen to the model instances.

Error Renderer (since v0.7)

One of the common challenge we face when building UI using any GUI framework is how to effectively and easily notify the user about errors. Ideally a validation framework should not just help developer define constraints and validation logic but also handle the presentation of the error message automatically with little coding involved. With this vision in mind Error Renderer was created.

Error Renderer can be declared easily by using the additional synthetic attribute 'errorRenderer' introduced in 0.7 release. See the following example:

In the above example, two error renderers were declared for the textField widget for the 'email' field in the model. Basically what it means is that if any error was detected for the email field in the model two types of error renderer will be activated to display the error(s). The styles portion of the configuration is optional. If no renderer style is defined, by default highlight renderer will be used. Currently three types of error renderer styles are implemented, I will go through them quickly here.

I. Highlight Error Renderer

This renderer basically change the background color of the component to pink. Mostly it is used for text based input fields. Here is a screen shot of the rendering result.


II. Popup Error Renderer

This renderer display the error message associated with the error using a tooltip-like popup box. Here is a screen shot of the rendering result.


III. On With Error Renderer

This is an invisible renderer that does not render anything itself but switch the component visible attribute on when the error is detected. It is commonly used to display initially invisible custom component when error occurs. This renderer is used in combination of the new errorIcon widget also introduced in this release. Here is a screen shot of it used with errorIcon.


Error Widget

1. Error Messages Widgets

This is basically the old wine in a new bottle. This widget is essentially identical to the ErrorMessagePanel class existed since v0.2 however it is now implemented as a widget to make it easier to use. Usage:

Screen Shot:

2. Error Icon

As mentioned before this widget is mainly used in combination with the onWithError renderer. This icon widget is initially invisible and will only be turned on by the onWithError renderer. Usage:

Screen Shot:

Demo app

A simple demo application can be downloaded from here.

  • No labels