Por vezes é útil despoletar ações quando o formulário ou algum campo é válido ou inválido.

A versão 2 do Parsley permite a utilização de eventos para este mesmo efeito. Os eventos podem ser usados para alterar o layout ou elementos do DOM ou mesmo para ter acesso à lista de erros do formulário ou dos campos. Em conjunto com os eventos, também iremos analisar como funcionam os objetos do Parlsey.

Existem seis eventos disponíveis (ver documentação) que são despoletados quando:

  1. O Parsley é associado ao formulário ou campo pela primeira vez
  2. Quando o formulário ou o campo é validado (antes de ser executada a validação)
  3. Quando a validação do formulário é concluída
  4. Quando o campo é validado com sucesso
  5. Quando o campo não é validado com sucesso

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

O código relevante do exemplo é:

$.listen('parsley:field:error', function(fieldInstance){
    // carrega todas as mensagens deste campo num array
    var arrErrorMsg = ParsleyUI.getErrorsMessages(fieldInstance);

    // converte o array numa string separada por ;
    var errorMsg = arrErrorMsg.join(';');

    // acesso ao atributo name do elemento
    var fieldName = fieldInstance.$element.attr('name');

    // apresentação de alert message
    alert('Errors for field ' + fieldName + ': ' + errorMsg);
});

Antes de passar à explicação de como funciona o código acima, é importante perceber que o Parsley funciona através de um conjunto de objetos. Isto quer dizer que quando incluem o Parsley na vossa aplicação têm acesso imediato aos objetos Parsley, ParsleyConfig, ParsleyExtend, ParsleyUI, ParsleyUtils e ParsleyValidator. A juntar a estes objetos, quando o Parsley é aplicado num formulário é criado um objeto ParsleyForm associado ao formulário e tantos objetos ParsleyField quantos os inputs a serem validados.

A criação dos objetos é feita no momento em que é aplicado o parsley ao formulário (ou seja, no momento em que fazem $("form").parsley()). Em qualquer momento, após a criação dos objetos, podem ter acesso aos mesmos através do código

// acesso à instância do ParsleyForm
$("#idDoForm").parsley();

// acesso à instância do ParsleyField de um campo
$("#idDoCampo").parsley();

É importante perceber este conceito porque todos os eventos recebem uma instância do objeto ParsleyForm, se forem relacionados com o formulário ou uma instância do objeto ParsleyField, se forem relacionados com o campo. No exemplo acima, estamos a usar o evento parsley:field:error que, como podem perceber, está associado aos campos. Ou seja, o parâmetro recebido no closure será uma instância do objeto ParsleyField.

O evento acima ocorre para cada campo com erros. O código executado pega em todas as mensagens de erro e no atributo name do campo e apresenta essa informação num alert. As mensagens de erro são carregadas através do ParsleyUI (atenção que o nome dos objetos é Case Sensitive) com o método getErrorsMessages(). Este método recebe uma instância do ParsleyField, uma vez que este objeto contém toda a informação sobre o campo.

Desde que tenham acesso à instância do ParsleyField ou ParsleyForm, têm também acesso ao input através do uso da propriedade $element. A partir daí é manipular seletores como de costume no jQuery.

O uso dos eventos é mais útil do que possa parecer no início. São úteis para fazer debug (post do StackOverflow em Inglês) ou até para apresentar as mensagens de erro nas tooltips do Bootstrap (post do StackOverflow em Inglês).

Antes de terminar deixo uma nota para quem pretende desenvolver formulários dinâmicos, ou seja, com a possibilidade de adicionar ou remover campos on-the-fly. Uma vez que os objetos são criados no momento em que o Parsley é aplicado ao formulário, todos os campos que sejam removidos vão continuar a ser validados (assumindo que os estão a remover do DOM) porque o objeto continua a existir. Da mesma forma todos os campos adicionados vão ser ignorados.

Existem duas formas de resolver esta situação:

  1. Controlar que campo é adicionado ou removido. Uma vez que a validação do Parsley pode ser associada diretamente ao campo (não é necessário ser ao formulário - como nota até podem associar a validação a uma div), podem executar o seguinte código para adicionar ou remover um campo da validação:

    //adicionar validação a um campo específico
$("#idDoCampoAdicionado").parsley();

// remover validação de um campo
$("#idDoCampoARemover").parsley().destroy();

  2. Se não quiserem a complexidade de fazer este processo campo a campo, podem fazê-lo ao formulário. No entanto, para formulários com muitos campos, há relatos deste processo demorar algum tempo. Ainda assim, basta destruir os objetos do Parsley e voltar a aplicar ao formulário:

    // destruir todas as instâncias de ParsleyForm e ParsleyField
$("#idDoFormulario").parsley().destroy();

// voltar a aplicar o Parsley ao formulário
$("#idDoFormulario").parsley();