Introduction

Getting started

Guards is a plugin for jQuery that provides a simple, chainable, declarative API for guarding your forms against invalid user input. To get started, include the guards.js file after jQuery, and start declaring your guards. Note that you do not need to include this in a document.onready callback. All guarding happens via delegated events, which means the elements need not yet be defined. They can be defined later on, or even be added to the DOM after some user input.

Let's get started with an example. Go ahead and try to submit the form without any input. The inputs are guarded with the default guard, which is the "required" guard, which ensures something has been provided.

Now let's break down what is happening. The first line in the script guards anything that matches the "form#form1 input[type='text']" selector (which happens to be both text fields in the form). The second line enables guards for the form, which hooks up events that prevent the form from submitting if any of the guards fail to pass.

All guards automatically have delegated events hooked up (regardless of if enableGuards is called for that form) which will clear errors when the user starts to change that field.

Some built in guards

Customizing how guards work is pretty easy, but before we get into deep customization, let's look at some of the built in guards. To specify a built in guard, simply call the using method with the name of the built in guard you would like to use. Try out the following form with some of the built in guards.

Other ways of guarding the form

The enableGuards function shown above is not the only way to guard forms. There are two other ways of guarding forms. There is the enableGuards method on the jQuery object, which will guard forms that have been selected via a jQuery selector. This differs from the other function in that it will not affect forms that are created at a later point. This means it must be called after the document is ready, or at least after the form has been declared.

The other method is liveGuard, which takes a selector and "live guards" any forms that match the selector. This uses delegated events like the first enableGuards, so it can be done outside document.onready callbacks. A live guard is a guard that will trigger errors as soon as the user changes a field. The field will still trigger errors on submit, but user changes make it easy for the user to realize mistakes as they happen. Note that for text fields, the change won't trigger the error until the focus leaves the field.

Try out the alternative methods below:

next