Overview

Frontend form validation

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

Javascript form validation is not necessary, and if used, it does not replace a 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 could 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.6), and it would need to be included before including Parsley.

Then, you can either use parsley.js unminified file or parsley.min.js minified one. These files and other builds (Remote, 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 type="text/javascript">
  $('#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, you have two possibilities:

• Load your needed localization before parsley, then select the one you need once Parsley is loaded and if you want to switch from the English default. In this example, we'll load both French and Italian translations, and use French:

  <script src="jquery.js"></script>
  <script src="i18n/fr.js"></script>
  <script src="i18n/it.js"></script>
  <script src="parsley.min.js"></script>
  <script type="text/javascript">
    window.ParsleyValidator.setLocale('fr');
  </script>
  

• Load your needed localization after parsley. The last loaded file will automatically set the messages locale for ParsleyValidator. In this example, we'll load both French and Italian translations, and use Italian:

  <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, that allows various plugins.

Current available plugins are:

• Parsley Remote: provides an ajax validator and asynchronous validation
• Parsley Extras: provides some extras and useful 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.

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 you 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 you a ParsleyField instance. Except for input types radio and checkbox that does not have a name attribute or a data-parsley-multiple attribute, they won't be bound (ignored) and would eventually raise a warning in the console.

Options

Methods

UI

Global configuration

It is possible to configure Parsley options globally and avoid passing them to each form on your site. To do so, you'll need to define a window.ParsleyConfig = {} object before calling Parsley file.

For example, if you want to customize the field errors and use div and spans instead of ul and lis, use this snippet:

window.ParsleyConfig = {
  errorsWrapper: '<div></div>',
  errorTemplate: '<span></span>'
};
<script src="parsley.js"></script>

Built-in validators

Overview

Parsley 2.x is now based on validator.js that ships commonly used validators and simplifies group and priority validation. That way, Parsley mutualize validators with validators.js and define new ones using the Callback() Assert.

Validators list

These validators are shipped in parsley.js. Have a look at Parsley Remote plugin and Parsley Extras for more 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.

Here again, like localizations, configuring your custom validators and error messages comes with two flavors:

• By registering them in some globals before calling parsley.js:

  <input type="text" data-parsley-multiple="3" />
  [...]
  <script type="text/javascript">
  window.ParsleyConfig = {
    validators: {
      multiple: {
        fn: function (value, requirement) {
          return 0 === value % requirement;
        },
        priority: 32
      }
    },
    i18n: {
      en: {
        multiple: 'This value should be a multiple of %s'
      },
      fr: {
        multiple: 'Cette valeur doit être un multiple de %s'
      }
    }
  };
  </script>
  

• By registering them in ParsleyValidator after that parsley.js is loaded:

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