Creating a form with validation and tooltips

This sample shows how to make a create and edit form with validation and tooltips. It demonstrates regular expression validation as well as a more complex validation using a groovy script. 

Download the sample in xar format

You will need to add ValidationSample.Translations to your translations bundles in the Advanced section of the global preferences.

Known issues

The following patches need to be applied on top of XWiki 1.3.2 up to XWiki 1.5 M2:

• http://jira.xwiki.org/jira/browse/XWIKI-2383: "Document.displayPrettyName should look for translations" otherwise the pretty names of fields will not how up.
• http://jira.xwiki.org/jira/browse/XWIKI-2384: "Add optional validation in SaveAction" otherwise the validation will not work when editing a document (using the inline mode).
• http://jira.xwiki.org/jira/browse/XWIKI-2385: "displayPrettyName should show mandatory if param is true regardless of a regular expression setting" otherwise the mandatory modified will not appear for the "age" field.

How does my form look like when validation errors are shown

Documents, Class and Scripts

• ValidationSample.WebHome Home page where you can create a new document and access the existing ones
• ValidationSample.ValidationSampleClassSheet Sheet presenting the document in create, edit and view mode including validation error messages
• ValidationSample.CreateDoc Page called on the submission of the create document form. This will validate and show the form with errors or will save the document.
• ValidationSample.ValidationSampleClass Class with definitions of fields, regular expressions and error message translations strings
• ValidationSample.ValidationGroovy Groovy validation script for complex validations
• ValidationSample.ValidationSampleClassTemplate Template of a document
• ValidationSample.Translations Translations of the texts, tooltips and error messages. This shows an example of the naming conventions for tooltips and pretty names
• ValidationSample.Val, ValidationSample.Val_0, ValidationSample.Val_1 Sample documents

How to create validations using regular expressions

To create validation first you need to declare your class and set the regulare expression to validate the fields you want to validate. 

The following code should be called to launch a validation on a document

The following code is need in the form to launch the validation for a standard Save to validate the form

Pay attention to the Validation Regular Expression and Validation Message fields. The first one is a Java Regular Expression pattern and the second one is a translation string:

• first_name
  • /^.{2,20}$/ -> field needs to be between 2 characters and 20 characters. If the field can have new lines, enable the dotall mode (http://download.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html#DOTALL) by adding an s at the end of the regex (/^.{2,20}$/s) otherwise a regex that contains a new line will not pass validation.
  • val_firstname_toolong -> XWiki will lookup this translation string in the translations pages
• last_name
  • /^.{2,20}$/ -> field needs to be between 2 characters and 20 characters.
• email
  • /.*@.*.com$/-> field must contain @ and finish with .com
• age
  • no validation set for age. This will be handled by the groovy script
• usphone
  • /^[0-9][0-9][0-9]-[0-9][0-9][0-9]-[0-9][0-9][0-9][0-9]$/-> the phone number must be made of digits separated by - in the form 000-000-0000

Other Validation Regular Expression examples:

• do not match XWiki.XWikiGuest, but allow it to be inside the string: /^(?!XWiki.XWikiGuest$).*/
• forbit XWiki.XWikiGuest anywhere in the string: /^(?!.*XWiki.XWikiGuest).*/

How to create validations using a groovy script

To create complex validation you can use a groovy script. 

The following code should be called to launch a validation on a document

The following code is need in the form to launch the validation on a standard Save of a document:

Here is the sample groovy script:

How to display validation error messages

Display all validation error message at the top of the document

The following macro can be used:

This is called using

Display the validation error messages next to the field

The following macro can be used to show the validation error called $message

This is called using

How to create tooltips, mandatory icon and the pretty name

The following macro shows a field including the mandatory field, the tooltip and the pretty name

This is called using:

In addition the following code needs to be called at the end of the page:

The tooltip

The pretty name with mandatory icon

The pretty name without mandatory icon

How to validate and save the document in CreateDoc

Complete presentation sheet of the document

Client side validation with LiveValidation

It's important to have server side validation for security and because not everyone uses Javascript but client side validation
while the user types can improve the user's experience and save server load from forms submitted over and over again.
To do validation on the client side you have to use the LiveValidation Javascript code. You can define your own style for
validation error messages or you can use the style sheet which is used by XWiki.Registration.

Here is a simple example of how to use LiveValidation in XWiki:

The result is this:

This example shows validation of presence (something must be written) and validation of format (testing against a regular expression).
Notice how the first line of Javascript says 'new LiveValidation("helloField"' this binds the validation to field with the id "helloField". Text validation also works on TextAreas.
There are more types of validation which are documented in the LiveValidation documentation.
To change the look and feel of the error message, you may define your own CSS skin extension instead of using the one provided.
All validation messages are of the class LV_validation_message The error messages are of the class LV_invalid and the valid messages are of class LV_valid. LiveValidation will also detect submit buttons and bind to them, blocking them if fields are invalid. There are ways around this such as using propotype's Event.stopObserving function.