SPIP

[ar] [ast] [bg] [br] [ca] [co] [cpf] [cs] [da] [de] [en] [eo] [es] [eu] [fa] [fon] [fr] [gl] [id] [it] [ja] [lb] [nl] [oc] [pl] [pt] [ro] [ru] [sk] [sv] [tr] [vi] [zh] Espace de traduction

Télécharger

Formulaires CVT en plusieurs pages

Mai 2012 — mis à jour le : Novembre 2011

Les formulaires multi-étapes (ou multi-pages) sont une variation des formulaires CVT qui permet d’enchainer plusieurs pages de saisies, avec une validation (vérification) intermédiaire de chacune de ces pages et un traitement final qui permet de prendre en compte toutes les valeurs saisies en une seule fois.


Il est nécessaire d’être déjà familier avec les formulaires CVT pour créer un formulaire CVT en plusieurs pages.

Nous allons voir comment construire facilement un formulaire d’inscription en 3 pages distinctes, SPIP prenant en charge la partie compliquée qui consiste à mémoriser les données déja saisies pour le traitement final, et à permettre la navigation entre les pages.

Les squelettes de chaque page

Chaque page du formulaire se présente comme un formulaire complet (avec un bouton de validation qui sert à passer à l’étape suivante).

Chacune des étape est numérotée, à partir de 1, et décrite par un fichier squelette indépendant qui implémente un formulaire autonome pour les saisies de cette page.

Pour l’étape 1, le squelette est formulaires/inscription.html.
Pour l’étape 2, le squelette est formulaires/inscription_2.html.
Pour l’étape 3, le squelette est formulaires/inscription_3.html.

Voici par exemple à quoi ressemble la première page de notre formulaire :

  1. <div class="formulaire_spip">
  2.         [<p class="reponse_formulaire reponse_formulaire_ok">(#ENV*{message_ok})</p>]
  3.         [<p class="reponse_formulaire reponse_formulaire_erreur">(#ENV*{message_erreur})</p>]
  4.         [(#ENV{editable})
  5.         <form method='post' action='#ENV{action}'><div>
  6.                 [(#REM) les hidden qui declencheront le service du formulaire parametre : url d'action ]
  7.                 #ACTION_FORMULAIRE{#ENV{action},#FORM}
  8.  
  9.                 <!-- Ici les saisies de l'étape 1, directement en HTML.
  10.                        Elles pourraient aussi être générées par le plugin SAISIES  -->
  11.                  <label>Votre email</label>
  12.                  <input type='text' name='email' value='#ENV{email}' />              
  13.                  <input type="submit" class="submit" value="<:pass_ok:>" />
  14.          </div></form>
  15.         ]
  16. </div>

À l’intérieur de chaque squelette, #ENV{_etape} renvoie le n° de l’étape, et #ENV{_etapes} renvoie le nombre total d’étapes de saisie. Cela permet par exemple d’afficher un état de l’avancement de la saisie par rapport au nombre total de pages de saisies :

  1. <div class="formulaire_spip formulaire_inscription formulaire_#FORM  formulaire_#FORM_#ENV{_etape}">
  2.         <h3>Inscription  #ENV{_etape} / #ENV{_etapes} : indiquez votre email</h3>
  3. ...

A chaque page, #ENV contient toutes les valeurs déjà saisies lors des étapes précédentes. Ainsi, si vous voulez proposer une valeur par défaut qui dépend d’une saisie précédente, il suffit d’utiliser celle-ci pour pré-remplir votre saisie.

Sur chaque page, il est aussi possible de proposer un bouton qui renvoie vers une autre étape (par exemple pour faire un bouton de retour à l’étape précédente). Il suffit pour cela de donner au bouton l’attribut name avec la valeur _retour_etape_n, n désignant le numéro de l’étape visée :

Il est possible que cette étape soit une étape en avant, mais attention : dans tous les cas l’utilisateur ne pourra passer à une étape n que si la saisie des étapes précédentes est correcte et sans erreur ! Dans le cas contraire, c’est la première page avec des erreurs qui lui sera présentée.

Charger et déclarer les étapes de saisie

La déclaration des étapes ou pages de saisies se fait dans la fonction charger() de votre formulaire CVT.

La fonction charger() est identique à celle d’un formulaire CVT conventionnel : elle doit retourner un tableau de tous les champs qui seront saisis dans l’ensemble du formulaire (donc toutes étapes confondues, comme si il n’y avait qu’une seule page de saisie).

Mais en plus, elle doit déclarer que le formulaire comporte plusieurs pages. Cela se fait en renvoyant en plus une valeur ’_etapes’ qui désigne le nombre d’étapes de saisies.

Dans notre exemple :

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

C’est cette valeur _etapes qui va déclencher la prise en charge par SPIP des différentes pages préparées ci-dessus.

Vérifier la saisie à chaque étape

La vérification de la saisie présente ici une particularité. Au lieu d’avoir une seule fonction verifier() comme dans un formulaire CVT conventionnel, il va falloir fournir ici une fonction verifier() par page de saisie. Celles-ci sont numérotées à partir de 1 comme pour les squelettes des différentes pages.

formulaires_inscription_verifier_1_dist vérifie les saisies de l’étape 1 uniquement.
formulaires_inscription_verifier_2_dist vérifie les saisies de l’étape 2.
formulaires_inscription_verifier_3_dist vérifie les saisies de l’étape 3.
etc.

A l’intérieur de ces fonctions, l’appel à _request permet d’accéder aux valeurs saisies depuis l’étape 1 jusqu’à l’étape courante.

Le numéro d’étape courante et le nombre totale d’étapes sont également accessible par request(’_etape’) et par request(’_etapes’), si nécessaire, pour mutualiser du code par exemple.

Après chaque page n, SPIP appelle les fonctions de vérification des étapes 1 à n pour vérifier l’absence de régression dans la validation (qui pourrait être due à une erreur ou à une tentative de fraude par l’utilisateur). En cas d’erreur, l’utilisateur est automatiquement renvoyé sur la première page dont la saisie n’est pas correcte.

En cas de succès, SPIP passe à l’étape suivante, sauf si l’utilisateur est arrivé à la dernière page, auquel cas SPIP appelle la fonction traiter().

Traiter la saisie

La fonction de traitement des saisies du formulaire n’est appelée que lorsque toutes les pages ont été saisies sans erreur.

Elle peut accéder à l’ensemble des saisies avec la fonction _request comme si le formulaire avait été saisi en une seule fois.

La fonction de traitement est donc tout à fait identique à celle d’un formulaire en une page et se nomme classiquement (ici formulaires_inscription_traiter_dist()).

Sans oublier...

-  Ce formulaire ainsi construit bénéficie de tous les avantages des formulaires CVT. Il suffit donc de l’encapsuler dans une <div class='ajax'> pour qu’il soit automatiqent pris en charge et permette la saisie multi-page en ajax.

-  Il est possible d’appeler le formulaire en commençant directement à l’étape 5, par exemple. Pour cela, il suffit de passer le paramètre "_etape=5" dans l’environnement (dans l’url par exemple).
Dans ce cas, les vérifications des 4 pages précédentes sont effectuées et en cas de validation, l’étape 5 est affichée. Sinon c’est la première étape qui présente une erreur qui est affichée.

Notes

[1Cette fonctionnalité est également accessible pour SPIP 2 mais nécessite l’activation du plugin cvt-multi-etapes


Voir le squelette de cette page Site réalisé avec SPIP | Espace de traduction | Espace privé