Les formulaires CVT

Cet article approfondit le fonctionnement décrit pour le CVT , pour mettre en évidence les interactions avec les fichiers squelettes de SPIP.

En HTML un formulaire est une zone de l’écran, encadrée par la balise <form action="url-action"..., comprenant des champs de saisie <input name=".. ; la validation par le bouton de soumission submit transmet la main à l’url-action [1] pour traiter les données saisies dans les champs.

 Le schéma de traitement SPIP

Sur SPIP le formulaire est intégré par une paire de fichiers : l’affichage écran et le programme de traitement sont dans deux fichiers dans le sous-dossier (au pluriel) ./squelettes/formulaires/, de même nom mais avec des extensions différentes : le squelette .html et son traitement .php associé !
Noter que les noms des champs de formulaires SPIP seront sensibles à la casse [2]..
Le fichier de traitement .php doit contenir trois fonctions (toujours préfixées -du pluriel formulaires_nom_form_XXX et suffixées de manière conventionnelle par C.V.T (Charger Vérifier Traiter)) qui vont envoyer des informations au squelette de même nom.

1. Charger : calcule la préparation du squelette en pré-remplissant au besoin les valeurs à proposer aux champs de saisie,
2. Vérifier  : valide les entrées et renvoie au besoin les erreurs dans l’écran de saisie à corriger,
3. Traiter  : opère les enregistrements, en appelant éventuellement des URL d’actions complémentaires, en particulier l’URL de retour.

Cette architecture limite beaucoup les besoins de programmation PHP, permet de se simplifier la vie et de s’assurer d’un traitement sécurisé (sans Javascript) ; noter que des plugins (Saisies) permettent même de se passer du PHP.

Schéma de principe de fonctionnement CVT

Toute l’interface privée de SPIP 3 est désormais conçue et développée avec cette technologie : vous trouverez l’ensemble des formulaires dans ./prive/formulaires, ce qui vous permet :
 d’utiliser directement ces formulaires dans votre interface publique,
 de personnaliser votre interface d’édition (en surchargeant dans ./squelettes/prive/formulaires/...

 Le chargement initial des valeurs

la fonction de chargement du formulaire doit définir les valeurs initiales affichées dans les champs de saisie, en positionnant les valeurs homonymes dans un tableau associatif envoyé au chargement du formulaire... Noter que -même si le HTML ne semble pas sensible à la casse pour les noms de champs- les traitement SPIP y sont sensibles, car ces noms sont utilisés comme ’clés’ des tableaux associatifs php échangés.
Ces valeurs sont à récupérer en relisant les données correspondantes d’une occurrence d’objet éditorial existant (cela suppose que l’appel au formulaire indique l’#ID_objet voulu), ou sinon elles doivent être initialisées pour un nouvel enregistrement ; ne pas confondre avec l’attribut de "placeholder" [3]non encore intégré aux saisies, qui permet d’avoir un libellé explicatif avant la saisie.

 Les vérifications et contrôles d’erreurs

Les valeurs saisies sont rendues disponibles à la fonction de vérification php au travers d’une routine _request() normalisée par SPIP(intégrant divers contrôles de sécurisation, comme l’écran de sécurité), utilisant le nom-clé comme identifiant d’accès au champ ; on peut déclencher un contrôle de contenu, avec (!_request ('champ')) [4], et les diverses vérifications formelles pourront être testées avec l’API de vérification, permettant même de modifier la valeur saisie par set_request()...
En cas d’anomalie, le retour d’information -messages d’erreurs- est conventionnellement associé au même nom-clé au sein d’un tableau associatif renvoyé au formulaire affiché : à charge pour le webmestre écrivant son formulaire HTML d’intégré l’affichage des messages d’erreurs associés aux champs (en utilisant une balise #ENV{erreurs/clé-champ} ).

Si aucune anomalie n’a été positionnée (contrôle (!count(array_filter($erreurs)))), l’exécution est automatiquement transmise par SPIP à la fonction de traitement, qu’il faudra compléter pour assurer les enregistrements, mémorisations et autres traitements suite à une saisie correcte et utile, avant de retourner vers l’utilisateur...

 L’URL code de retour

Il reste un paramètre utile après saisie d’un formulaire : en cas de traitement correct, on souhaitera le plus souvent passer à une autre page du site, de façon à enchaîner la navigation...
C’est la raison d’être d’un champ-clé particulier du retour de traitements, prévu pour recevoir une URL-page de SPIP (ou tout autre URL calculée) ; d’ailleurs, on fournit souvent l’URL de retour comme paramètre de l’appel du formulaire, dans un squelette, par une balise (au singulier) #FORMULAIRE_nom_form_XXX dans le squelette initial, en complément de l’#ID_objet [5].

Enfin, pour compléter les possibilités des formulaires gérés avec SPIP, signalons qu’il est simplissime de rajouter l’appel à un formulaire "au sein même" d’un article, en utilisant un modèle à son nom...

Et le ’two-phases commit’ me demanderez-vous ?
oui, avoir un écran de validation en deux phases (comme pour les messages des forum Spip que vous avez tous pratiqué !).

En gros, il semble y avoir deux approches possibles :
 jouer avec "editable"
(je vous renvoie à https://programmer.spip.net
 que votre CVT-vérifier génère un second formulaire
(c’est l’approche traditionnelle de formulaires/forum.php et forum_previsu ...)

Quant aux "cases à cocher" multiples..... mot-et-mots..
avec passage d’arguments en champs "hidden",
un peu de patience, que j’en sois devenu expert ;-)