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

Como definir a função

A função traiter() 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_traiter_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_traiter()

Os argumentos da função

Como as funções charger() e verifier(), a função traiter() recebe automaticamente, na mesma ordem, o valor de cada um dos argumentos passados à tag #FORMULAIRE_XX.

Por exemplo, ao escrever-se

#FORMULAIRE_XX{#ID_ARTICLE,#ID_RUBRIQUE}

e a função

formulaires_xxx_traiter_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 traiter() faz todos os processamentos necessários a seguir à entrada de dados do utilizador, e após as validações feitas pela função verifier().

O ponto importante aquié que a função traiter() será sempre chamada logo após a função verifier() e apenas se esta retornou uma matriz vazia, significando a ausência de erros.

Uma vez realizadas as ações (por exemplo: registo dos dados, escrita num ficheiro, envio de e-mail ...), a função traiter() deve devolver uma matriz de valores descrevendo o resultado da ação.

Esta matriz devolvida por traiter() deve incluir pelo menos um de dois valores: message_ok ou message_erreur para indicar o sucesso ou insucesso do processamento.

message_ok
Se tudo correu bem, mostrar o resultado numa mensagem permite que o utilizador se assegure que a ação foi realizada. É uma boa prática sempre exibir uma mensagem, mesmo que tudo corra bem!

message_erreur
Apesar das validações realizadas pela função verifier(), o processamento pode falhar por outras razões não detetadas à partida. Neste caso, a função traiter() indica a causa do erro em message_erreur, e o utilizador será informado do problema.

editable
Por padrão, após o preenchimento do formulário e o seu processamento com sucesso, os campos do formulário não é disponibilizado novamente. Apenas a mensagem de sucesso é exibida.

Ao enviar um valor true para este campo, permite que o utilizador preencha novamente o formulário.

id_xx
Se o processamentoinseriu ou alterou um (ou vários) dado na base, é recomendável enviar as chaves primárias, geranmente iniciadas por id_, dos registos em causa.

Assim, um plugin que intervenha em seguida ao tratamento por padrão saberá em qual objeto executou a ação e poderá agir complementarmente.

redirect
Basta indicar um URL neste campo para redirecionar o utilizador para outra página, após a submissão.

Atenção, é importante que a função traiter() não faça, ela mesma, o redirecionamento, já que isso impediria a intervenção de um plugin após a função traiter().

Exemplode função traiter()

Vejamos um exemplo

function formulaires_xxx_traiter_dist() {
	$res = array();
	$nom = _request('sobrenome');
	$prenom = _request('nome');
	$email = _request('email');
	
	include_spip('action/editer_auteur');
	if ($id_auteur = insert_auteur()) {
		auteurs_set($id_auteur,array('nome'=>"$nome $sobrenome",'email'=>$email));
		$res['message_ok'] = "Registo realizado!";
		$res['id_auteur'] = $id_auteur;
	}
	else {
		$res['message_erreur'] = "Ocorreu um problema, não foi possível registar os seus dados.";
	}
	return $res;
}

Aqui, a função

• recupera as informações digitada;
• inclui um autor na tabela de autores do SPIP;
• regista os nome, sobrenome e e-mail informados pelo autor;
• indica no resultado o id_auteur incluído, bem como a mensagem de sucesso.

Se o autor não pôde ser incluído, é mostrada uma mensagem de erro.

Casos particulares

Os formulários podem ser facilmente processados por ajax, ao incluir uma classe ajax. As funções charger(), verifier() e traiter() ficam sem saber e não vêem nenhuma diferença.

No entanto, às vezes é preciso que a função traiter() não seja chamada por ajax. Por exemplo, porque ela irá alterar consideravelmente a base de dados e é preferível que toda a página seja reexibida após a submissão, e não apenas o formulário.

Neste caso, é preciso iniciar a função traiter() com uma chamada à função refuser_traiter_formulaire_ajax().

Se o formiulário não foi submetido por ajax, esta função não fará nada e, em seguida, a função traiter() será executada normalmente.

Se o formulário foi submetido por ajax, essa função vai parar tudo e enviar um código específico ao Javascript da página. Ao receber o código, o Javascript provocará um novo envio dos dados do formulário, desta vez sem ajax. O SPIP irá novamente chamar a função verifier(), e depois a função traiter(), que, desta vez, será executada completamente e poderá realizar as suas operações.

Assim, é fundamental que a função traiter() se inicie com esta chamada a refuser_traiter_formulaire_ajax(), e não faça nenhuma manipulação antes de chamar essa função, senão essas eventuais operações serão executadas duas vezes.

Personalização

Como as funções charger() e verifier(), a função traiter() de um formulário existente pode ser personalizada por doisa mecanismos:

Surcharge
Como indicado acima, pode-se redefinir a função traiter() padrão, ao definir a sua própria função
function formulaires_xxx_traiter(), 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/traiter.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_traiter permite alterar o resultado da função traiter() 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'=>$res)
)

Ao escrever a função pipeline neste formato

function meuplugin_formulaire_traiter($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()
• verifier()

Em programmer.spip.net

• o pipeline formulaire_traiter
• os formulários CVT
• outros exemplos