Formulários CVT multi-páginas

Os templates de cada página

Cada página do formulário se apresenta como um formulário completo (com um botão de validação que serve para passar à etapa seguinte).

Cada etapa é numerada, a partir de 1, e definida por um template independente que implementa um formulário autonomo para as entradas de dados dessa página.

Para a etapa 1, o template é formulaires/inscricao.html.
Para a etapa 2, le squelette est formulaires/inscricao_2.html.
Para a etapa 3, le squelette est formulaires/inscricao_3.html.

Veja, por exemplo, como se parece a primeira página do nosso formulário:

<div class="formulaire_spip">
	[<p class="reponse_formulaire reponse_formulaire_ok">(#ENV*{message_ok})</p>]
	[<p class="reponse_formulaire reponse_formulaire_erreur">(#ENV*{message_erreur})</p>]
	[(#ENV{editable})
	<form method='post' action='#ENV{action}'><div>
		[(#REM) os campos ocultos que acionarão o serviço do formulário; parâmetro: url da ação ]
		#ACTION_FORMULAIRE{#ENV{action},#FORM}

                <!-- Aqui os dados da etapa 1, diretamente em HTML. 
                       Elas também podem ser geradas pelo plugin ENTRADAS PARA FORMULÁRIOS  -->
                 <label>Seu e-mail</label>
                 <input type='text' name='email' value='#ENV{email}' />               
                 <input type="submit" class="submit" value="<:pass_ok:>" />
         </div></form>
	]
</div>

Em cada template, #ENV{_etape} encaminha o número da etapa, e #ENV{_etapes} encaminha o número total de etapas de entrada de dados. Isso permite, por exemplo, exibir um indicador de avanço da entrada de dados em relação ao número total de páginas de entrada de dados:

<div class="formulaire_spip formulaire_inscription formulaire_#FORM  formulaire_#FORM_#ENV{_etape}">
	<h3>Inscrição  #ENV{_etape} / #ENV{_etapes}:informe o seu e-mail</h3>
... 

A cada página, #ENV contém todos os valores já informados nas etapas precedentes. Desse modo, se você quiser propor um valor padrão que dependa de um valor já informado, poderá recuperá-lo para preencher o seu campo.

Em cada página, também é possível oferecer um botão que envie para uma outra etapa (por exemplo, para exibir um botão de retorno à etapa precedente). Basta, para isso, dar ao botão o atributo name com o valor _retour_etape_n, sendo que n designa o número da etapa visada:

<p class="boutons">
                <input type="submit" class="submit" name="_retour_etape_2" value="<:retour:>" />
        </p>

É possível que essa etapa seja posterior mas, atenção: em todos os casos o visitante só poderá passar a uma etapa n se os dados informados nas etapas precedentes forem válidos e sem erros! No caso contrário, será a primeira página com erros que será exibida.

Nota: _retour_etape_n é compatível com Internet Explorer. Este uso está obsoleto: é necessário usar um input com name aller_a_etape, em que o valor seja o da etapa visada.

A partir do SPIP 4.0: para ir diretamente para a validação final, basta indicar um número de etapa superior ao número total de etapas.

Carregar e declarar as etapas de entrada de dados

A declaração das etapas ou páginas de entrada de dados se faz na função charger() do seu formulário CVT.

A função charger() é idêntica à de um formulário CVT convencional: ela deve retornar uma tabela de todos os campos que serão informados no conjunto do formulário (considerando todas as etapas, como se só houvesse uma única página de entrada de dados).

Adicionalmente, ela deve declarar que o formulário é composto de várias páginas. Isso se faz incluindo o valor ’_etapes’ que designa o número de etapas de entrada de dados.

No nosso exemplo:

function formulaires_inscription_charger_dist() {
   return array (
        'email' => '',  // etapa 1
        'nom' => '',  // etapa 2
        'prenom' => '',
        'semaine' => 0, // etapa 3
        '_etapes' => 3);
}

É este valeur _etapes que irá fazer com que o SPIP se encarregue das diferentes páginas preparadas abaixo.

Nota: a função charger não é chamada apenas pela primeira etapa, mas também para iniciar a exibição de cada etapa.

Verificar os dados informados a cada etapa

A verificação dos dados apresenta uma particularidade. Em vez de ter uma única função verifier() como num formulário CVT convencional, é necessário fornecer uma função verifier()
para cada página de entrada de dados. Estas são numeradas a partir de 1, como para os templates das diferentes páginas.

formulaires_inscription_verifier_1_dist verifica os dados apenas da etapa 1.
formulaires_inscription_verifier_2_dist verifica os dados da etapa 2.
formulaires_inscription_verifier_3_dist verifica os dados da etapa 3.
etc.

No interior dessas funções, a chamada a _request permite aceder aos valores informados a partir da etapa 1 até a etapa corrente.

O número da etapa corrente e o número total de etapas estão igualmente disponíveis via _request(’_etape’) e _request(’_etapes’), se necessário, para mutualizar o código, por exemplo.

Após cada página n, o SPIP chama as funç#oes de verificação das etapas 1 a n para verificar a ausência de regressão na validação (que pode se dar por erro ou tentativa de fraude pelo visitante). Em caso de erro, o visitante é automaticamente direcionado para a primeira página em que os dados não estão corretos.

Em caso de sucesso, o SPIP passa à fase seguinte, exceto se o visitante chegou à última página, quando o SPIP chama a função traiter().

Se há um erro, $erreurs['message_erreur'] não é levada em conta e não se pode especificar um erro global no formulário. É preciso declarar um erro específico no campo que gerou o erro, com $erreurs['champquivamal'] = "Mensagem de erro...".

Normalização

Certas funções de verificação podem fornecer um valor normalizado via o seu terceiro argumento passado em referência.

• Num formulário CVT de uma única etapa, ocorre que se normaliza o valor informado no interior da função ’verifier’ do próprio formulário por um set_request.
• Num formulário multi-etapas, é preciso levar em conta o fato de que o valor normalizado será testado novamente na etapa subsequente: ele deve assim ser também aceite pelo função de verificação. E se houver um retorno a uma etapa anterior, esse valor normalizado deverá também ser exibido corretamente pelo template. Se estas duas condições não forem reunidas, é no validador associado ao formulário que se deve normalizar os valores, e não em ’verifier’.

Exemplo: a função de verificação das datas pode normalizá-las no formato datetime, mas ela não aceita as datas no formato datetime. O valor normalizado só deverá ser usado no validador.

Tratar os dados

A função de tratamento dos dados informados no formulário só é chamada quando todas as páginas tiverem sido preenchidas sem erros.

Ela pode aceder ao conjunto dos dados informados com a função _request como se o formulário tivesse sido preenchido de uma vez só.

A função de tratamento é, de fato, idêntica à de um formulário de página única e é nomeada classicamente (aqui formulaires_inscription_traiter_dist()).

Quando a última etapa de uma entrada de dados válida é tratada, é novamente o template dessa etapa que é usado para exibir a mensagem de retorno e confirmar que os dados foram devidamente considerados.

Sem esquecer...

• O formulário construído desta forma beneficia-se de todas as vantagens dos formulários CVT. Basta incluí-lo numa <div class='ajax'> para que ele seja automaticamente considerado e possibilitar a entrada de dados multi-página em ajax.
• É possível chamar o formulário iniciando-se diretamente na etapa 5, por exemplo. Para isso, basta que se passe o parâmetro "_etape=5" no ambiente (por exemplo no URL, ou por meio de set_request).
  Neste caso, as verificações das quatro páginas precedentes são realizadas e, no caso de validação, a etapa 5 é exibida. Senão, será a primeira etapa que apresentará um erro que será exibida.