SPIP
Artigo validado
O artigo « Formulários CVT multi-páginas
(Formulários CVT multi-páginas - SPIP) » acabou de ser publicado por
Ricardo Porto.
Formulários CVT multi-páginas
quarta-feira 25 de setembro de 2024 , por Ricardo
Porto
Os formulários multi-etapas (ou multi-páginas) são uma variação dos
formulários CVT que permite encadear múltiplas páginas de entrada de
dados, com uma validação (verificação) intermediária de cada uma das
páginas, e um tratamento final que permite levar em conta todos os valores
informados, de uma única vez.
Sommaire
- Os templates de cada página
- Carregar e declarar as etapas de entrada de dados
- Verificar os dados informados a cada etapa
- Tratar os dados
- Sem esquecer…
É preciso já estar familiarizado com os Formulaires CVT par l’exemple
(SPIP) para criar um
formulário CVT com múltiplas páginas.
Veremos como construir facilmente um formulário de inscrição em três
páginas distintas, deixando ao SPIP a parte complexa que consiste em
memorizar os dados já informados para o tratamento final, e permitir a
navegação entre as páginas.
Os templates de cada página[|Retour au
sommaire](#s-Os-templates-de-cada-pagina)
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})]
[
(#ENV*{message_erreur})]
[(#ENV{editable})
[(#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 →
Seu e-mail
<input type="submit" class="submit"
value="<:pass_ok:>" />
]
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}">
Inscrição #ENV{_etape} / #ENV{_etapes}:informe o seu
e-mail
…
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:>" />
É 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[|Retour au
sommaire](#s-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[|Retour au
sommaire](#s-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 umset_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|Retour au sommaire
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…|Retour au sommaire
- 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 deset_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.
— Enviado por SPIP (https://www.spip.net/)