Overview

Frontend form validation

Parsley is a javascript form validation library. It helps you provide your users with feedback on their form submission before sending it to your server. It saves you bandwidth, server load and it saves time for your users.

Javascript form validation is not necessary, and if used, it does not replace strong backend server validation.

That's why Parsley is here: to let you define your general form validation, implement it on the backend side, and simply port it frontend-side, with maximum respect to user experience best practices.

Data attributes

Parsley uses a specific DOM API which allows you to configure pretty much everything directly from your DOM, without writing a single javascript configuration line or custom function. Parsley's default DOM API is data-parsley-. That means that if in config you see a foo property, it can be set/modified via DOM with data-parsley-foo="value".

Configuration

You'll see along this documentation and through examples various available configuration options. You can also view here all of Parsley's default configuration options.

Installation

Basic installation

Parsley relies on jQuery (>= 1.8), and it will need to be included before including Parsley.

You will also need to include es5-shim if you want need to support IE8.

Then, you can either use parsley.js unminified file or parsley.min.js minified one. These files and extras are available here.

Finally, add data-parsley-validate to each <form> you want to be validated.

That would look pretty much like this:

<script src="jquery.js"></script>
<script src="parsley.min.js"></script>

<form data-parsley-validate>
...
</form>

Javascript installation

Like for Basic installation, first include jQuery and Parsley. Then, simply use $('#form').parsley(options); or new Parsley('#form', options); (where options is an optional configuration object) to manually bind Parsley to your forms.

That would look pretty much like this:

<script src="jquery.js"></script>
<script src="parsley.min.js"></script>

<form id="form">
...
</form>

<script>
  $('#form').parsley();
</script>

Localization

Parsley comes with various error messages for its built-in validators. They are shipped in English by default, but many other languages are available, thanks to the awesome international Parsley community. See the available localizations here.

To load a different locale and its messages, include them after Parsley:

<script src="jquery.js"></script>
<script src="parsley.min.js"></script>
<script src="i18n/fr.js"></script>
<script src="i18n/it.js"></script>

Plugins

Parsley strives to be highly decoupled and modular. It uses events and inheritance, and allows various plugins.

Current available plugins are in Extras for additional validators.

Usage

Overview

Parsley is a decoupled library that uses different classes to do the heavy work. You'll see here the different protagonists involved and how you can configure them to fit your desired validation.

Configuration

Data attributes and javascript

The multiple options can be specified using data attributes and javascript:

<input id="first" data-parsley-maxlength="42" value="hello"/>
<input id="second" value="world"/>
[...]
<script>
var instance = $('#first').parsley();
console.log(instance.isValid()); // maxlength is 42, so field is valid
$('#first').attr('data-parsley-maxlength', 4);
console.log(instance.isValid()); // No longer valid, as maxlength is 4
// You can access and override options in javascript too:
instance.options.maxlength++;
console.log(instance.isValid()); // Back to being valid, as maxlength is 5
// Alternatively, the options can be specified as:
var otherInstance = $('#second').parsley({
  maxlength: 10
});
console.log(otherInstance.options); // Shows that maxlength will be 10 for this field

As shown in the previous example, Parsley will actualize the options from the data attributes whenever it needs to validate a field.

Option inheritance

Field instances inherit their options from Form instances, and both inherit from the global options. This is a handy way to configure all your form's inputs in a row by passing their config through form.

<form>
  <input/>
</form>
[...]
<script>
Parsley.options.maxlength = 42;
var formInstance = $('form').parsley();
var field = $('input').parsley();
console.log(field.options.maxlength); // Shows that maxlength is 42
Parsley.options.maxlength = 30;
console.log(field.options.maxlength); // Shows that maxlength is automagically 30
formInstance.options.maxlength++;
console.log(field.options.maxlength); // Shows that maxlength is automagically 31

The previous example shows that the inheritance of options is automagic. In case you are wondering, they are linked through prototype to achieve this.

Naming

You can change the DOM API namespace directly using the namespace option. Data attributes with compound names are camelcased for javascript, and their values are automatically converted to the appropriate type (boolean, integer, etc.). For example:

<input data-my-namespace-priority-enabled="false">
[...]
<script>
var instance = $('input').parsley({namespace: 'my-namespace-'});
if (false === instance.options.priorityEnabled)
  console.log("priorityEnabled was set to false");

Form

When doing $('#target').parsley() or new Parsley('#target'); on a <form id="target"> element, it will bind the whole form and its various inputs and return a ParsleyForm instance.

Options

data-parsley-excluded="input[type=button], input[type=submit], input[type=reset], input[type=hidden], [disabled], :hidden"

Methods

UI

Field

When doing $('#target').parsley() or new Parsley('#target'); on a <input id="target"> element (or <textarea>, <select>), it will bind the field and return a ParsleyField instance. Except for input types radio and checkbox that don't have a name attribute or a data-parsley-multiple attribute, they won't be bound (ignored) and will eventually raise a warning in the console.

Options

Methods

UI

Built-in validators

Overview

A validator is a method to determine if a given value (or sometimes sets of values) is acceptable or not, given some requirement parameters.

Parsley comes with many builtin validators and provides tools to specify your own.

Builtin validators list

These validators are shipped in parsley.js. Have a look at Parsley Extras for more validators.

Custom Validators

Craft yours

Of course, Parsley built-in validators are commonly used validators, and you'll need some more that fit your specific forms and validations. That's why Parsley lets you easily create your own validators.

The preferred way to register them (after parsley.js is loaded) looks like:

<input type="text" data-parsley-multiple-of="3" />
[...]
<script>
window.Parsley
  .addValidator('multipleOf', {
    requirementType: 'integer',
    validateNumber: function(value, requirement) {
      return 0 === value % requirement;
    },
    messages: {
      en: 'This value should be a multiple of %s',
      fr: 'Cette valeur doit être un multiple de %s'
    }
  });
</script>

The following sections go over the details on how to define a custom validator

Validating function

There are many ways a validator can specify how to validate data:

Your custom validator must specify at least one of these. If it can validate both single inputs and multiple (i.e. checkboxes), then you can specify validateMultiple and one of the other two.

Validating functions should return either true if the value is valid, or false otherwise. It can instead return a jQuery promise that will be resolved if the value is valid, or be rejected otherwise.

Validators can reject with a custom error message as a first argument if desired.

Requirement parameters

You can specify what kind of requirement parameter your custom validator is expecting:

You can also specify an array of these kinds. For example, if a validator has requirementType: ['integer', 'integer'], then given the requirement string "[1, 2]" it will receive 1 and 2 as second and third arguments (the first one being the value(s) to validate).

For cases where more complex parameters are needed, you can specify extra parameters; refer to the source and check how the remote validator uses that.