Carnet Wiki

Doc Saisies complémentaire

Version 38 — Janvier 2012 — 41.134.xx.xx

-  passage de tableaux en paramètres sous forme de chaine
-  exemples de création de boutons radio et de menus select
-  autres saisies
-  CSS : mettre 2 saisies côte-à-côte
-  Utilisation de tableaux php ou yaml
-  vérifications de la conformité des valeurs saisies
-  Saisies « autonomes »
-  Affichage conditionnel de saisies
-  Génération automatique de CVT
-  Valeur prédéfinie forcée sur un input
-  Saisie d’un point sur une carte (map)
-  Personnaliser les valeurs pour Oui et Non pour les saisies ’cases’ et ’oui_non’
-  Quelques mystéres


Passage de tableaux en paramètres sous forme de chaine

Certains paramètres de diverses saisies peuvent recevoir un tableau en paramètre :
-  datas pour les selection, radio, checkbox, selection_multiple, et même les input en html5. (ce pourrait ou devrait peut être aussi l’être pour secteur mais ça n’est pas le cas).
-  defaut pour les selection_multiple et les checkbox.

Ces paramètres ont donc pour valeur soit un texte sous la forme d’une chaine simple, soit un tableau de plusieurs valeurs. Pour passer un tableau de plusieurs valeurs on peut passer un #ARRAY directement, ou bien alors une chaine servant à représenter un tableau, sous le format d’un raccourci de tableau spip ou sous le format simplifié d’une suite de lignes contenant les couples clé valeur séparés par un pipe (sans les pipe au début et à la fin de la ligne) :

|cle1|valeur1|
|cle2|valeur2|
cle3|valeur3
cle4|valeur4
valeur5
valeur6

Boutons radios et Sélections

La doc n’indique pas comment créer les options des select ou les différents boutons radio d’un ensemble, mais le log ainsi que les fichiers sources donnent des exemples :

Pour les saisies "boutons radio"

[(#SAISIE{radio, afficher_liste,
        label=<:plugin:afficher_liste:>,
        explication=<:plugin:explication_afficher_liste:>,
        datas=#ARRAY{
                cle1,valeur1,
                cle2,valeur2,
                cle3,valeur3}
})]


[(#SAISIE{radio, maintenance}
        {label=Durée de maintenance}
        {defaut=12}
        {datas=#ARRAY{
                12, 12 mois,
                24, 24 mois,
                36, 36 mois}
        }
)]

Pour les saisies "select"

[(#SAISIE{selection, maintenance}
        {label=Durée de maintenance}
        {option_intro=Sélectionnez la durée de maintenance}
        {defaut=12}
        {datas=#ARRAY{
                12, 12 mois,
                24, 24 mois,
                36, 36 mois}
        }
)]

Autres saisies

Il y a moultes saisies dans le plugin, fort utiles dans certains cas, bien que non listées dans la documentation de référence :

  • explication : cette saisie ne saisit rien, mais présente un texte d’explication
  • choix d’un n° d’article original (qui n’est pas une traduction)
  • choix d’une rubrique existante
  • choix de la langue
  • choix d’un article à l’intérieur d’une rubrique
  • choix d’un secteur
  • saisie date_jour_mois_annee
  • ...

Il faut regarder le contenu du sous-répertoire saisies et y faire son marché !

Certains font appel aux « selecteurs » définis dans SPIP Bonux et font un ample usage d’ajax pour faciliter la sélection, par navigation arborescente dans les rubriques par exemple.


CSS : mettre 2 saisies côte-à-côte

Par défaut, des #SAISIES successives sont affichées les unes sous les autres. (propriété clear:both; sur les <li> définie dans habillage.css).

Pour faire apparaître une saisie à droite d’une autre, sur la même ligne, il faut surcharger les propriétés CSS de manière à corriger les valeurs définies dans habillage.css

Pour cela on créera un fichier perso.css dans le dossier squelettes, qui contiendra les nouvelles valeurs.

Par exemple, pour un formulaire « identite » qui comporte une #saisie{input, prenom} immédiatement suivi d’une #saisie{input, nom}, pour que le nom apparaisse à droite du prénom, il suffit de mettre dans perso.css :

.formulaire_identite .editer {
       float: left;
}
.formulaire_identite  .editer_prenom {
       clear: left;
}
.formulaire_identite  .editer_nom {
       clear: right;
       margin-left: 10px;
}

L’affichage des erreurs n’est alors pas très agréable puisqu’en s’intercalant entre le label et la saisie, les erreurs rompent l’alignement horizontal des deux zones de saisie voisines.
Pour remédier, on peut :

  • soit insérer une pseudo saisie "erreur" juste avant, uniquement pour afficher l’erreur commune à ces deux saisies ;
  • soit définir un nouveau type de saisie "prenom_nom" qui intègre les deux ;
  • soit définir un nouveau type de saisie "cote_a_cote" qui intègre deux saisies quelles qu’elles soient. [1]

Utilisation de tableaux php ou yaml

Les #SAISIES peuvent bien évidement être utilisées dans le cadre d’un formulaire CVT.

La documentation du plugin Saisies nous parle de tableaux PHP, mais ne nous dit pas clairement comment les récupérer dans une balise de #FORMULAIRE au sein d’un squelette. La réponse est, encore une fois, dans le fonctionnement de base des formulaires CVT : on définit le tableau dans la fonction "charger", on l’inclut dans le résultat renvoyé par la fonction, et il sera alors disponible dans l’environnement.

Exemple :
Dans un fichier formulaires/x.php :

formulaire_x_charger() {
  $valeurs = array();
  $saisie_age = array(
        'saisie' => 'input',
        'options' => array(
                'nom' => 'age',
                'label' => 'Votre age',
                'size' => 2)
   );
  $valeurs['saisie_age'] = $saisie_age;
  ...
  return $valeurs;

On récupère alors ces infos dans le squelette x.html du formulaire :
SAISIES{#ENV{saisie_age}}

Comme indiqué dans Saisies, on pourra aussi rassembler toutes les saisies dans un tableau $formulaire = array ($saisie_age, ...);, et utiliser une balise #GENERER_SAISIES

Si l’on veut utiliser yaml pour définir une saisie (ce qui nous permettra de simplifier l’écriture et de séparer le code des données et de structure du formulaure), c’est aussi dans la fonction charger() que ca se passe :

function formulaires_y_charger_dist() {
       $valeurs = array();
       include_spip('inc/yaml');
       $saisie_age_yaml = find_in_path('saisie_age.yaml');
       $valeurs['encuesta'] = yaml_decode_file($saisie_age_yaml);
  ...
  return $valeurs;

Pour obtenir le même résultat, le ficher saisie_age.yamldoit contenir :

 saisie: 'input'
 options:
   nom: 'age'
   label: 'Votre age'
   size: 2

Vérifications de la conformité des valeurs

Restant dans le cadre d’une #SAISIES dansun formulaire CVT, la partie ’verifier’ du code associé fera les vérifications adéquates. Elle peut pour cela faire appel aux vérifications prédéfinies par le plugin ’verifier’ (actuellement encore en dev).

Par exemple, pour vérifier un code postal français, ça s’utilise en faisant :

       
$verifier = charger_fonction('verifier','inc');
if ($err=$verifier(_request('cp'), 'entier',  array('min'=>1000, 'max'=>99999))
    $erreurs['cp'] =  $err;

SAISIES propose également une fonction ’saisies_verifier($formulaire)’ qui vérifie et valide en un seul appel la conformité de toutes les saisies, et renvoie le tableau des erreurs dans le cas d’une non validité.

Pour cela,

  • il faut disposer de la constitution du formulaire sous forme d’un tableau PHP. C’est le cas par exemple si la saisie est générée par ce même tableau php au moyen de #GENERER_SAISIES
  • chaque saisie doit avoir été créée avec une option supplémentaire de nom ’verifier’ et dont la valeur est un tableau définissant le type de validation à faire avec le plugin verifier.

Ce tableau contient 2 entrées :
-  ’type’
-  ’options’

Pour chaque saisie, saisies_verifier vérifie si elle a bien été saisie (dans le cas d’une saisie obligatoire), puis appelle la fonction de vérification avec les options indiquées.

Reprenant le même exemple que ci-dessus, on ajoute des options de vérification :

formulaire_x_charger() {
  $valeurs = array();
  $saisie_age = array(
        'saisie' => 'input',
        'options' => array(
                'nom' => 'age',
                'label' => 'Votre age',
                'size' => 2),
        'verifier' => array (type, entier
                options => array (max=>0, min=>100)));
  $valeurs['saisie_age'] = $saisie_age;
  ...
  return $valeurs;

Si l’on passe en yaml, le ficher saisie_age.yaml devient :

 saisie: 'input'
 options:
   nom: 'age'
   label: 'Votre age'
   size: 2
 verifier:
   type: 'entier'
   options:
     min: 0
     max: 100

Saisies autonomes ou non autonomes

Le code html servant à générer chaque saisie est défini par les squelettes contenus dans le répertoire saisies du plugin. Ces squelettes sont inclus par le squelette générique _base.html, qui teste si la saisie à afficher est "autonome".

La plupart des saisies ne sont pas autonomes, et en plus de l’inclusion, les traitements génériques aux saisies sont effectués (en dehors donc du fichier propre à la saisie, qui ne présente que les spécificités de la saisie) :
-  l’affichage d’une erreur associée si il y en a une,
-  le label,
-  les explications,
-  les ’attention’ et les traitements de obligatoire...

Les saisies autonomes sont par contre inclues sans rien d’autre autour. Elles sont dites "autonomes" car c’est leur propre squelette qui gère, ou non, l’affichage des labels, erreurs, explications, attentions et obligatoire. Si le squelette qui définit une saisie autonome n’affiche ni erreur ni label, il n’y aura donc pas d’affichage des erreurs ni des labels.

Les saisies qui sont autonomes sont définies par la fonction saisies_autonomes qui appelle le pipeline du même nom qui permet d’en ajouter de nouvelles. Ce sont par défaut les saisies :
-  fieldset
-  hidden
-  destinataires
-  explication

On peut modifier cette liste en redéfinissant le pipeline éponyme. Ou bien (mauvaise pratique) son unique usage : en créant dans le répertoire squelette/saisies une surcharge de _base.html :
à la place de #SET{saisies_autonomes,#VAL|saisies_autonomes}
mettre #SET{saisies_autonomes,#ARRAY{fieldset, hidden, destinataires, explication, cequonveutenplus}}


Affichage conditionnel de saisies : l’option ’afficher_si’

L’option afficher_si ajoutée à une saisie permets de préciser une condition sur les autres valeurs d’un formulaire indiquant si la saisie doit être affichée ou non.

L’option afficher_si n’a d’effet que sur les balises #GENERER_SAISIES et #VOIR_SAISIES. Les conditions doivent porter sur des champs définis dans le tableau de saisies.

Il est ainsi possible d’insérer - ou plutôt de simuler- plusieurs formulaires avec dans une même page.

Cette option est par exemple utilisée par certaines noisettes aveline dans l’epace privé.

Exemple YAML :

  1. -
  2.   saisie: 'radio'
  3.   options:
  4.     nom: 'choix'
  5.     label: 'Utilisez-vous SPIP ?'
  6.     datas:
  7.        1: non
  8.        2: oui
  9. -
  10.   saisie: 'input'
  11.   options:
  12.     nom: 'raison_non'
  13.     label: 'Si non, pourquoi ?'
  14.     afficher_si: '@choix@ == 1'
  15. -
  16.   saisie: 'input'
  17.   options:
  18.     nom: 'raison_oui'
  19.     label: 'Si oui, pourquoi ?'
  20.     afficher_si: '@choix@ == 2'

Télécharger

Le nom des champs doit être encadré par le caractère @.

Remarque : on notera qu’on a défini ci-dessus le champs choix comme radio, avec des valeurs numpériques, au lieu de oui_non (ou tout autre champs qui donnerait des chaînes de caractères). C’est une astuce pour contourner un bug : ca marche pour un formulaire dans l’espace privé (et c’est ainsi que font les noisettes aveline), mais pas dans l’espace public : avec oui_non il nous faudrait écrire afficher_si: '@choix@ == ""' et afficher_si: '@choix@ == "on"' (ou tout autre "valeur") et il se trouve que les guillemets " sont ensuite transformés en entités HTML &quote; dans une fonction javascript, ce qui provoque une erreur de syntaxe JS.

ATTENTION : si vous utilisez un formulaire CVT, il est important que le nom de la variable contenant le tableau de saisie comment par _ (underscore) afin de désactiver traitements automatiques de SPIP (cf. http://www.spip.net/fr_article4151.html). Sinon, par exemple, les guillements seront transformés en entitées HTLM.

Il est possible d’utiliser des parenthèses dans les conditions ainsi que les opérateurs && et ||.

Par exemple : afficher_si: '@radio1@ == "on" || (@input2@ != "" && @select3@=="valeur3")'

A partir de la version 1.9.3 de saisies, on peut également vérifier la présence d’un plugin pour l’affichage conditionnel d’une saisie avec @plugin:prefixe_du_plugin@.

A partir de la version 1.9.7 de saisies, on peut également tester la valeur d’un champ meta de configuration de plugin pour l’affichage conditionnel d’une saisie avec @config:prefixe_plugin:meta_a_tester@ test à effectuer. Ex : afficher_si: '@config:mon_plugin:afficher_un_truc@ == "on"'


Génération automatique de formulaire CVT

Nouvelle fonctionnnalité dans Saisies : la génération automatique d’un formulaire CVT uniquement à partir de la déclaration d’une liste de saisies. (commit autodocumenté)

Une nouvelle fonction s’ajoute donc à l’API des CVT :
function formulaires_moncvt_saisies()
(ou saisies_dist())

Elle doit retourner un tableau PHP selon le formalisme de l’API de Saisies.

Si cette fonction existe, alors Saisies
-  va automatiquement déclarer les champs trouvés dans charger()
-  va automatiquement regarder les erreurs dans verifier()
-  et va automatiquement générer le HTML du formulaire SI le fichier formulaires/moncvt.html est VIDE (mais existant !)

C’est en effet une contrainte actuelle du système CVT : un formulaire a l’obligation pour exister d’avoir un fichier HTML en dur, même vide, sinon SPIP retourne du vide. Il n’y a donc pas pour le moment de moyen d’éviter la création de ce fichier, même vide.

Evidement, la fonction traiter() est du ressort de chacun !

Exemple

On peut s’en servir notamment pour la création d’un formulaire de configuration. Il suffit de définir la fonction formulaires_truc_saisies_dist($params) dans le ficher PHP de définition du formulaire. Cela permet de déclarer toutes les zones de saisies avec en même temps leurs critères de validité et de vérification (API verifier). Dans ce cas, le fichier html doit exister, mais être vide.

Par exemple, pour le plugin ’produits’ le fichier formulaires/configurer_produits.php :

  1. <?php
  2. if (!defined('_ECRIRE_INC_VERSION')) return;  // Sécurité
  3.  
  4.  
  5. function formulaires_configurer_produits_saisies_dist(){
  6.         include_spip('inc/config');
  7.         return array(
  8.                 array(
  9.                         'saisie' => 'input',
  10.                         'options' => array(
  11.                                 'nom' => 'taxe',
  12.                                 'label' => _T('produits:configurer_taxe_defaut_label'),
  13.                                 'defaut' => lire_config('produits/taxe', ),
  14.                         ),
  15.                         'verifier' => array(
  16.                                 'type' => 'decimal'
  17.                         )
  18.                 )
  19.         );
  20. }
  21. ?>

Télécharger

Autres exemples

-  Sur : ?page=saisies_cvt (avec Z). Et le code dans formulaires/saisies_cvt.php.

-  Autre exemple : http://zone.spip.org/trac/spip-zone/browser/_plugins_/produits/formulaires/editer_produit.php


Forcer une valeur sur une saisie ’input’

On peut définir des valeurs de configuration prioritaires en se servant de defines PHP... Ces valeurs prennent le pas sur la configuration SPIP (via cfg, bonux ou SPIP3). Cela permet de forcer une valeur par rapport à celle du contexte.

Log : http://zone.spip.org/trac/spip-zone/changeset/50402

Exemple d’utilisation dans le plugin "tickets" : http://zone.spip.org/trac/spip-zone/browser/_plugins_/tickets/formulaires/config_tickets_general.html?rev=50403#L16

  1.         #SET{readonly,''}
  2.         [(#VAL{_TICKETS_LISTE_VERSIONS}|defined|?#SET{versions_readonly,readonly},#SET{versions_readonly,''}})]
  3.         [(#GET{versions_readonly}|?{#SET{explications_versions,<:tickets:cfg_explication_readonly:>},#SET{explications_versions,<:tickets:cfg_explication_versions:>}})]
  4.         [(#SAISIE{input, versions,
  5.                 label=<:tickets:cfg_lbl_versions:>,
  6.                 readonly=#GET{versions_readonly},
  7.                 explication=#GET{explications_versions},
  8.                 valeur_forcee=[(#GET{versions_readonly}|?{#EVAL{'_TICKETS_LISTE_VERSIONS'},''})]})]

Télécharger

Cette partie du code teste si _TICKETS_LISTE_VERSIONS est défini,
et dans ce cas :

  • le champ de saisie passe en readonly
  • il reçoit une class readonly pour permettre de le styler
  • il reçoit un message d’explication expliquant que la valeur est déjà définie
  • on affiche la valeur du define (qui est utilisée) et non celle de la configuration.
<blockquote class="spip">

— Mais pourquoi ce nouveau paramètre "valeur_forcee" ne serait que sur les inputs ?
— Parce que je n’ai pas eu le temps et je n’ai pas le code pour tester sur les autres...

</blockquote>

Saisie d’un point sur une carte (googlemap ou autre)

Le plugin GIS définit une nouvelle #SAISIE : une carte cliquable, qui ne constitue pas à proprement parler un champ, mais qui sait pré-remplir d’autres champs qu’on lui passe en paramètre (définis par défaut donc on peut s’en passer) : lat, lon, adresse, code_postal, ville, region, pays.

Pour en bénéficier il faut donc activer le plugin GIS (commit : http://zone.spip.org/trac/spip-zone/changeset/53606)

Exemple d’utilisation ?
non mais


Personnaliser les valeurs Oui et Non pour les saisies oui_non et les cases

http://zone.spip.org/trac/spip-zone/changeset/57042 introduit 2 nouveaux champs transmissibles dans l’env :
-  valeur_oui (par défaut : ’on’)
-  valeur_non (par défauit : ’’ chaine vide)

Ces champs définissent la valeur renvoyée par la saisie en cas de saisie de Oui ou de Non.


attribus mystères

Trouvé dans les yaml du plugin formidable :
-  env : true

Retour à la version courante

Toutes les versions