Version 1.5glow.forms.Form

Validating Forms

Glow can be used to add validation to forms by defining constraints and limits to the values that are permitted in your form fields, and to display error messages in cases where those values fall outside those limits.

Contents

1. Forms and Fields
2. Adding Tests
3. Custom Error Messages
4. Adding More Complicated Tests
5. Adding Tests That Apply to Other Fields
6. Running Tests
7. Types of Tests
8. Running Tests Via AJAX

Forms and Fields

You need to first create a glow.forms.Form object before you can add tests to the various fields in your form.

<form id="register"> <!-- for example -->
</form> <script> var myForm = new glow.forms.Form("#register");
</script>

Once you have a glow.forms.Form object you can add tests to it.

Adding Tests

A "test" is a condition associated with a form field. The condition must pass in order for the value in that field to be considered valid. For example a test called "required" means that a value must not be empty in order to be valid.

Use the addTests method to add tests to a glow.forms.Form object.

myForm.addTests( "username", // the field we are testing has the name "username" ["required"] // a valid username value cannot be empty
);

You can add multiple tests to a field if you wish. Each test will be run in the order which you add them.

myForm.addTests( "username", // the field we are testing has the name "username" ["required"], // a valid username value cannot be empty ["isEmail"] // and must be formatted like an email address
);

You can add tests to several fields by chaining the addTests calls together.

myForm.addTests( "email_address", ["isEmail"] // email_address must be formatted like an email address
)
.addTests( "user_age", ["isNumber"] // user_age must be a number
);

Custom Error Messages

You can provide a custom error message if the default one is not what you want.

myForm.addTests( "age", ["min", { arg: "16", message: "You must be at least 16 years old to sign up for the newsletter." }]
);

Adding More Complicated Tests

Some tests require additional information from you. For example the "minLen" test means that a value must be at least a given number of characters long to be valid. To specify what the minimum length is you must provide an argument, like so:

myForm.addTests( "username", ["minLen", { arg: 3 // must be at least 3 characters long }] );

Another example is the "sameAs" test which says a value in the given field must be the same as the value in another field.

myForm.addTests( "email_confirm", ["sameAs", { arg: "email" // must be the same as the email value }] );

Adding Tests That Apply to Other Fields

In some cases you don't want to run any of your tests on the current field unless a test first passes on another field. This is called a "conditional test". You use the "field" property to specify the name of the other field.

myForm.addTests( "email_confirm", ["isEmail", {field: "email"}], // only when the email field is an email ["sameAs", {arg: "email"}] // do we test if they are both the same
);

Note that if the conditional test fails (for example if the "email" field were empty) then result is that all subsequent tests are skipped. This doesn't mean the test failed, it simply means the tests weren't run because the precondition wasn't met.

Running Tests

Now that you have added tests to a form, you may want to control when those tests will actually run. By default every test will run when the form is submitted, but you can override this behaviour:

myForm.addTests( "username", ["required", {on: "change"}] // validate this whenever it is changed
);

There are several supported event names that can be used:

submit

Run the test when the form is submitted (this is the default whenever no event is specified).

change

Run the test when the value in the field is changed and the focus leaves the field.

click

Run the test when the field is clicked. This is useful for radio and checkbox inputs.

idle

Run the test when there is a non-empty value in the field that has changed and a short period of inactivity has passed.

You can add multiple event names to a single test if you wish to run that test in response to several events.

myForm.addTests( "username", ["required", {on: "change submit idle"}]
);

Types of Tests

There are many built-in tests that you can use, or you can define your own custom tests.

Available test types

Creating Custom Tests

You can write your own tests if none of the built-in tests do what you need.

Your custom function will receive the following arguments:

values

An array of every value in the form associated with the field name of this test.

opts

The options object the user passed into the addTests method.

callback

A function that you must call to signal that the test is complete. You should pass this callback a boolean or numeric value that evaluates to true or false, and an optional message to be displayed.

formData

A JSON object that represents all the values in the form this test is attached to.

myForm
.addTests( "username", ["custom", { arg: function(values, opts, callback, formData) { // note: `values` is always an array, even if there is only one value for (var i = 0, len = values.length; i < len; i++) { if (values[i] == "Jake") { callback(glow.forms.FAIL, "The name Jake is not allowed."); return; } } callback(glow.forms.PASS, "Good name."); } }]
);

Running Tests Via AJAX

If your test requires a server-side process to run you can use the ajax test to send data to a URL and interpret the results.

You should define two properties of your options object:

arg

A function that will interpret the response from the server. This function will receive an argument of type glow.net.Response and must return a boolean or numeric value that evalutes to true or false.

url

The URL of the server-side process. Due to cross-site scripting restrictions this must be on the same domain as the one where the JavaScript is running. You can insert values into the URL by using placeholders such as: /cgi/checkname.cgi?name={username}

myForm
.addTests( "username", ["ajax", { arg: function(response) { // return true for pass, or false for fail }, url: "/cgi/checkname.cgi?name={username}" }]
);