Please turn on JavaScript. To find out how to do this visit the WebWise JavaScript guide.

Collection of built-in tests that can be added to any form field as a way of validating that field's value.

You do not need to call these functions directly, the devloper use a test by passing its name to the addTests method.

For more information about tests, how to create your own custom tests, or to see what arguments these tests take, you may refer to the Creating Custom Tests section of the Validating Forms user guide.

Further Info & Examples

Methods

ajax

Send the data to the server for testing.

Synopsis

glow.forms.tests.ajax();

Description

A request to the given URL will be made and the response will be passed to the given callback.

'arg' is the function to handle the response from the server.

This function should return a truthy value to indicate whether the server response should be considered a PASS or a FAIL. Optionally you can include a bespoke error message by returning an array of two elements, the first being the PASS or FAIL verdict, and the second being the error message to display.

'url' is the url to call. You can use placeholders in here for form values (see example).

Example

myForm.addTests(
  "username",
  ["ajax", {
    url: "/cgi/checkname.cgi?name={username}",
    arg: function (response) {
      if (response.text() == "OK") {
        return glow.forms.PASS;
      } else {
        return [glow.forms.FAIL, "That name is already taken."];
      }
    },
    message: "The server responded: that name is not permitted."
  }]
);
count

There must be exactly the given number of values submitted with this name.

Synopsis

glow.forms.tests.count();

Description

This is useful for multiple selects and checkboxes that have the same name.

Example

myForm.addTests(
  "fieldName",
  ["count", {
    arg: "2"
  }]
);
custom

Create a custom test.

Synopsis

glow.forms.tests.custom();

Description

'arg' is a function which tests the form value.

The function is given the following parameters:

values
An array of values submitted for that form field. If you are only expecting one value, it can be accessed via values[0]
opts
An object of any additional data included with the test
callback
This is a function used to tell Glow whether the test has passed or not. A callback is used rather than 'return' to allow async tests. The first parameter is either glow.forms.PASS or glow.forms.FAIL, the second is the success or failure message.
formData
This is an object of all values captured in the form.

Example

myForm.addTests(
  "username",
  ["custom", {
    arg: function(values, opts, callback, formData) {
      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.");
    }
  }]
);
is

The value must be equal to a particular value

Synopsis

glow.forms.tests.is();

Example

// this test ensures "other" is required *if* the "reason" field is equal to "otherReason"
myForm.addTests(
  "other",
  ["is", {
    field: "reason",
    arg: "otherReason"
  }],
  ["required"]
);
isEmail

The value must be a valid email address.

Synopsis

glow.forms.tests.isEmail();

Description

This checks the formatting of the address, not whether the address exists.

Example

myForm.addTests(
  "fieldName",
  ["isEmail"]
);
isNot

The value must not be equal to a particular value

Synopsis

glow.forms.tests.isNot();

Example

// you may have a dropdown select where the first option is "none" for serverside reasons
myForm.addTests(
  "gender",
  ["isNot", {
    arg: "none"
  }]
);
isNumber

The value must be a valid number.

Synopsis

glow.forms.tests.isNumber();

Description

A field that is empty, or contains a value that is not a number like 1 or 3.14 will fail this test.

Example

myForm.addTests(
  "fieldName",
  ["isNumber"]
);
max

The numeric value must be no more than the given value.

Synopsis

glow.forms.tests.max();

Description

A field whose value, when converted to a number, is not more than the given arg will fail this test.

Example

myForm.addTests(
  "fieldName",
  ["max", {
    arg: "100"
  }]
);
maxCount

There must be no more than the given number of values submitted with this name.

Synopsis

glow.forms.tests.maxCount();

Description

This is useful for multiple selects and checkboxes that have the same name.

Example

myForm.addTests(
  "fieldName",
  ["maxCount", {
    arg: "10"
  }]
);
maxLen

The value must be at most the given number of characters long.

Synopsis

glow.forms.tests.maxLen();

Example

myForm.addTests(
  "fieldName",
  ["maxLen", {
    arg: "24"
  }]
);
min

The numeric value must be at least the given value.

Synopsis

glow.forms.tests.min();

Description

A field whose value, when converted to a number, is not less than the given arg will fail this test.

Example

myForm.addTests(
  "fieldName",
  ["min", {
    arg: "1"
  }]
);
minCount

There must be at least the given number of values submitted with this name.

Synopsis

glow.forms.tests.minCount();

Description

This is useful for multiple selects and checkboxes that have the same name.

Example

myForm.addTests(
  "fieldName",
  ["minCount", {
    arg: "1"
  }]
);
minLen

The value must be at least the given number of characters long.

Synopsis

glow.forms.tests.minLen();

Example

myForm.addTests(
  "fieldName",
  ["minLen", {
    arg: "3"
  }]
);
range

The numeric value must be between x..y.

Synopsis

glow.forms.tests.range();

Description

A field whose value, when converted to a number, is not more than x and less than y will fail this test.

Example

myForm.addTests(
  "fieldName",
  ["range", {
    arg: "18..118"
  }]
);
regex

The value must match the given regular expression.

Synopsis

glow.forms.tests.regex();

Example

myForm.addTests(
  "fieldName",
  ["regex", {
    arg: /^[A-Z0-9]*$/
  }]
);
required

The value must contain at least one non-whitespace character.

Synopsis

glow.forms.tests.required();

Description

A text input field that is empty, or contains only spaces for example will fail this test.

Example

myForm.addTests(
  "fieldName",
  ["required"]
);
sameAs

The value must be the same as the value in the given field.

Synopsis

glow.forms.tests.sameAs();

Example

myForm.addTests(
  "email_confirm",
  ["sameAs", {
    arg: "email"
  }]
);
Documentation generated by JsDoc Toolkit 2.1.0 on Thu Jul 07 2011 12:47:29 GMT+0100 (BST)

BBC navigation

BBC © 2014 The BBC is not responsible for the content of external sites. Read more.

This page is best viewed in an up-to-date web browser with style sheets (CSS) enabled. While you will be able to view the content of this page in your current browser, you will not be able to get the full visual experience. Please consider upgrading your browser software or enabling style sheets (CSS) if you are able to do so.