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 des boutons radios avec un choix "oui ou non" :
#SAISIE{oui_non, zanini, label=Tu veux ou tu veux pas ?}
 
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.

  1. [(#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.

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

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

Cette 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].

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 2 October 2019

Discussion

141 discussions

  • 7

    Bonjour,

    Je cherchais à utiliser les codes de langue pour internationaliser mon formulaire en utilisant un fichier YAML pour générer mon formulaire. J’ai essayé avec :

    saisie: 'input'
    options:
        nom: 'voie'
        label: '<:coordonnees:label_voie:>'

    Mais ça m’écrit “<:coordonnees:label_voie:>” dans le formulaire sans traduction.

    Est-ce qu’il existe déjà une méthode prévue dans le plugin Saisie ou dans YAML pour effectuer la traduction des éléments label ? Ou faut-il se le faire à la main en parcourant récursivement le tableau après importation du fichier YAML et en appliquant la fonction _T sur les clés ’label’ du tableau ?

    • Si tu utilises bien #GENERER_SAISIES{tableau}, ya déjà la fonction _T_ou_typo() qui est appliquée partout, donc ce n’est pas normal que ça ne soit pas déjà traduit.

    • Salut Rastapopoulos,

      J’ai identifié ce qui ne marche pas mais je ne trouve pas la solution au problème. Lorsque j’effectue yaml_decode_file, j’obtiens bien des :

      'label'=>'<:coordonnees:label_voie:>', etc.

      Ensuite quand j’effectue un [(#VALEUR**|var_dump)] dans le squelette inclure/generer_saisies.html, j’obtiens des :
      'label'=>"&lt;:coordonnees:label_voie:&gt;"

      Et du coup, la fonction _T_ou_Typo ne fait pas son boulot... Je n’arrive pas à trouver l’endroit ou les chaînes du tableau transmis à generer_saisies est transformé en entités HTML.

    • Ben dans charger(), toutes les valeurs de formulaire (= destinées à des champs HTML) sont échappées. Les autres doivent être envoyées avec un souligné devant : array('_saisies' => $saisies)

    • Youpi, merci, ça marche !

      Avec dans ma fonction charger :

      $valeurs = array('_mes_saisies' => yaml_decode_file($fichier_yaml));
      return $valeurs;

      Et dans mon squelette :

      [(#GENERER_SAISIES{#ENV{_mes_saisies}})]

      Tout fonctionne parfaitement ! Dans la doc, le paragraphe sur la balise #GENERER_SAISIE mérite peut-être d’être amendé pour signaler cette subtilité ? Je crois que peu de personnes sont au courant du truc. Par exemple dans le plugin coordonnees, il est fait appel à la fonction _T dans la fonction charger dans la déclaration du tableau transmis à #GENERER_SAISIE.

    • Au fait, pour les curieux, le coup de l’underscore est expliqué ici : http://programmer.spip.net/Charger-les-valeurs-du-formulaire ... J’aurai pu effectivement trouver la solution en grattant encore un peu, enfin... en creusant beaucoup :)

    • Faut faire attention quand même : ne pas échapper des éléments risque d’entraîner des trous de sécu sérieux (de type XSS au moins). Le problème par rapport aux codes de langue c’est, à mon avis, qu’ils devraient être traités avant que le nettoyage html ne soit effectué.

    • @Gilles, “échapper” c’est une opération qui sert à protéger ce qui vient de l’extérieur, soit de l’environnement, soit d’une soumission de formulaire, etc. Là on parle d’un tableau PHP codé par un⋅e dev, le contexte est donc totalement différent. Et c’est bien pour ça qu’il existe les clés avec soulignement “_truc” dans le charger() de CVT : pour que les devs passent des valeurs internes sans rapport avec l’extérieur, et donc sans passage par l’échappement (qui peut casser bien d’autres choses que juste les chaînes de langue, ça ne suffirait pas de gérer juste ça).

    Reply to this message

  • 3
    Saisie des dates

    Bonjour
    j’utilise la saisie des dates et j’aimerais savoir si on pouvait récupérer la valeur au format date directement Y-m-d plutôt que d/m/Y?
    Cordialement

    • Les saisies ne s’occupent que d’afficher des champs, pas de les traiter. Donc soit tu dois faire ça à la main (dans verifier() ou traiter() du CVT), soit tu peux utiliser le plugin Vérifier qui contient une vérification de date, et dans celle-ci il y a une option de normalisation de la valeur en datetime (avec l’heure par contre, quitte à ce qu’elle soit à 00h00, il faudrait peut-être ajouter une option date sans time).

    • Saisie des dates

      OK, merci
      J’ai bien assimilé que saisies ne s’occupe que d’afficher les champs. C’est tout de même saisies qui renvoie la date cliquée à un certain format. Je pensais que l’on pouvait choisir ce format..
      Je vais donc garder ma solution actuelle de modifier le format dans la partie traitement.
      Merci pour la réponse rapide

    • Théoriquement il y aurait la possibilité de changer le format de la valeur au tout dernier moment en JS, mais ça veut dire que ça obligerait à JS et que ça ne marcherait pas sans, ce qui est mal.

      Là le fait de le faire après, ça permet qu’au niveau interface ça soit au format humain habituel (et dans l’ordre FR par défaut), mais qu’ensuite pour le traitement on le passe en format SQL-friendly.

    Reply to this message

  • 6

    Bonjour,
    j’essaie d’utiliser l’option valeur alternative pour les checkbox mais elle n’est pas fonctionnelle, la valeur est bien enregistrée, mais n’est pas récupérée par le champ dans le formulaire. Le problème a été signalé ici https://www.mail-archive.com/spip-zone@rezo.net/msg35064.html, une solution a t-elle été trouvée? merci d’avance

    • corrigé par http://zone.spip.org/trac/spip-zone/changeset/91257 (par contre ni l’un ni l’autre des messages n’est clair... il fallait comprendre à quel moment c’était censé s’afficher et cela ne le faisait pas)

    • super, merci beaucoup et désolé du manque de clarté.
      J’ai un souci si cette valeur alternative contient une apostrophe, en base et dans saisies/checbox.html ça va bien, mais pas à l’affichage en squelette dans une boucle avec {valeur LIKE %(#GET{valeur_demandee})%} , l’apostrophe bloque... merci encore

    • pas sûr encore une fois de comprendre. on pourrait avoir une boucle plus détaillé? le valeur est censé être le champ? et le #GET{valeur_demandee} contenir une apostrophe ? et que veux tu dire par “bloque”

    • ah oui, re flûte, j’avais #GET{valeur_demandée} parceque j’ai essayé de filtrer avec texte_script, mais sans succès. en fait la boucle c’est

      <BOUCLE_auteurs_type_emploi(AUTEURS){tous}
      {!situation_actuelle_type_emploi LIKE %(#ENV{type_emploi})%}
      {!situation_precedente_type_emploi_1 LIKE %(#ENV{type_emploi})%}
      {doublons} ></BOUCLE_auteurs_type_emploi>

      oui les champs bd c’est situation_actuelle_type_emploi et situation_precedente_type_emploi_1
      #ENV{type_emploi} est un parametre url
      la boucle ramène tous les auteurs quand #ENV{type_emploi} contient une apostrophe ...

    • ce n’est pas un problème lié à saisie, mais un problème plus général aux caractères spéciaux dans #ENV.

      Le pb : #ENV transforme les caractères spéciaux en entités HTML (voir par exemple avec un [(#ENV{toto|var_dump)])

      la solution : demander le champ semi-brut, avec une astérisque : #ENV*{toto}. Attention ne mettre bien qu’une astérisques et pas deux, sinon risque de potentielle faille de sécurité.

    • bingo, la bonne étoile s’appelle Maieul ;) résolu, mille mercis

    Reply to this message

  • tintinux

    Bonjour

    Je voulais télécharger la Version 1.42.6 sur cette page, mais le lien est cassé !

    Si ça peut être réparé, je serais content....

    Merci !

    Reply to this message

  • 3
    laurent

    bonjour,

    il semblerai que les liens de téléchargement soient mort :-\

    merci d’avance à vous!

    • J’ai changé le nom des ZIP ce matin. Il faut attendre que le robot passe sur Contrib pour mettre à jour automatiquement l’article (oui on a un robot pour ça, c’est magique :D).

    • laurent

      super :-)

      merci pour votre travail !

    • masterio

      les archives sont de nouveaux disponibles !merci pour le job ! :)

    Reply to this message

  • 2
    nikon33

    Bonjour

    MERCI de votre aide
    MERCI de votre attention

    Spip 3.0.19
    Processus de don pour une association

    Comme administrateur, au passage en backend de
    http://sourirepourlespoir.org/spipe

    Erreur
    Message
    Numéro 1
    Message Aucun squelette n’est disponible
    Squelette plugins/auto/saisies/v2.2.1/saisies/_base.html
    Boucle /
    Ligne 0

    NB:
    la désactivation réactivation des plugins
    (liés)
    Formidable 2.8.9
    Formulaire de paiement 1.0.4
    Saisies pour formulaires 2.2.1
    Formidable de participation Formidable 1.0.2
    Fusion de formulaire pour Formidable 1.0.1
    Spip Cycle2

    fait bien disparaitre et ré apparaitre l’écran d’erreur
    Aucun squelette n’est disponible

    Pouvez vous me donner une piste pour aller plus loin dans l’analyse sinon la solution

    MERCI

    • Cette erreur parle d’une saisie “montant” qui n’existe pas dans Saisies mais qui est propre au plugin de paiement. Donc je pense que tu devrais poser cette question aux gens qui maintiennent ce plugin. :)

    • nikon33

      pour RastaPopoulos

      Merci de votre réponse

      Juste en ajout au problème évoqué

      Cette alerte
      “Aucun squelette n’est disponible
      Squelette plugins/auto/saisies/v2.2.1/saisies/_base.html”
      n’est PAS
      présente sur la même base de donnée
      chez le même hébergeur
      avec la même version de php
      ... mais un site en Spip 3017

      je vais de ce pas voir du côté des plugins de paiements
      pour moi
      banque&paiements 2.32.1

      mais c’est peut être aussi un problème spip 3.0.17 spip 3.0.19

      MERCI de votre aide

    Reply to this message

  • Suggestion d’amélioration pour la saisie/date.html :
    -  pour pouvoir passer des paramètrages au inc-dateur (standard de spip 3),
    il faudrait en fin de saisie/date.html, rajouter un paramètre ,env
    à la ligne : [(#INCLURE{fond=formulaires/dateur/inc-dateur, env, heure_pas=#ENV{heure_pas,30}})]], ou au moins transmettre une chaine/array d’options : je l’ai fait dans une surcharge perso mais..
    Est-ce un problème au niveau du cache de cette noisette ?

    Merci
    YannX

    PS : exemple d’utilisation : transmettre un “yearRange: 'c-100:c+1', ” (pour pouvoir facilement saisir l’année de naissance) ou un format de date de saisie en fonction du langage !

    Reply to this message

  • 2

    Bonjour,
    J’ai besoin de créer une nouvelle saisie spéciale qui n’a pas à accéder à un champ de la bdd (comme fieldset) mais qui doit par contre récupérer une variable dans l environnement de la page (id_auteur), et.... j’y arrive pas....
    J ai créé mon couple de fichier html et yaml, je me dis que depuis le yaml faut p’etre passer un paramètre au html (comme pour les noisettes du noizetier) ?
    J’utilise cette saisie avec les champs extra depuis l interface extra (je ne sais si ca change quelque chose)...
    amicalement
    triton

    • Mmmh je ne sais plus si c’est possible déjà. Ça me dit quelque chose que quelque part dans le code (ouais c’est hyper vague) il y a un endroit qui teste si on doit passer tout l’environnement ou seulement une partie précise nécessaire. Mais de tête je ne me rappelle plus des conditions.

      Je dis ça, c’est pour l’API PHP où on génère pleins de saisies à partir d’un tableau complet. Quand c’est saisie par saisie avec la balise unitaire, là je sais pas (sûrement juste ajoute “, env” dans les params).

      Pas eu le temps de re-fouiller le code pour l’instant, désolé. :(

    • J ai contourné le pb en dupliquant une saisie de type input que je positionne sur mon champ id_auteur (en lecture seul) et a partir de cet id_auteur je vais chercher mes données dans ma saisie...
      Je vais quand même essayer de lire le code voir si je trouve...
      merci pour la reponse
      amicalement
      triton

    Reply to this message

  • 1

    En voulant ajouter un nouveau champ (après en avoir ajouté d’autres sans pb) je rencontre cette erreur : Fatal error: Maximum execution time of 120 seconds exceeded in /www/plugins/auto/saisies/v1.40.7/inc/saisies.php on line 132

    Pourriez vous m’aider ??

    • Si tu ajoutes des champs, c’est à priori que tu parles du plugin champs extras, qui lui même est utilisateur du plugin saisies. M’est avis que tu devrait plutôt poser la question dans le forum de ce plugin, si ce n’est pas déjà fait. :)

    Reply to this message

  • Bonjour,
    Je débute dans l’utilisation des formulaires pour mettre en place une procédure de dons sur le site http://www.cubacoop.org/
    J’utilise les plugins ;
    Formidable 2,8,0
    Saisies pour formulaires 1.42.1
    YAML1.5.2
    Transaction 0.3.1
    Mes premiers test semblent satisfaisants mais je ne comprend pas pourquoi après validation de la saisie d’une entrée dans le formulaire, le message de retour est affiché 6 fois au lieu d’une.
    Merci de me dire où je peux corriger cet affichage multiple.

    le formulaire peut être testé ici

    Reply to this message

Comment on this article

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