XUI Validation

eXtensible Unobtrusive Input Validation

XUI Validation provides client-side input validation for (X)HTML forms.

It can be added to forms as an unobtrusive behaviour layer as long as the forms follow a few simple rules:

  1. All form controls must have a <label> explicitly associated with them (using the for attribute).
  2. Other markup structures can be configured, but by default:
    • All form controls must have a container element with a class of form-element.
    • Groups of radio buttons and checkboxes must have a container element with a class of form-element.
    • Groups of radio buttons and checkboxes must have a label-like element with a class of options-label within the container (usually before the inputs).

Basic validations are very easy to apply, for example: to make an input mandatory you only need to include the scripts and add the required class
to the input.

<div class="form-element">
<label for="input1">
	My first input
	<abbr title="required">*</abbr>
</label>
<input type="text" name="input1" id="input1" class="required" />
</div>

Custom validations are also easy to setup.

Working example

A demonstration of xui-validation is available.

The demonstration page uses a little extra CSS and some images which are available in the package.

Download

XUI Validation is licensed under the The GNU General Public License (GPL), by downloading it you are agreeing to abide by the terms of that license.

Package

Download the complete XUI Validation example package (.zip)

Individual files

Configuration

Edit the configuration block in xui-validation.js to suit the markup of your forms, see the annotated configuration file for detail on each variable.

Extension (custom validations)

Each custom validation is a JavaScript Object added to the global validations array
with the following properties:

match

A string that will select from within the form the controls to apply this custom validation to.

Supported selectors are detailed in the jQuery Selectors documentation.

triggers

An array of the event types that will trigger this validation.

The full list of supported event types are listed in the jQuery bind documentation.

validate

A JavaScript function called for each form control that is matched to be validated, when the specified events are triggered.

this

The variable this in the context of the callback function is the form control element to be
validated. Therefore the value entered by the user can be accessed (for simple controls) using the following jQuery code: $(this).val()

arguments

The function is also sent two arguments:

  1. arguments[0] The event type that triggered the validation (blur, submit, keyup, etc…).
  2. arguments[1] The event object itself.

return

The callback function must return one of the following:

  • true if the input is valid
  • "error message string" if the input is invalid. Messages work best if they are of the form "must contain x" or "can only contain x" or "must be of the format x"
  • null if validity of the content cannot be determined or should not be specified at this time. For example: for a control with a minimum length, it may be confusing to the user to display a "must be at least x characters long" error while the user is trying to type. It is best to return null on ‘keyup’ events, then return the error message if the user moves away from the field (on ‘blur’ events) if their input is still not long enough.

confirmation messages

You can give the user confirmation that what they entered was parsed correctly by calling the updateConfirmation function from within the validate function.

This may come in handy when parsing complex data formats, like a date. For example: if a user enters ’12/06/2008′ you could send the confirmation ’12 June 2008′.

if (parseInt(month)==6){
	updateConfirmation.apply(this, ['June']);
}

See the credit card expiry validation from the custom validations file for a detailed example.

Order of validations

The order of the validations in the array is important. Validations are processed in reverse array order, and the framework will stop and return the first error it discovers.

It is therefore advised to add more specific validations later in the array.

It is also important to note that as the required field validation is processed after custom validations, each custom validation must return true if the input is blank/empty. This ensures the field can be treated independently as required or non-required as needed.

Custom validation example

Below is an example of a custom validation specified in JavaScript Object literal notation to allow only
an integer to be entered into any input fields with a class of integer:

vCount = validations.length;

// integer only fields
validations[vCount++] = {
	'match'    : 'input.integer',
	'triggers' : ['keyup','change','blur','submit'],
	/**
	 * @param DOMElement this The DOMElement for the input that is
	 *        being validated.
	 * @param String arguments[0] The type of event that triggered this 
	 *        validation (example: 'keyup', 'change', etc...).
	 * @param EventObject arguments[1] The EventObject for the event 
	 *        that triggered this validation.
	 * @return Mixed true for success, String for failure (error message), 
	 *         null if validity cannot be determined.
	 */
	'validate' : function () {
		if ($(this).val().match(/[^0-9]/g)) {
			return 'can contain an integer only';
		}
		return true;
	}
};

More details examples are available in the custom validations file.

Disclaimer

  • XUI Validation is provided as is without warranty or guarantee etc…

  • You should never rely on client-side validation alone (it can be easily circumvented by crafty customers).

    Important information should always be (re)validated on the server to ensure security and data-integrity. However client-side validation can help create a friendlier, more responsive user experience.

  • Please don’t submit actual credit card details using the example form.

Posted in

Leave a reply