³ÉÈËÂÛ̳

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"
  }]
);