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

Como definir a função

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

Esta função deve ser chamada como function formulaires_xxx_charger_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_charger().

Os argumentos da função

A função charger() recebe automaticamente, na mesma ordem, o valor de cada argumento passado à tag #FORMULAIRE_XX.

Por exemplo, ao escrever-se

#FORMULAIRE_XX{#ID_ARTICLE, #ID_RUBRIQUE}

e a função

formulaires_xxx_charger_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 charger() deve retornar uma matriz de valores padrão para cada campo de entrada de dados do formulário.

Esta matriz tem uma função dupla:

• declarar a lista dos campos de entrada de dados (a lista dos «name» dos inputs do formulário)
• fornecer um valor padrão para cada entrada de dados

Os valores padrão fornecidos serão usados na exibição inicial do formulário, sendo sobrescritos pelos dados informados pelo utilizador, no caso da reapresentação do formulário em consequência de um erro de entrada de dados.

Exemplo de função charger()

Vejamos um exemplo:

function formulaires_xxx_charger_dist() {
	$valeurs = array();
	$valeurs['sobrenome'] = 'Informe o seu nome';
	$valeurs['nome'] = '';
	$valeurs['email'] = '';
	return $valeurs;
}

Aqui, a função charger() vai retornar uma matriz associativa com 3 campos: ’sobrenome’, ’nome’, ’email’ e um valor padrão para cada um deles.

Mesmo se o valor padrão estiver vazio, é importante fazer figurar o campo na matrix retornada pela função charger(). Com efeito, o SPIP usa em seguida esta matriz para saber quais campos serão usados.

Não é preciso proteger o valor dos campos se estes contiverem aspas, por exemplo: o SPIP o fará automaticamente.

Cada valor do campo será encontrado no template do formulário HTML com, por exemplo aqui,, #ENV{sobrenome}, #ENV{nome}, #ENV{email}.

Campos específicos

A função charger() pode retornar certos valores específicos

editable
Este valor é usado no template do formulário para permitir ou não a entrada de dados. Por padrão, após o processamento do formulário, «editable» é falso e os campos do formulário não é disponibilizado novamente. Apenas a mensagem de sucesso é exibida.

Pode-se fornecer aqui um valor para «editable» para gerir as condições particulares de ativação ou não do campo do formulário.

message_ok
A mensagem de sucesso é fornecida, em princípio, pela função traiter(). É possível, no entanto, fornecê-la pela função charger() em caráter de exceção.

message_erreur
A mensagem de erro é fornecida, em princípio, pela função traiter(). É possível, no entanto, fornecê-la pela função charger() em caráter de exceção.

action
Este valor especifica o URL em que o formulário é postado. Por padrão, é o URL da página corrente. É importante que permaneça assim como caso geral porque, em caso de erro no preenchimento do formulário, este precisa ser reapresentado.

Em alguns casos excecionais, pode ser útil alterar este URL, o que deve ser reservado a usos muito particulares.

_forcer_request
Por padrão, o SPIP verifica se o formulário postado é o correto, para permitir que existam vários formulários do mesmo tipo numa página, e só processar o que foi submetido. A verificação baseia-se na lista de argumentos passados à tag #FORMULAIRE_XXX.

Em alguns casos, quando esses argumentos são alterados após a entrada de dados, o SPIP pode se confundir e achar que os dados vêm de outro formulário. Ao passar true para _forcer_request, está a indicar que o SPIP não deve fazer essa verificação e que deve tratar os dados em todos os casos.

_action
Se o processamento do formulário xxx precisar chamar uma função do diretório actions/ que é protegido por securiser_action(), é possivel, ao indicar o nome da ação, que o SPIP forneça automaticamente o hash de proteção correspondente.

_hidden
O valor desse campo será incluído diretamente no código HTML do formulário gerado. Ele é usado para incluir inputs hidden que deverão ser escritos explicitamente:

$valeurs['_hidden'] = "<input type='hidden' name='secreto' value='hop' />";

_pipeline
Este campo permite solicitar que o resultado do cálculo do formulário passe pelo pipeline mencionado, permitindo a sua extensão por plugins.

Isto pode ser uma string simples, para definir o nome do pipeline:

$valeurs['_pipeline'] = "meupipeline";

ou uma matriz de dois valores, para especificar os argumentos a serem passados ao pipeline:

$valeurs['_pipeline'] = array("meupipeline", array('arg1' => 'unevaleur', ...));

Prefixação e proteção dos campos de entrada de dados
Por padrão, todos os valores da matriz são protegidos para poderem ser inseridos com total segurança no atributo value de um input no template do formulário. Quando o valor é, ele mesmo, uma matriz, cada um dos seus valores é protegine, e assim sucessivamente.

No entanto, os campos prefixados por um _ (underscore) não serão protegidos automaticamente pelo SPIP. Quando for preciso passar valores ao template que não serão usados pela entrada de dados, é recomendável usar sistematicamente este prefixo.

Além disso, não se deve usar um prefixo _ (underscore) para um campo de entrada de dados, já que o valor informado pelo utilizador será ignorado se o formulário for reapresentado, em caso de erro.

Personalização

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

Surcharge
Como indicado acima, pode-se redefinir a função charger() padrão, ao definir a sua própria função function formulaires_xxx_charger(), 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/charger.php, ou num ficheiro options.php que é sempre carregado.

Pipeline
O pipeline formulaire_charger permite alterar o resultado da função charger() 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' => $valores)
)

Ao escrever a função pipeline neste formato

function meuplugin_formulaire_charger($flux) {
...
}

o seu argumento deverá ter 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 em questão.

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