• Flowplayer
• jQuery Tools
• Login
• Logout

Usage

You take any form you like, spice it up with new HTML5 input types and attributes and make a single call to jQuery Tools validator. Here is the HTML layout for the example form above:

<form id="myform">
  <fieldset>
    <h3>Sample registration form</h3>
    <p> Enter bad values and then press the submit button. </p>
 
    <p>
      <label>email *</label>
      <input type="email" name="email" required="required" />
    </p>
    <p>
      <label>website *</label>
      <input type="url" name="url" required="required" />
    </p>
    <p>
      <label>name *</label>
      <input type="text" name="name" pattern="[a-zA-Z ]{5,}" maxlength="30" />
    </p>
    <p>
      <label>age</label>
      <input type="number" name="age" size="4" min="5" max="50" />
    </p>
    <p id="terms">
      <label>I accept the terms</label>
      <input type="checkbox" required="required" />
    </p>
    <button type="submit">Submit form</button>
    <button type="reset">Reset</button>
  </fieldset>
</form>

And here is the validator call that enables form validation:

$("#myform").validator();

When the form is submitted the validator will make sure that the input fields pass all the rules that are defined for them. If there are any errors an error message appears above all failed fields. When the user starts fixing the values each error message will magically disappear once the input is valid. Look at the minimal setup for more details.

Validating inputs without a form

The tool validates all input fields except buttons and hidden fields inside a particular form. You can also select particular fields and validate them. For example:

  // initialize validator for a bunch of input fields
  var inputs = $("#mydiv :input").validator();
 
  // perform validation programmatically
  inputs.data("validator").checkValidity();

Since v1.2.3 another $("...").validator() call would destroy the existing instance and will install a completely new validator instance.

Demos

Please study the first demo "Minimal setup for Validator". It teaches you the basics of form validation.

• ${demo.title}

Supported HTML5 features

jQuery Tools Validator adds new input types and attributes to your form construction arsenal.

HTML5 input types

Now you can specify more than just "text", "checkbox" or "radio" for your type attribute. Here are the new types supported by validator:

HTML5 range and date types are also supported by using the rangeinput and dateinput Tools. Empty values are allowed for all input types. If you don't want to allow empty values use the required attribute.

For jQuery users the :email, :number and :url selectors are available for convenience.

HTML5 Attributes

HTML4 Attributes

These good old HTML4 attributes have a role in form validation and will make your forms more user friendly:

Note: all the above attributes can be changed dynamically using jQuery's attr method. For example:

$("fieldset:eq(1)").attr("disabled", true);

In addition to the above HTML attributes, jQuery Tools allows you to implement your own custom attributes for validation.

Configuration

Error message positioning

The error message position is specified with two different configuration properties: position and offset. The position property specifies the position in relation to the input field. For example, a value of 'bottom center' will place the message on the bottom edge of the input, centered horizontally. The following image illustrates the "slots" that you can use:

The offset property fine tunes the tooltip position specified with the position property. For example, the value [10, -20] moves the tooltip position 10px downwards and 20px to the left. The first value modifies the vertical positioning from the top edge of the tooltip and the second value modifies the horizontal positioning from the left edge of the tooltip. Positive values move the tooltip downward and to the right, while negative values move the tooltip upward and to the left.

Localization

The default error messages are contained in the $.tools.validator.messages object. Here is a screenshot of all the messages contained inside the validator as seen from the Firebug console.

The default error messages are in English. The * message is shown if there is no validator specific message available. If you want to provide error messages in other languages, use the $.tools.validator.localize method as follows:

  $.tools.validator.localize("fi", {
  ':email'  		: 'Virheellinen sähköpostiosoite',
  ':number' 		: 'Arvon on oltava numeerinen',
  '[max]'	 		: 'Arvon on oltava pienempi, kuin $1',
  '[min]'	 		: 'Arvon on oltava suurempi, kuin $1',
  '[required]' 	: 'Kentän arvo on annettava'
  });

The first argument is the language code and the second argument is an object containing the localized messages. After calling the localize command you can check that everything went well with the Firebug console:

The :email and :number localizations are opened. more… indicates objects that can be opened to inspect localized messages. As you can see, this is not the case for * and :url which were not localized. The $1 tokens in [max] and [min] are replaced with proper values once the message is shown to the user. You can take advantage of this variable substitution feature in your own custom validators.

Now if you want to use the Finnish localization in your form you need to set the lang configuration variable to "fi":

  $("#myForm").validator({lang: 'fi'});

Localizing single validator

Sometimes you just need to localize a single validator function. In that case you can use the $.tools.validator.localizeFn function. For example:

  $.tools.validator.localizeFn("[type=time]", {
  en: 'Please supply a valid time',
  fi: 'Virheellinen aika'
  });

This will modify existing languages and/or add new ones for this single validator only. Note that with both localization functions you can generate the messages dynamically via JavaScript if you need to. Localization objects are plain old and dynamic JavaScript objects after all.

Input specific error message

You can explicitly define the error message for a field that is shown when validation fails. It can be defined with the data-message attribute. For example:

  <input type="number" min="10" data-message="A larger value is needed" />

This will override any other error messages that are defined for the validation error. The drawback here is that you can only supply a single error message although there may be many different validation errors and that this error message cannot be localized. Of course you can supply a different value for this attribute on the server-side.

Here is the order in which the error message is selected starting from the step 1 and if none of the steps result in any error message then the final option is shown.

1. a value specified in the data-message attribute
2. a validator specific error message that matches the language specified in the lang configuration option
3. the default error message that is configured with the asterisk (*) in the $.tools.validator.messages object

As you might have noticed, the name of the data-message attribute features a somewhat cumbersome data- prefix. This actually makes the attribute valid HTML5, and your fields will successfully pass a HTML5 validator. If you are one of those people who do not care about techy standards and want your forms to be more readable, you can change the name of this attribute from within the configuration using the messageAttr configuration variable.

Making custom validators

jQuery Tools Validator makes it easy to create new input types and attributes. When building your forms you'll typically use the built-in HTML5 features and also add a couple of your own custom validators. Here is an example:

// make a HTML5 "time" input type
$.tools.validator.fn("[type=time]", function(el, value) {
  return /\d\d:\d\d/.test(value) ? true : "Invalid time";
});

You can find more examples here. Here is the $.tools.validator.fn and its arguments explained:

$.tools.validator.fn(matcher, [errorMessages], validator)

As you can see you can supply error messages in two ways: as the second argument to the $.tools.validator.fn function as well as by returning them from the validator function. When supplying them as the second argument you can take advantage of the centralized language configuration where the error messages can be changed and new languages can be added. When returning error messages from your validator you have much greater control of the dynamic construction of the error messages, but the messages are hard-coded inside your function.

If your validator function provides error messages in both of the previous ways, the one that is returned by the validator function takes precedence.

Variable substitution

This feature is best explained by way of an example:

$.tools.validator.fn(
    "[type=range]",
    "Value must be between $1 and $2",
    function(el, v) {
 
        // get min and max for this field from the (HTML5) attributes
        var min = el.attr("min"), max = el.attr("max"), value = parseFloat(v);
 
        // if the value is inside the range return true otherwise
        // return values for replacement
        return  value >= min && value <= max ? true : [min, max];
    }
);

The error message given in the second argument contains two replacement tokens, $1 and $2, which will be expanded to the respective values of the two members in the Array returned by the validator function: [value1, value2].

Function matcher

Instead of a jQuery selector you can use a function to determine which fields are to be validated by your custom validator. For example:

  // 1st argument provides the function matcher
  $.tools.validator.fn(function()  {
 
  // returning true means that a match was found
  return $(this).parents("form.register").length > 0;
 
    // 2nd argument provides the actual validator function
    }, function(el, v) {
 
    // do your validation. return true if the value is valid
    return true;
 
    });

Our matcher only selects inputs that are within a form with class name "register". This is probably not a real world situation, but it does show you how it works. You have complete control over the selection.

Localization & function matchers

You can return the error message from the validator function directly. If you want to take advantage of the $.tools.validator.messages object in your localization, we need to have a key for your matcher. The key is given as a property of the validator function as follows:

  // define the function matcher
  function myMatcher() {
  return $(this).parents("form.register").length > 0;
  }
 
  // supply a key for the matcher
  myMatcher.key = "register-input";
 
  // use the "localized" matcher on our validator
  $.tools.validator.fn(myMatcher, "Please fix this value", function(el, v) {
 
  // do your validation. return true if the value is valid
  return true;
  });

Now you can inspect the custom validator in the $.tools.validator.messages object (last line):

Scripting API

First make sure you have familiarized yourself with jQuery Tools scripting.

Events

First make sure you have read about Events in jQuery Tools. All event listeners receive an Event Object as the first argument.

You can view a demo here about validator events.

Field specific events

If you want to listen to validation errors on a field level you have the oninvalid method available. For example

  $("[name=password]").oninvalid(function(event, errorMessage) {
 
  // get handle to the API
  var api = $(this).data("validator");
  });

Server-side integration

Here is the logic taken from the server-side validation demo. Please read the comment blocks and see the natural and standards-based syntax.

  // initialize validator and add the custom form submission logic
  $("#myform").validator({ position: 'center right' }).submit(function(e) {
 
  var form = $(this);
 
  // client-side validation passed
  if (!e.isDefaultPrevented()) {
 
  // submit the data to the server with AJAX
  $.getJSON(form.attr("action") + "?" + form.serialize(), function(json) {
 
  // everything is ok. (the server returned true)
  if (json === true)  {
  form.load("success.php");
 
  // server-side validation failed. use invalidate() to show errors
  } else {
  form.data("validator").invalidate(json);
  }
  });
 
  // prevent default form submission logic
  e.preventDefault();
  }
  });

Here we used the simple return value true to indicate that the data was valid on the server-side. You can do whatever you wish when the data is good. Here we replaced the form contents with a server-side page. If the data was not valid we use the invalidate method to display errors to the user. The invalidate method accepts an object argument which maps a field name to an error message like this:

  {
  "zip": "You must live in northern Finland in order to proceed",
  "total": "You gave us too much money! Please check"
  }

You can switch the language of the errors on the server. Note: jQuery 1.4+ requires that both labels and values are quoted with double quotes on the returned JSON.

Making custom effects

The default validator effect is responsible for displaying the validation errors beside each input field and when the user fixes the problems the effect hides the associated error messages accordingly. If you want to alter this behaviour you can write your own custom validator effect. For example, you may want to show those errors in a single container instead of beside each input field.

Custom effects are added with the $.tools.validator.addEffect method. This method accepts three arguments. The first argument is the effect name, the second argument is a function that is called when there are validation errors available and the third argument is a function that is called when an input field switches from an invalid to a valid state. Here is an example:

  // adds an effect called "wall" to the validator
  $.tools.validator.addEffect("wall", function(errors, event) {
 
  // "show" function
  $.each(errors, function(index, error) {
 
  // erroneous input
  var input = error.input;
 
  // error messages for the input (Array)
  var errors = error.messages;
  });
 
  }, function(inputs)  {
  // "hide" function
 
  });

The show function receives two arguments. The first argument is an array of Error objects. Each error object has two properties: input, which is the erroneous input, and messages which is an array of error messages. The second argument is the event that fired the validation. This may be the form submission or a change in an input field.

The hide function receives a jQuery object containing all input fields that are switching to a valid state after being invalid.

Take a look at a simple custom validator effect in action.

• report a bug »
• 
• What's new in v1.2.6 »