Events and objects in Parsley.js

Sometimes it’s useful to trigger some actions when your form of field is validated.

Parsely 2.x allows you to use trigger events to this end. Events can be used to change DOM elements or to get access to the list of error messages for the form of fields. We’ll also take a look at the objects created by Parsley and how do they work.

There are six different types of events (take a look at the documentation) that are triggered when

Parsley is bound to the form or the field
When the form of field validation is started
After the form validation is executed
When the field is successfully validated
When the field has an error

See the Pen Parsley 2.0 - Events demo by Luís Cruz (@milz) on CodePen.

The relevant code in the example is:

$.listen('parsley:field:error', function(fieldInstance){
    // loads all error messages for the current field in an array
    var arrErrorMsg = ParsleyUI.getErrorsMessages(fieldInstance);

    // implodes the array elements into a string separated by ;
    var errorMsg = arrErrorMsg.join(';');

    // access the DOM element and retrieve the attribute name
    var fieldName = fieldInstance.$element.attr('name');

    // display the field name and error list in an alert message
    alert('Errors for field ' + fieldName + ': ' + errorMsg);
});

Before we start to explore the above code it’s important to understand that Parsley works with a set of Javascript objects. This means that when you include Parsley, you will have access to the following objects Parsley, ParsleyConfig, ParsleyExtend, ParsleyUI, ParsleyUtils e ParsleyValidator. In adition to these, you’ll also have a ParsleyForm object when Parsley is bound to a form and as many ParsleyField objects as the number of fields to be validated.

These objects are created at the moment where you bind Parsley to the form (meaning that they are created when you execute $("form").parsley()). At any moment after this code is executed, you can access the instances through:

// access the ParsleyForm instance
$("#formId").parsley();

// access the instance of ParsleyField related to a field
$("#FieldId").parsley();

It’s essencial that you understand this concept since every event is passed and object instance of ParsleyForm (when the event is related to the form) or ParsleyField (if the event is related to a field. In the above example we’re using the parsley:field:error event which is related to a field. This means that the closure parameter will be an instance of the ParsleyField object.

The above event is executed once for each field with errors. The code will get all the error messages and the attribute name for each field and shows that information in an alert message. We get the list of error messages with the object ParsleyUI (this is case-sensitive) and the getErrorsMessages() method. This method receives an instances of ParsleyField.

As long as you have access to an instance of ParsleyField or ParsleyForm, you’ll also have access to the input of form DOM through the $element property. After that, you can use the usual jQuery selectors.

The events are more useful than they may seem at the beggining. They are useful with debug purposes (Stackoverflow post) and you can even use them to display the error messages in Bootstrap’s tooltips (StackOverflow post).

Finally I would like to leave a note for forms where you can add or remove fields on-the-fly. Since the objects are created at the moment when you bind Parsley, they will remain even if you delete the fields from the DOM. So, if you remove a field after the object’s creation, that field will still be validated. Any other field added to the DOM will not be validated.

There are two ways to solve this:

Monitor which field is added or removed. Since you can bind Parsley directly to your field (for that matter, you can even bind Parsley to a div element), you can execute the following code to add or remove the validation for a specific field:
```
//add validation to a specific field
$("#fieldId").parsley();

// remove existing validation for the field
$("#fieldId").parsley().destroy();
```
If you don’t want the hassle of controlling the fields, you can solve this issue at the form’s level. However, there have been users complaining about the time needed for this process. Still, if you don’t have that many fields, this should work:
```
// destroy all instances of ParsleyForm and ParsleyField
$("#formId").parsley().destroy();

// bind Parsley to the form
$("#formId").parsley();
```