Client-Side Validation for Vaadin

The CSValidationTextField (suggestions for a better name are welcome) is an extension of the regular TextField. It can validate the user input with a regular expression and/or a JavaScript program. It can report invalid input with style and error message, or prevent typing invalid input altogether.

• The Demo (editors, some validation examples)
• API Documentation
• Browse Sources
• Example Source Code
• Download the JAR from Vaadin Directory

Installation

The Client-Side Validation (csvalidation) components require Vaadin 6.2 or later.

Download the csvalidation-<version>.jar and put it in your library folder in your class path, typically in WebContent/WEB-INF/lib.

Notice: The Vaadin Plugin for Eclipse may suggest to rebuild the widget set. You have to answer Yes and build a new widget set if:

• you have a custom widget set in your project, or

• you include other widget JARs in your project, or

• the precompiled widget set is incompatible with the Vaadin that you use in your project. The widget set in the Jar contains a compiled client-side engine of Vaadin, which will otherwise override the one included in the Vaadin Jar. If the client-side engine is incompatible with the server-side API, it will malfunction. Even if the precompiled widget set works, it may still be older than the client-side engine in the Vaadin Jar.

Say No if the above conditions do not apply, as this will be a bit easier. Otherwise the plugin will create an unnecessary widget set for your project and compile the widget set already included in the csvalidation.jar unnecessarily.

In this case, the plugin does not automatically update the WebContent/WEB-INF/web.xml descriptor of your project to include the widget set, and you need to add the following yourself:

<servlet>
    ...
    <init-param>
        <description>Application widgetset</description>
        <param-name>widgetset</param-name>
        <param-value>com.vaadin.csvalidation.widgetset.CSValidationWidgetset</param-value>
    </init-param>
</servlet>

If you answer Yes, the plugin will create a new widget set for the project, or use an existing one, and add the following line in its .gwt.xml descriptor:

    <inherits name="com.vaadin.csvalidation.widgetset.CSValidationWidgetset" />

The plugin will then compile the widget set.

Notes

You can't trust the client-side code for validation, so you need to validate the input on the server-side as well. For regular expression validation, you can usually use the same expression for the server-side RegexpValidator (just remember that the regular expressions in Java and JavaScript have slightly different syntax). For example:

// The Finnish Social Security Number
final CSValidatedTextField ssn = new CSValidatedTextField("SSN");
String ssn_regexp = "[0-9]{6}[+-A][0-9]{3}[0-9a-zA-Z]";

// The client-side validation
ssn.setRegExp(ssn_regexp, "000000-000A"); // Must give padding
ssn.setPreventInvalidTyping(true); // Prevent typing invalid values

// The server-side validation
ssn.addValidator(new RegexpValidator(ssn_regexp, "Invalid SSN"));
ssn.setRequired(true);
ssn.setRequiredError("SSN is required");

form.addField("ssn", ssn);

You can validate with JavaScript just as easily:

CSValidatedTextField postcode = new CSValidatedTextField("Postal Code");
postcode.setJavaScript("if (value >= 0 && value < 10000)" +
                       "    \"partial\";" +
                       "else if (value >= 10000 && value <= 99999)" +
                       "    null;" +
                       "else" +
                       "    \"Postal Code must be a 5-digit number between 10000 and 99999\";");
layout.addComponent(postcode);

The server-side validation needs separate Java code though, unless you use some JavaScript execution library.

See the example source codes (link above) for more examples.

Included are also handy interactive editors for the regular expressions and JavaScript validators, as you can see in the demo.

Issues

• Matching partially filled values with regular expressions is a problem with no known solution. If you disallow typing invalid input, as in the example above, the validation is mostly restricted to fixed-length fields and requires padding to make partial input valid. If you allow invalid input, there are no restrictions and the fixed-length example is not needed.

• It would be nice to have a type-over input prompt, such as underscores, under the input text.

• The error is now reported with a text span right of the input field. This may not be desired. Alternatives are to use the same error indicator with the error description as tooltip as for server-side errors, or as text below the input box.

• Not sure of the error field causes problems with the calculation of the component widths.

Change Log

Version 0.3.2

• Fixed a JavaScript evaluation problem in Safari (and possibly in other browsers as well).

Version 0.3.1

• Added setValidateEmpty() method that, when set true, forces validation of new fields even when they are empty.
• Enhanced the demo framework greatly

Version 0.3.0

• CSValidatedTextArea for multi-line text area. Setting setRows() does not make the regular CSValidatedTextField multi-line, but you have to use this class.
• New "valid" and "partial" keywords for JavaScript evaluation results that allow specifying a message after the keyword. The valid and partial messages are displayed in the same area as the error messages. This makes creation of various counters, for example, very easy.
• Validation is now done also for empty fields. This may change the behavior of existing applications.
• Upgraded repository from Vaadin 6.2.2 to 6.3.1 and from GWT 1.x to GWT 2.0.

License

This software is licensed under the Apache 2 License.