Introduction
Créer un formulaire est une tâche toujours un peu répétitive : les champs ont souvent les mêmes propriétés, le même accompagnement (message d’erreur, explication ...) et la même structure HTML. Ce plugin est un outil d’aide au développement, ayant pour but de faciliter et d’accélérer l’écriture des formulaires.
Pour cela, Saisies propose plusieurs mécanismes (balises, API PHP) pour générer et manipuler plus facilement les champs des formulaires. De cette manière, les squelettes de formulaires sont :
- plus lisibles : il n’y a que le strict nécessaire dedans, pas de répétition ;
- intégrés au fonctionnement CVT de SPIP, notamment pour la gestion des erreurs sur les champs ;
- automatiquement compatibles avec les recommandations HTML/CSS de SPIP.
Dans la présente documentation, nous présentons la manière de construire un formulaire avec Saisies de la méthode la plus robuste à la méthode la moins robuste.
Les méthodes moins robustes sont présentées pour deux raisons :
- ce sont les méthodes les plus anciennes. On trouve encore beaucoup de code les utilisant ;
- il est parfois nécessaire de passer par là, pour des réglages fins.
Pour utiliser l’API complète PHP, vous devez installer ou nécessiter le plugin YAML dans votre plugin. Ce n’est pas le cas quand on utilise juste la simple balise, ce pourquoi c’est à vous de le nécessiter.
Dans la présente documentation, lorsqu’un code est entre chevrons (comme <ceci>
), vous devez le remplacer par une valeur correspondant à votre projet.
Cette documentation est valable à partir de la version 4.11.0 ou du plugin.
Méthode 1 : déclarer un formulaire CVT complet en PHP
Principe
Saisies augmente l’API CVT de SPIP avec une fonction formulaires_<nomduformulaire>_saisies()
afin de déclarer l’ensemble des champs d’un formulaire et leur vérification dans une unique syntaxe. Cette fonction permet également de déclarer différents réglages de formulaire, tel que :
- le label du bouton de validation final;
- l’utilisation en multiétapes.
Grâce à ce mécanisme, pour les cas les plus courants, les fonctions formulaires_<nomduformulaire>_charger()
et formulaires_<nomduformulaire>_verifier()
deviennent facultatives. Saisies s’occupera de tout suivant votre déclaration. Seule la fonction formulaires_<nomduformulaire>_traiter()
reste toujours de votre ressort.
De même, par défaut, vous n’avez plus à vous occuper du squelette. Il doit toujours être présent, avec le même nom que votre fichier PHP dans le dossier formulaires/
, mais vous devez le laisser totalement vide. Saisies s’occupera de générer le HTML complet, en suivant les recommandations de structuration de SPIP.
Enfin, dans le cas particulier où vous créez un formulaire de configuration, vous n’aurez même pas à déclarer les valeurs par défaut ni le traitement. Voir l’article “Formulaire de configuration avec le plugin Saisies”.
Mise en œuvre
Il vous faut donc créer un fichier formulaires/<nomduformulaire>.html
vide, ainsi qu’un fichier formulaires/<nomduformulaire>.php
contenant deux fonctions :
- formulaires_<nomduformulaire>_traiter()
, qui indique ce que votre formulaire doit effectuer comme traitement ; cela n’est pas du ressort du plugin Saisies;
- formulaires_<nomduformulaire>_saisies()
, pour déclarer les saisies proprement dites.
Cette dernière fonction reçoit comme arguments les mêmes arguments que la fonction _charger()
du formulaire CVT, et elle doit retourner un tableau PHP contenant la liste de toutes vos saisies suivant un formalisme attendu.
formulaires_<nomduformulaire>_saisies(…) {
$saisies = […];
return $saisies;
}
Déclaration de l’ensemble des saisies
Chaque ligne globale du tableau renvoyé décrit une saisie.
L’ordre des éléments sera l’ordre des saisies.
$saisies = [
[…], // une saisie
[…], // une saisie
[…], // une saisie
];
Déclaration d’une saisie individuelle
Chaque saisie est elle-même décrite dans un tableau, qui prend par exemple la forme suivante :
[
'saisie' => 'input',
'options' => [
'nom' => 'nom',
'label' => 'Votre nom',
'defaut' => 'Valeur par défaut'
],
];
On consultera “Référence des saisies” pour avoir l’ensemble des saisies et des options disponibles en standard.
D’autres plugins ajoutent leurs propres saisies, et vous pouvez aussi créer vos propres saisies.
Déclaration des saisies enfants
Les saisies qui acceptent des enfants (comme les fieldsets) les placent dans une clé saisies
dont la valeur est un tableau ayant la même structure que le tableau global :
$un_fieldset = [
'saisie' => 'fieldset',
'options' => [
'nom' => 'mon_groupe',
'label' => 'Mon groupe de champ'
],
'saisies' => [
[…], // une autre saisie
[…], // une autre saisie
[…], // etc
]
];
Appliquer des vérifications
Pour des vérifications simples et uniques vous pouvez en déclarer des vérifications à appliquer sur chacune de vos saisies, avec le plugin API de Vérification (qui n’est pas activé automatiquement avec le plugin saisies
).
Il faut alors ajouter une clé verifier
selon ce formalisme :
[
'saisie' => 'input',
'options' => [
'nom' => 'slug',
'label' => 'slug',
'obligatoire' => 'oui',
],
'verifier' => [
[
'type' => 'taille',
'options' => ['min' => 10]
],
[
'type' => 'slug',
],
],
];
Permet de vérifier que nous avons affaire à un slug d’une taille minimum de 10 caractères.
Consulter “Références des vérifications” pour la liste des types de vérification livrés avec le plugin et de leurs options.
[
'saisie' => 'input',
'options' => [
'nom' => 'nom',
'label' => 'nom',
'obligatoire' => 'oui',
],
'verifier' => [
'type' => 'entier',
'options' => [
'min' => 100,
'max' => 500
],
],
];
Support du multilinguisme
Saisies supporte le multilinguisme. Ainsi, dans l’exemple ci-dessous, la chaine de langue <:cle:valeur:>
sera automatiquement interprétée.
[
'saisie' => 'input',
'options' => [
'nom' => 'nom',
'label' => '<:cle:valeur:>',
'size' => 50
],
];
Options globales
Il est possible de déclarer des options d’affichage globales à l’ensemble du formulaire. Elles sont alors placées dans une clé options
à la racine du tableau des saisies.
$saisies = [
'options' => [
// Changer l'intitulé du bouton final de validation
'texte_submit' => 'Valider c’est gagné',
…
'<option>' => '<valeur>' //Une autre option
],
[…], // une saisie
[…], // une saisie
[…], // une saisie
);
Option | Usage | Valeur possible | Valeur par défaut |
---|---|---|---|
Options pour le bouton de validation | |||
texte_submit |
Texte du bouton de validation | Texte, passe par _T_ou_typo() |
<:bouton_enregistrer:> |
afficher_si_submit |
Condition pour afficher le bouton de validation | Voir “Affichage conditionnel des saisies : syntaxe des tests” | null |
Options pour la gestion des étapes multiples | |||
etapes_activer |
Activer la gestion multi-étapes, chaque fieldset de premier niveau devient une étape |
True|False |
False |
etapes_presentation |
Mode de présentation des étapes en haut du formulaire | 'defaut'|'courante' , il est possible de créer son propre mode en créant un squelette formulaires/inc-saisies-cvt-etapes-<presentation>.html |
defaut |
etapes_suivant |
Texte du bouton pour aller à l’étape suivante | Texte, passe par _T_ou_typo() |
<:bouton_suivant:> |
etapes_precedent |
Texte du bouton pour revenir à l’étape précédente | Texte, passe par _T_ou_typo() |
<:precedent|ucfirst:> |
etapes_precedent_suivant_titrer |
Permet d’ajouter le titre des étapes dans les boutons “précédent” et “suivant” | True|False |
False |
etapes_ignorer_recapitulatif |
Permet de ne pas insérer de récapitulatif avant la validation finale | True|False |
False |
Options techniques | |||
verifier_valeurs_acceptables |
Permet de s’assurer que les valeurs reçues figurent bien parmi les valeurs proposées lors de la saisie du formulaire | True|False |
False |
afficher_si_avec_post |
Permet que les saisies masquées par affichage conditionnel soient tout de même postées | True|False |
False |
inserer_debut |
Contenu arbitraire à insérer au début du formulaire, par exemple pour appeler un script Javascript | Chaîne de caractères | null |
inserer_fin |
Contenu arbitraire à insérer à la fin du formulaire, par exemple pour appeler un script Javascript | Chaîne de caractère | null |
Si un texte passe par _T_ou_typo()
, cela peut être :
- un texte directement écrit dans la langue du site;
- un appel à une chaîne de langue sous la forme
<:fichier_de_langue:chaine:>
; - un texte utilisant la balise
<multi>
pour gérer l’internationalisation.
Pipeline
Lors du chargement des saisies déclarées via une fonction formulaires_<nom_du_formulaire>_saisies()
, les saisies sont passés à un pipeline formulaire_saisies
. Le tableau $flux
passé à ce pipeline à la structure suivante :
- $flux['args']['form']
: le nom du formulaire;
- $flux['args']['args']
: les différents arguments passés;
- $flux['data']
: les saisies.
Il est donc possible à un plugin de modifier dynamiquement les saisies d’un formulaire en utilisant les différentes fonctions de l’API de saisies.
Méthode 1a : déclarer un formulaire CVT en PHP, mais effectuer soi-même des vérifications
Parfois il est nécessaire d’avoir des vérifications supplémentaires sur les saisies. Pour ce faire, vous devez déclarer votre propre fonction formulaires_<nomduformulaire>_verifier()
.
Dans ce cas, vous ne perdrez pas le bénéfice d’une déclaration des vérifications de base dans votre tableau de saisies : celles-ci sont alors automatiquement effectuées après vos propres vérifications.
Toutefois, il est parfois nécessaire de faire en sorte que les vérifications “par déclaration” se fassent avant vos propres vérifications. Dans ce cas, la méthode la plus propre est de déclarer ses vérifications non pas sous forme d’une fonction formulaires_<nomduformulaire>_verifier()
, mais par la création d’une fonction formulaires_<nomduformulaire>_verifier_post_saisie()
, ou sa variante verifier_etapes_post_saisies()
dans le cadre du multiétape.
À noter qu’il existe deux pipelines pour ajouter des vérifications à un formulaire existant : formulaire_verifier_post_saisies
et formulaire_verifier_etapes_post_saisies
.
Méthode 1b avec #GENERER_SAISIES
: contrôler la structure globale du formulaire, mais utiliser le formalisme de saisies
Dans quelques cas rares, la structure globale du formulaire livrée avec Saisies ne convient pas. Pour autant, vous souhaitez.
- profiter du formalisme de déclaration des saisies
- profiter de la vérification automatique de ces saisies (sauf si vous utilisez la méthode 1a).
Dans ce cas :
- vous mettez dans votre fichier
formulaires/<nomduformulaire>.html
la structure globale du formulaire correspondant à votre besoin; - là où vous souhaitez insérer vos saisies, vous utilisez la balise
#GENERER_SAISIES
.
Cette balise permet de générer toutes les saisies d’un formulaire, en une seule fois. Pour cela on lui passe en paramètre le tableau de description.
Exemple d’utilisation :
<div class="formulaire_spip formulaire_#ENV{form}"[(#ENV{_etape}|oui)formulaire_multietapes]">
<form .... [ data-resume_etapes_futures="(#ENV{_resume_etapes_futures}|json_encode|attribut_html)"]>
....
<div >
#GENERER_SAISIES{#ENV{_saisies}}
</div>
....
</form>
</div>
On notera l’emploi d’un _
en préfixe de la variable d’environnement. Cela permet que les guillemets présents dans les options ne soient pas transformés en entités HTML [1].
#ENV{_saisies}
est rempli automatiquement avec la valeur de retour de la fonction formulaires_<nomduformulaire>_saisies()
[2].
On n’oubliera pas les attributs suivants :
- les différentes classes sur le <div>
englobant
- l’attribut [ data-resume_etapes_futures="(#ENV{_resume_etapes_futures}|json_encode|attribut_html)"]
sur le <form>
, qui permet de gérer correctement les affichages conditionnels des étapes dans un formulaire multi-étape.
Par ailleurs, on utilisera
[(#ENV{_etape}|oui)
<INCLURE{fond=formulaires/inc-saisies-cvt-etapes-#ENV{_saisies/options/etapes_presentation,defaut}, etapes=#ENV{_saisies_par_etapes}, env} />
]
</div>
pour insérer le chemin d'étapes, et
<cadre class="spip">
<INCLURE{fond=formulaires/inc-saisies-cvt-boutons,env} />
pour les boutons de validation.
Méthode 2 : la balise #SAISIE
Parfois on veut pouvoir contrôler encore plus finement la présentation des saisies. Pour ce faire, on peut insérer dans formulaires/<nomduformulaire>.html
des appels à la balise #SAISIE
.
Cette méthode n’est pas toujours adaptée, car elle présente des limitations :
- elle ne permet pas de profiter des vérifications automatiques;
- elle ne permet pas de profiter du mécanisme d’affichage conditionnel.
#SAISIE
permet de générer une seule saisie en lui donnant directement les paramètres désirés. Chaque saisie va générer une ligne dans un formulaire, c’est-à-dire un élément <div>
.
La balise #SAISIE
a deux arguments obligatoires : le type de saisie, et son nom HTML (attribut “name”). Toutes les autres options sont facultatives et servent à configurer le champ ; de ce fait, elles sont de la forme option=valeur
.
La forme complète est donc la suivante :
#SAISIE{type, name, option=valeur, option2=valeur2, etc=etc}
Voici quelques exemples d’utilisation.
Génère un simple champ texte, indiqué comme étant obligatoire :
#SAISIE{input, email, label=Votre courriel, obligatoire=oui}
Génère un choix multiple parmi les utilisateurs du SPIP :
#SAISIE{auteurs, destinataires,
label=Destinataires du message,
explication=Choisissez une ou plusieurs personnes à qui sera envoyé le message.,
multiple=oui}
Comme vous le voyez, des champs qui peuvent être complexes, et fastidieux à écrire de manière complète, s’écrivent ici en quelques lignes.
#SAISIE
supporte le multilinguisme. Dans ce cas, attention de bien utiliser la syntaxe complète avec les crochets :
-
#SAISIE{input, annee, label=<:monplugin:annee:>,obligatoire=oui}
ne fonctionne pas ; -
[(#SAISIE{input, annee, label=<:monplugin:annee:>,obligatoire=oui})]
fonctionne.
Appendice 1 : chargement des CSS et scripts Javascript sur le site public
Si votre formulaire est destiné à être public, le plugin se charge d’ajouter automatiquement les appels aux fichiers CSS et scripts Javascript associés aux saisies utilisées sur le site public, lorsque le formulaire est effectivement utilisé.forme
Toutefois, si vous avez beaucoup de formulaires utilisant Saisies sur le site public, il peut être judicieux de charger systématiquement les fichiers sur toutes les pages, afin de profiter de la compréhension et du cache navigateur. Dans la configuration du plugin (“Squelettes”->“Configuration du plugin Saisies”), une option permet d’activer cela.
Appendice 2 : enregistrer des tableaux
La norme HTML permet de gérer des réponses de formulaire sous la forme de tableau.
Dans la déclaration de la saisie, on peut utiliser la syntaxe HTML classique avec crochets :
[
'saisie' => 'input',
'options' => [
'nom' => 'annee[debut]',
'label' => 'Votre nom',
'size' => 50
],
];
Mais il est recommandé d’utiliser le formalisme SPIP suivant : <tableau>/<clé>
.
[
'saisie' => 'input',
'options' => [
'nom' => 'annee/debut',
'label' => 'Label',
'size' => 50
],
];
Le code suivant permettra de récupérer la valeur en PHP :
$annee = _request('annee');
$debut = $annee['debut'];
Appendice 3 : la balise #VOIR_SAISIES
Cette balise permet d’afficher toutes les valeurs saisies après validation d’un formulaire. On lui passe en paramètre deux arguments :
- le tableau de description des saisies (au même format que pour #GENERER_SAISIES)
- un tableau des valeurs saisies
Exemple d’utilisation, dans le squelette d’un formulaire :
[(#EDITABLE|non)
#VOIR_SAISIES{#ENV{mes_saisies}, #ENV}
]
Appendice 4 : problème avec Xdebug
Si vous développez en utilisant le logiciel Xdebug, il existe un problème connu : par défaut celui-ci affiche une erreur à partir d’un certain niveau d’imbrication de fonctions PHP (“nesting level” dirait Shakespeare).
Le niveau d’imbrication autorisé par défaut est relativement bas, mais on peut le paramétrer. Vous devez donc ajouter cela dans votre configuration PHP/Xdebug :
[xdebug]
xdebug.max_nesting_level = 200 ou 500 ou plus…
Et hop, ça remarche.
No discussion
Add a comment
Avant de faire part d’un problème sur un plugin X, merci de lire ce qui suit :
Merci d’avance pour les personnes qui vous aideront !
Par ailleurs, n’oubliez pas que les contributeurs et contributrices ont une vie en dehors de SPIP.
Follow the comments: |