Une vue et 3 étapes
Prenons l’exemple d’un formulaire de contact que l’on veut gérer avec la balise #FORMULAIRE_CONTACT.
Affichage
Lorsque SPIP rencontre la balise #FORMULAIRE_CONTACT, il reconnait qu’il s’agit d’une balise du type #FORMULAIRE_xxx.
Il cherche alors le squelette formulaires/contact.html pour afficher le formulaire.
Il n’y a aucun autre pré-requis pour l’affichage du formulaire [1], ce qui permet son intégration visuelle indépendamment des 3 fonctions ci-dessous.
Chargement
Avant l’affichage du squelette, SPIP appelle, si elle existe, la fonction formulaires_contact_charger_dist() pour fournir la liste des champs saisis dans le formulaire, avec des valeurs par défaut éventuelles. Ces champs et valeurs seront fournis au squelette formulaires/contact.html qui en fait donc usage.
Vérification
Lorsque l’internaute remplit le formulaire et clique sur le bouton de validation, SPIP appelle la fonction formulaires_contact_verifier_dist() pour vérifier la validité de la saisie. La fonction renvoie une liste de messages d’erreur correspondants à chaque champs erroné, ou une liste vide en cas d’absence d’erreur.
Traitement
Si la fonction de vérification n’a pas renvoyé d’erreur, alors SPIP appelle automatiquement la fonction de traitement du formulaire formulaires_contact_traiter_dist() qui pourra réaliser toutes les opérations de traitement du formulaire : envoi d’un mail, enregistrement en base de donnée...
La fonction de traitement renvoie une liste d’information, dont un message confirmant que la saisie a bien été prise en compte.
Arguments
Les arguments passés à la balise formulaire, sous la forme
#FORMULAIRE_CONTACT{#ID_AUTEUR} sont automatiquement transmis aux fonctions charger, verifier, traiter, dans le même ordre.
Personnalisations
Le découpage modulaire du formulaire en un squelette d’affichage et trois fonctions Charger, Verifier et Traiter permet de personnaliser indépendamment chacune des étapes :
- le squelette d’un formulaire de SPIP peut être personnalisé dans le dossier
squelettes/ - la fonction
formulaires_contact_charger_dist()peut être personnalisée en définissant la fonctionformulaires_contact_charger() - la fonction
formulaires_contact_verifier_dist()peut être personnalisée en définissant la fonctionformulaires_contact_verifier() - la fonction
formulaires_contact_traiter_dist()peut être personnalisée en définissant la fonctionformulaires_contact_traiter()
Ces fonctions sont a définir dans un fichier contact.php
Ajax
La standardisation dans SPIP du formalisme CVT permet de bénéficier de fonctionnalités supplémentaires sans développement.
En particulier, pour améliorer la fluidité de la navigation et le temps de réponse perçu par l’internaute, une technique consiste à soumettre le formulaire par une requête asynchrone envoyée par le navigateur sans recharger toute la page.
Ce type de requête, souvent désignée par l’acronyme AJAX est en général lourd à développer.
SPIP et CVT simplifient radicalement la mise en place du traitement AJAX de votre formulaire.
Pour cela, il suffit d’encapsuler votre formulaire dans une div avec la classe ajax :
<div class='ajax'>
#FORMULAIRE_CONTACT
</div>
Lorsque l’internaute soumettra le formulaire, celui-ci sera renvoyé à SPIP par une requete asynchrone, et SPIP ne renverra que le résultat du formulaire après vérification et traitement éventuel.
L’internaute aura une réponse plus rapide, car il n’aura pas rechargé toute la page, mais seulement la zone correspondant au formulaire !
noscroll : L’emploi de la classe « noscroll » en plus permet de demander que l’appel ajax se fasse sans que le navigateur ne scrolle au début de la page. Cet ajout peut se faire
- en plus de « ajax » dans la balise englobante
- ou dans le bouton de submit
Compatibilité avec les anciens formulaires dynamiques de SPIP
Les anciens formulaires dynamiques de Spip reposant sur un squelette et une serie de fonction balise_formulaires_xxx, balise_formulaires_xxx_stat, et balise_formulaires_xxx_dyn restent fonctionnels, mais il est conseillé de les migrer progressivement vers le formalisme CVT.
Techniquement CVT est une surcouche implémentée par des fonctions génériques balise_formulaires_xxx, balise_formulaires_xxx_stat, et balise_formulaires_xxx_dyn.
A ce titre, il est possible, par exemple pour la collecte automatique d’arguments, de définir sa propre fonction balise_formulaires_contact_stat.