Saisies

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 pour les développeur⋅euses 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.

La balise #SAISIE

Cette balise 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 soit :

La balise a deux arguments obligatoires : le type du champ, et son nom HTML (attribut “name”). Toutes les autres options sont facultatives et servent à configurer le champ ; de ce fait, elles sont de la formes option=valeur.

La forme complète est donc la suivante :
#SAISIE{type, name, option=valeur, option2=valeur2, etc=etc}

Voici quelques exemples d’utilisation, pour comprendre l’approche.

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.

Consultez également :

-  La référence des options de chaque saisie

-  Un complément de doc avancée sur les saisies

Multilinguisme

#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.

Afficher les erreurs

Saisie gère nativement l’affichage des erreurs.

Si la fonction CVT verifier() retourne une erreur du même nom celle ci sera affichée entre le label et le champ.

  • Pour la saisie [(#SAISIE{input, annee, label=<:monplugin:annee:>})]
  • si verifier() retourne : $erreurs['annee'] = "Une erreur"
  • alors <span class="erreur_message">Une erreur</span> sera affichée juste avant l’input.

Enregistrer des tableaux

La norme HTML permet de gérer des réponses de formulaire sous la forme de tableau. Il est recommandé d’utiliser alors le formalisme suivant : tableau/variable.

[(#SAISIE{input, annee/debut, label=<:monplugin:annee:>})]

Permettra de récupérer en PHP

_request('annee');
// array('debut' => 'valeur')

La forme HTML classique [(#SAISIE{input, annee\[debut\], label=<:monplugin:annee:>})] fonctionne aussi.


Attention, pour utiliser tout ce qui suit, vous devez installer aussi le plugin YAML.


Déclarer un formulaire CVT complet en PHP

Saisies augmente l’API CVT de SPIP avec une fonction …_saisies() afin de déclarer l’ensemble des champs d’un formulaire et leur vérification dans une unique syntaxe.

Grace à ce mécanisme, pour les cas les plus courants, les fonctions charger() et verifier() deviennent facultatives. Saisies s’occupera de tout suivant votre déclaration. Seule la fonction traiter() restera 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 pouvez le laisser totalement vide. Saisies s’occupera de générer le bon HTML complet.

Enfin, si 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”.

Dans le PHP, au côté des autres fonctions, vous devez déclarer les saisies :

formulaires_monformulaire_saisies_dist() {
    $saisies = array();
 
    return $saisies;
}

Cette fonction reçoit comme arguments les mêmes arguments que la fonction _charger() du formulaire CVT.

La fonction doit retourner un tableau PHP contenant la liste de toutes vos saisies suivant un formalisme attendu.

Le tableau doit respecter les points suivant :

  • Chaque ligne du tableau d’ensemble est une saisie, elle-même étant décrite dans un tableau. L’ordre des éléments sera l’ordre des saisies.
    $saisies = array(
    	array(), // une saisie
    	array(), // une saisie
    	array(), // une saisie
    );
  • Chaque saisie individuelle est un tableau de la forme :
    array(
    	'saisie' => 'input',
    	'options' => array(
    		'nom' => 'nom',
    		'label' => 'Votre nom',
    		'size' => 50
    	),
    );
  • Les saisies qui acceptent des enfants (comme les fieldsets) les placent dans une clé “saisies” qui contiendra un tableau ayant la même structure que le tableau global :
    $un_fieldset = array(
    	'saisie' => 'fieldset',
    	'options' => array(
    		'nom' => 'mon_groupe',
    		'label' => 'Mon groupe de champ'
    	),
    	'saisies' => array(
    		array(), // une autre saisie
    		array(), // une autre saisie
    		array(), // etc
    	)
    );

Appliquer une vérification

Pour des vérifications simples et uniques, avec le plugin API de Vérification vous pouvez en plus déclarer une vérification à appliquer sur chacune de vos saisies.

Il faut alors ajouter une clé “verifier” selon ce formalisme :

array(
	'saisie' => 'input',
	'options' => array(
		'nom' => 'nom',
		'label' => 'Un nombre entre 100 et 500',
		'obligatoire' => 'oui',
	),
	'verifier' => array(
		'type' => 'entier',
		'options' => array(
			'min' => 100,
			'max' => 500
		),
	),
);

Options globales

Il est possible aussi de déclarer quelques options d’affichage qui sont globales à l’ensemble du formulaire. Elles sont alors placées dans une clé “options” à la racine du tableau.

$saisies = array(
	'options' => array(
		// Changer l'intitulé du bouton final de validation
		'texte_submit' => 'Valider c’est gagné',
 
		// Transformer votre formulaire en multi-étapes
		// Chaque fieldset racine sera reconnu comme étant une étape !
		'etapes_activer' => true,
 
		// Changer l'intitulé du bouton suivant
		'etapes_suivant' => 'Suivantissime',
 
		// Changer l'intitulé du bouton précédent
		'etapes_precedent' => 'Previously on Lost',
	),
	array(), // une saisie
	array(), // une saisie
	array(), // une saisie
);

La balise #GENERER_SAISIES

Dans la plupart des cas vous n’avez pas à l’utiliser vous-même. Il se peut cependant que vous désiriez gérer malgré tout le squelette de votre formulaire.

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>
	#GENERER_SAISIES{#ENV{_saisies}}
</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_monformulaire_saisies_dist(…) si vous la déclarez ;
-  peut aussi être remplie manuellement en ajoutant une clé _saisies dans le tableau de retour de votre fonction _charger.

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 :

  1. le tableau de description des saisies (au même format que pour #GENERER_SAISIES)
  2. un tableau des valeurs saisies

Exemple d’utilisation, dans le squelette d’un formulaire :

[(#EDITABLE|non)
	#VOIR_SAISIES{#ENV{mes_saisies}, #ENV}
]

Problème avec Xdebug

Si vous êtes développeur et que vous utilisez 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 modifier avec une variable. Vous devez donc ajouter cela dans votre configuration PHP/Xdebug :

[xdebug]
xdebug.max_nesting_level = 200 ou 500 ou plus…

Et hop, ça remarche.

updated on 11 May 2020

Discussion

153 discussions

  • 4

    Bonjour,
    j’ai 3 erreurs identiques lorsque je recalcule une page article où il y a un formulaire :
    1         Filtre saisies_nom2classe non défini        plugins/auto/saisies/v3.42.1/saisies/checkbox.html        _checkbox        66

    Dans ce formulaire il y a 2 cases à cocher pour spécifier une valeur

    0bjet de votre demande (obligatoire)
    Demande 1
    Demande 2
    Autre demande

    + 1 case à cocher pour s’inscrire à une newsletter.
    Je ne sais pas laquelle pose problème.
    Elle sont toutes décochées par défaut.

    Avec Saisies pour formulaires 3.42.1 - stable

    Merci

    • évidemment cette version n’a durée que 5min et il a fallu que tu mettes à jour celle là :p

      j’ai refait le tag de cette version 5min plus tard sans la coquille donc il faudrait retélécharger cette version… sinon il faudra que j’augmente la version

    • mouais, on dirait qu’il y a un bug dans le système de cache du debardeur,
      cf le zip joint à cet article.

    • Bon alors je viens de vérifier et apparemment le système ne refait pas le ZIP quand on supprime et refait le tag… :(

      Je modifie la version donc…

    • Merci !
      Je ne fais pas de mise à jour tous les jours, mais là j’ai été trop rapide....

      j’ai fait
      3.42.1 à 3.42.2
      et l’erreur a disparu.

    Reply to this message

  • 1

    Bonjour.

    Dans les commentaires de Formidable, j’avais posté les suggestions suivantes mais, comme je le supputais et comme Maïeul me l’a confirmé, ça relève plutôt de Saisies. Je me permets donc de le reposter ici :


    Bonjour.

    Quelqu’un me fait remarquer que, dans un champ date, le sélecteur d’années va de -60 à +40 ans (en 2019, on a donc le choix d’années entre 1959 et 2059).

    Or une telle gamme n’est pas toujours souhaitée (on pourrait ne vouloir que trois années) ni toujours adéquate (pour une date de naissance, pas besoin des années à venir, mais probablement bien de dates en deçà de 1959).

    Ne pourrait-il pas y avoir des options pour jouer sur l’étendue proposée ? On pourrait ainsi mettre de 2020 à 2022, ou de 1919 à aujourd’hui, ou d’aujourd’hui à 2042, etc.

    Peut-être que ça existe déjà, mais je n’ai alors pas trouvé…
    (Et peut-être que ça relève plus de Saisies que de Formidable…)

    Et, tant qu’à faire, ne pourrait-on pas implémenter dans Formidable le champ HTML5

    1. <input type="date" … >

    , qui a le gros avantage de proposer une ergonomie plus adaptée sur appareils mobiles ?
    (OK, il faudrait garder le système actuel en fallback pour les navigateurs qui ne le supportent pas encore, et je crains que ça coince pour Safari, où le type date est reconnu mais où aucun outil de saisie n’est présent.)

    Plus d’infos sur le type date chez Mozilla…

    Merci d’avance pour vos réponses, et bon week-end !

    1138.

    PS : dans la prévisualisation, le texte

    1. <input type="date">

    affiche réellement le champ . ;-)

    Reply to this message

  • 1

    Bonjour,

    J’ai une colle pour les meilleurs SAISISTES dans les parages.

    J’ai fais un super formulaire CVT en exploitant à 200% SAISIES et c’est top ;) Par contre j’arrive à mes limites en souhaitant mettre de l’ajax et ne pas trop me salir avec du JS inutile.

    Mon formulaire étant AJAXé via la class ’ajax’, j’aimerais pouvoir le recharger pour lui renvoyer une données saisies par l’utilisateur, je m’explique.

    Il s’agit d’un formulaire d’inscription, et j’aimerais généré via SAISIES autant de champs (nom, prenom, emails) que nécessaire, selon le nombre de personnes spécifié par l’internaute via des ’selects’.

    Pour ce faire j’ai commencé par rajouter du javascript dans l’html pour pouvoir déclarer un attribut onChange à mes selects... chose qui n’est pas possible via SAISIES (sauf erreur). Puis un script lancant un ’ajaxReload’ pour renvoyer le nouveau nombre d’inscrits en argument du formulaire, pour généré via une boucle mes champs (prenoms...), enfin bref, ca marche po.

    L’ajaxReload ne fait rien du tout... Je ne suis pas d’ailleurs très sur de la syntaxe. Car AjaxReload prends en argument l’id du bloc ajax pour un inclure, mais pour un formulaire CVT c’est moi évident.

    Donc si quelqu’un à un exemple sous la main, je suis preneur.

    En vous remerciant,
    JuL

    • un an plus tard…

      il ne faut pas faire des ajaxReload car sinon tu vas perdre les saisies déjà effectuées, comme avec un rechargement de page quoi

      quand on veut recharger un formulaire CVT de SPIP avec des nouvelles informations, il faut *valider* le formulaire, mais détecter qu’on veut s’arrêter dans verifier() en générant une fausse erreur invisible qu’on n’affiche pas (c’est ce que fait la prévisu des forums par exemple)

      dans ce cas toutes les saisies sont conservées en mémoire, après à chacun de faire des choses en plus quand tu détectes qu’il y a ci ou ça dans l’environnement en plus (dans le charger() ou les saisies(), c’est après verifier(), donc si ya eu des set_request() ou autre dans verifier() tu peux les retrouver ensuite )

    Reply to this message

  • 4

    Re-Bonjour Rastapopoulos et Maïeul,
    Je viens vers vous pour une question un complexe qui mériterait une documentation à part entière.
    Il s’agit d’utiliser AJAX dans les formulaires CVT exploitant SAISIES (j’ignore si c’est le meilleurs endroit pour poster ce message)

    Voici donc, j’ai un formulaire publique CVT dont tous les champs sont générés via le php puis inlcus dans le HTML via la balise #GENERER_SAISIES.
    Je souhaite que le formulaire se recharge avec de nouveaux arguments au fur et a mesure de la saisie de ce même formulaire donc avant la validation de celui-ci.

    Il s’agit d’un formulaire d’inscription a des activités, avec des inscriptions groupés ou on souhaite recueillir les noms des participants.
    Actuellement, je récupère les noms des participants dans un TEXTAREA, ce qui n’est pas top à manipuler. je souhaiterais avoir autant d’input que de nom à saisir, pour les “serializer” lors du traitement du formualire.
    J’ai cherché et testé puis abandonné...
    Il y aurait un exemple sur lequel je pourrais m’appuyer?

    Je sais utiliser l’ajax proposé par SPIP, mais comme il s’agit d’un formulaire je m’en sors pas.
    Merci d’avance.

    • Reéponse coute : je ne sais pas.

      Réponse longue ; j’ai un besoin similaire

      Réponse très longue : la piste la plus prometteuse serait la saisie “groupe”, mais il faut la travailler pour la rendre accessible et générique.

    • La saisie liste pour telle besoin précis ok, mais pour le besoin plus générique de “faire dépendre l’ajout de certaines saisies à la saisie d’autres trucs précédents” c’est forcément plus compliqué et plus générique.

      Deux possibilités :

      Tente avec les formulaires par étapes. Si à une étape t’as rempli un truc, tu récupère la valeur dans l’étape suivante, et tu mets pas la même saisie ou le même nombre de saisies.

      Plus globalement, même sans le système d’étapes qui prémache certaines choses, il s’agit d’utiliser le “verifier” quoi. Sachant que le charger (et donc la déclaration des champs quand on fait avec saisies) ça arrive APRES verifier et traiter. Donc normalement quand tu es dans la déclaration des champs, tu es capable de savoir la valeur d’un autre précédent, pour peu que t’as arrêté la validation durant “verifier”. Donc 1) quand tu postes un champ “nombre de participants” par ex, faut dire dans verifier() de s’arrêter, et 2) lors de ce deuxième chargement, faut mettre le bon nombre de gens à remplir. Un truc comme ça.

    • Effectivement le système de formulaire par étape pourrait être une solution.

      Originellement, j’aurais souhaité qu’un javascript intervienne comme on peut le faire avec l’AJAX des INCLURE permettant de recharger un bloc a distance avec des arguments.
      https://contrib.spip.net/Exemple-de-bloc-telecommande-en-Ajax
      Sauf que les blocs ajax des formulaires ne semble pas d’avoir d’ID ajax définissable contrairement au bloc INCLURE.

      La solution des étapes me semble une bonne piste effectivement, si la seconde étape prends en compte les données de la précédente, c’est déjà ca. Je pense toutefois que cela porte préjudice à l’ergonomie, en tout cas dans mon cas de figure ou le formulaire n’est pas très compliqué.

    Reply to this message

  • 5

    Bonjour,

    Dans l’exemple
    https://contrib.spip.net/Saisies#La-balise-80c3

    Pouvez-vous préciser comment est défini le nom de la variable #ENV{_saisies} ?
    Est-ce parce que la fonction formulaires_monformulaire_saisies_dist(…) { termine par _saisies_dist ?
    Ou bien est-ce précisément lié au nom de variable array créée dans cette fonction et renvoyée par le return ?

    Merci

    • Le contenu de cette variable est le tableau renvoyé par _saisies_dist() si vous l’utilisez, sinon vous devrez le remplir à la main dans le tableau de retour de votre fonction _charger.

    • J’ai bien compris ce que contient ou doit renvoyer la variable.

      La question est sur le nom de la variable à utiliser : #ENV_saisies
      -  Est-ce qu’il faut mettre toujours “_saisies” sans chercher à comprendre ?
      -  Est-ce qu’il faut mettre “_saisies” parce que la variable locale dans la fonction “formulaires_monformulaire_saisies_dist(” est : $saisies = array( (ou bien aucun lien) ?
      -  Est-ce qu’il faut mettre toujours “_saisies” parce que c’est le fonctionnement du formulaire avec la fonction formulaires_monformulaire_saisies_dist ?
      Merci

    • Il faut mettre _saisies parce que c’est conventionnel ET parce que c’est ce que renvoie la detection automatique des saisies définie par formulaires_monformulaire_saisies_dist

    • Bah ça dépend ce que tu fais, si tu fais tout tout seul tu fais bien ce que tu veux.

      Mais

      • si tu personnalises le squelette en utilisant la déclaration magique des saisies en PHP, bah t’es bien obligé d’utiliser cette variable puisque c’est ça qui est remplis dans charger() par l’automatisme
      • si inversement tu gères le charger toi-même mais que tu utilises le squelette par défaut, t’es bien obligé de renvoyer cette variable là dans charger puisque c’est ça qu’attend le squelette générque

      Par ailleurs le _ devant est absolument obligatoire, même si tu t’amuses à utiliser un autre nom, puisque c’est ce qui permet à CVT de ne PAS traiter la variable avec des choses qui vont la péter.

    • OK c’est clair.
      Peut-être à préciser dans l’article.

      Merci à tous les deux.

    Reply to this message

  • 1

    Bonjour,
    Dans l’exemple
    formulaires_monformulaire_saisies_dist(…) {
    Qu’il y-a-t-il dans les “…” entre les parenthèses ?

    Merci

    • Normalement les mêmes choses que dans les fonctions _charger(), _traiter(), etc. Je précise la doc.

    Reply to this message

  • 1

    Bonjour,

    Manifestement, il y avait un bogue sévère dans la dernière version de Saisies, qui a été supprimée pour revenir à une version antérieure. Problème, mon site avait été mis à jour entre temps et est resté 2 semaines avec tous ses formulaires bloqués (nous avons es messages importants en ce moment d’intérimaires qui ont de gros soucis de paie), jusqu’à ce que je piste les erreurs dans php avec un développeur pour retrouver l’origine du problème, puis par google que nous retrouvions que l’extension Saisies était en cause.
    Suggestion : Il serait sans doute plus efficace pour tous les utilisateurs je pense, que l’ancienne version (celle qui fonctionnait), soit republiée avec une nouvelle numérotation, plutôt que de simplement faire disparaître la dernière. L’extension boguée disparaitrait ainsi naturellement des sites qui entretiennent leurs mises à jour, au lieu de rester coincée en production.
    D’autant que je ne suis pas certains que d’autres sites ne sont pas encore dans le cas que je décris...

    Merci en tout cas pour vos excellentes extensions (c’est le principal :-)

    • Alors, non, on ne vas surtout pas faire ça. À la limite s’il s’était agit d’une version très mineure encore… mais là on va certainement pas passer à un numéro majeur 4.X alors qu’il n’y a strictement rien de nouveau, aucune refonte, rien dans le plugin. Passer de 3.X à 4.X c’est pas un truc commun quoi…

      La version fautive est une version qui n’a jamais existé du tout plus de 30min, et elle est apparue publiquement suite à un changement majeur dernièrement dans le système de génération des paquets SPIP. On a essuyé les plâtres, c’est comme ça… mais cette version vraiment n’existe pas. Et elle n’avait aucun bug, c’est juste que c’est un état (un tag en l’occurrence) du plugin de… 2018, donc forcément il manquait plein de choses qu’attendaient les formulaires récents.

      Il faut donc la supprimer et remettre la vraie dernière version.

    Reply to this message

  • 5

    Où en est le problème de version d’il y a quelques jours ? Est-ce que la version 4.0.0 est valide ? Est-ce qu’on peut l’installer sur un SPIP 3.2.7 ?

    Dans la capture faite à l’instant, on voit 3 fois une version 3.36.2, toutes trois de tailles différentes.

    D’avance merci

    • La référence c’est
      https://plugins.spip.net/saisies.html

      Vivement que ces deux sites soient fusionnées enfin !
      Je supprime les merdouilles.

    • Merci
      Vivement que la page /ecrire/?exec=admin_plugin ne mentionne plus “version obsolète” sur la ligne du plugin Saisies pour formulaires 3.36.2

    • oui Rasta, le script de synchronisation s’est visiblement embrouillé avec le passage au débardeur. Il devient urgent d’accélerer la fusion des deux sites.

      Guillain, la version 4.0.0 ainsi qu’expliqué n’a jamais vraiment existé. C’est une erreur si elle a été annoncée.

      si ils t’annonce encore que c’est obsolète, je craint qu’il ne faille passer par une correction “à la main” dans la table spip_paquets et spip_saisies (après tout de même aovir testé une actualisation manuel des depot distants)

    • Merci
      Je vérifierai ce soir ou demain

    • J’ai du supprimer et ajouter les dépôts pour corriger le problème
      Merci

    Reply to this message

  • 5
    Michel du lac de Créteil

    ATTENTION ! => Le plugin SAISIES n’est pas encore actualisé en AUTO ce qui désactive le plugin FORMIDABLE ! Ce qui est gênant, car nous attendons des inscriptions à un événement par un formulaire créé avec FORMIDABLE.
    ——
    MESSAGE :
    Erreurs survenues
    Impossible d’activer le plugin ../plugins/auto/formidable/v4.1.1
    Nécessite le plugin SAISIES en version ≥ 3.34.0.

    Reply to this message

  • Michel du lac de Créteil

    C’est OK maintenant !
    Merci !
    Michel

    Reply to this message

Ajouter un commentaire

Who are you?
[Log in]

To show your avatar with your message, register it first on gravatar.com (free et painless) and don’t forget to indicate your Email addresse here.

Enter your comment here

This form accepts SPIP shortcuts {{bold}} {italic} -*list [text->url] <quote> <code> and HTML code <q> <del> <ins>. To create paragraphs, just leave empty lines.

Add a document

Follow the comments: RSS 2.0 | Atom