Validações personalizadas com Parsley.js

A introdução ao Parsley é suficiente para formulários relativamente reduzidos ou sem necessidade de muita personalização. Para formulários mais complexos pode ser necessária a aplicação de validações personalizadas, eventos ou a alteração das opções.

Neste post apresentamos validações personalizadas, como utilizar os eventos disponibilizados pelo Parsley e como submeter um formulário por AJAX, que seja validado com o Parsley.

Vamos começar por submeter um formulário via AJAX, uma vez que o Parsley já necessita da inclusão do jQuery.

$(document).ready(function() {
    $("form[name=myForm]").parsley();

    $("form[name=myForm]").on('submit', function(e) {
        var f = $(this);
        f.parsley().validate();

        if (f.parsley().isValid()) {
            alert('O formulário é válido');
            $.ajax({
                url: f.attr('action'),
                data: f.serialize(),
                type: 'post',
                dataType: 'json',
                success: function(response) {
                    alert('O formulário foi submetido com sucesso');
                },
                error: function() {
                    alert('Ocorreu um erro ao submeter o formulário');
                }
            });
        } else {
            alert('O formulário não é válido');
        }

        e.preventDefault();
    });
});

Como apresentado, é obrigatório aplicar o parsley ao formulário através de $("form[name=myForm]").parsley();. Depois é necessário associar o evento submit do formulário, de forma a ser possível controlar o processo de submissão.

Dentro do evento submit é feita a validação do formulário pelo Parsley através do código $(this).parsley().validate();. Automaticamente é feita a validação de acordo com os atributos de cada input e são apresentadas as mensagens de erro, caso existam. Depois deste processo, é necessário saber se a validação teve um resultado positivo e, em caso afirmativo, submeter o formulário por AJAX.

A verificação de sucesso na validação é feita com o código $(this).parsley().isValid(), que devolve true caso o formulário seja válido ou false caso contrário. Esta notação é usada a partir do Parsley 2.x, na versão 1.x a notação era um pouco diferente.

Na minha opinião, a submissão de formulários por AJAX é preferível porque, além de ser mais rápida (evitando reloads desnecessários) também deixa de existir a preocupação de voltar a colocar os valores nos campos, caso a submissão não tenha sucesso.

Uma opção importante do Parsley é a possibilidade de usar validações personalizadas. Talvez o melhor exemplo para este tipo de situações seja um formulário de registo, onde é necessário garantir que o nome de utilizador de quem se está a registar ainda não existe na base de dados. Nestas situações é possível recorrer às validações personalizadas do Parsley

É possível adicionar as validações personalizadas ao Parsley antes ou depois da biblioteca ser incluída. Para o propósito destes exemplos vamos aplicar as validações depois do plugin ser incluído.

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

A validação é adicionada através de Javascript, usando window.ParsleyValidator.addValidator('customValidation', function(value, requirement)). Para aplicar a validação ao input, deve usar-se o atributo data-parsley-customValidation (como se pode ver no campo username do formulário).

Neste caso, a validação faz um pedido AJAX onde é enviado o campo username via $_GET. No servidor deve ser verificada a existência do valor na base de dados e, caso exista, devolver uma resposta com o código HTTP 404 (na verdade, qualquer código começado por 4 funciona). Caso o nome de utilizador não exista (e, consequentemente, o campo é válido), deve ser enviada uma resposta com o código HTTP 200.

O closure passado para o addValidator recebe os parâmetros value e requirement. O value é o valor introduzido no input. O requirement (não usado no exemplo) serve para passar outro valor para a validação. Na documentação é apresentado um exemplo em que o valor deve ser múltiplo de um outro valor (3, no caso da documentação).

Para fazer uso do requirement é necessário atribuir um valor ao atributo do input. Algo como data-parsley-something='1234'. Por vezes pode ser conveniente ter acesso a outros inputs dentro da validação e podemos fazê-lo através do requirement, passando o identificador do input. Com este código data-parsley-something='input[name=email]' podemos aceder ao campo email, na validação, através de jQuery.

Se procuras uma introdução ao Parsley.js lê o artigo com a introdução ao Parsley.js.