A função verifier() dos formulários CVT

Como definir a função

A função verifier() de um formulário XXX (que será exibido nos templates por #FORMULAIRE_XXX) é definida no ficheiro formulaires/xxx.php ou no ficheiro formulaires/xxx/traiter.php. O diretório formulaires/ pode ser colocado no diretório de um plugin, ou no diretório squelettes.

A função deve ser chamada como function formulaires_xxx_verifier_dist(). O sufixo _dist permite que, durante o desenvolvimento, seja definida a função para alterar o seu comportamento, criando uma função function formulaires_xxx_verifier()

Os argumentos da função

A função verifier() recebe automaticamente o valor de cada um dos argumentos passados à tag #FORMULAIRE_XX, na mesma ordem.

Por exemplo, ao escrever-se

#FORMULAIRE_XX{#ID_ARTICLE,#ID_RUBRIQUE}

e a função

formulaires_xxx_verifier_dist($arg1,$arg2){
	...
}

$arg1 terá o valor de #ID_ARTICLE, e $arg2 terá o valor de #ID_RUBRIQUE.

O que a função deve fazer

A função verifier() deve receber uma matriz de erros de entradas de dados resultantes da validação dos dados informados.

Se todos os dados forem válidos, a matriz estará vazia e o SPIP chamará então a função traiter() do formulário, encarregada de terminar o trabalho.

Se a matriz enviada pela função verifier() não estiver vazia, a função traiter() não será chamada, o formulário será reapresentado com as eventuais mensagens de erro para que o utilizador faça as correções.

É conveniente fazer todas as validações necessárias ao processamento na função verifier() para garantir a melhor interatividade possível.

Cada erro é enviado na forma de uma associação chave=>valor, e é costume usar como chave o nome da variável usada no formulário.

Exemplo de função verifier()

Vejamos um exemplo

function formulaires_xxx_verifier_dist() {
	$erreurs = array();
	if (!_request('sobrenome')) {
		$erreurs['sobrenome'] = _T('info_obligatoire');
	}
	include_spip('inc/filtres');
	if ($email = _request('email')  AND !email_valide($email)) {
		$erreurs['email'] = _T('form_email_non_valide');
	}
	return $erreurs;
}

Aqui, a função

• verifica se o sobrenome foi devidamente informado, e produz uma mensagem de erro no caso contrário;
• verifica se um endereço de e-mail foi informado, e neste caso verifica a sua validade, com uma mensagem de erro se o endereço de e-mail estiver incorreto.

Campos específicos

A função verifier() pode retornar certos valores específicos na matriz:

message_erreur
Este valor é usado no template do formulário para exibir uma mensagem de erro geral, relativa a todo o formulário.
Cette valeur est utilisée dans le squelette du formulaire pour afficher un message d’erreur général, qui concerne tout le formulaire. É recomendável preencher esta mensagem assim que um erro num campo tenha sido identificado.

message_ok
Este valor permite enviar uma mensagem de sucesso. Esta mensagem pode ser útil quando, por exemplo, o utilizador informou um primeiro valor que possibilita verificar certas informações, sem que o preenchimento do formulário tenha sido concluído.
A presença desta mensagem impede a chamada da função traiter() do formulário. que só é chamada apenas se a matriz retornada por verifier() estiver vazia.

Personalização

Como a função charger(), a função verifier() de um formulário existente pode ser personalizada por dois mecanismos:

Surcharge
Como indicado acima, pode-se redefinir a função verifier() padrão, ao definir a sua própria função function formulaires_xxx_verifier() que será chamada no lugar da função padrão, que possui o sufixo _dist.

Esta substituição poderá ser colocada no ficheiro formulaires/xxx/verifier.php, ou num ficheiro options.php que será chamado a cada hit de modo a que a função seja definida no momento em que o SPIP a procurar.

Pipeline
O pipeline formulaire_verifier permite alterar o resultado da função verifier() padrão de qualquer formulário CVT.

Este é o método que deve ser preferido num plugin.

O pipeline recebe como argumento uma matriz neste formato:

array(
	'args'=>array('form'=>$form,'args'=>$args),
	'data'=>$erreurs
)

Ao escrever a função pipeline neste formato

function monplugin_formulaire_verifier($flux) {
	...
}

Assim encontrará em $flux os elementos a seguir:

Todos os formulários passam pelo mesmo pipeline. Deve-se assim testar o valor de $flux[’args’][’form’] para só alterar o comportamento do formulário xxx.

Ver também as funções charger() e traiter()