Carnet Wiki

Saisies : Doc complémentaire

Quelques annotations complémentaires à l’usage des Saisies avec leur Référence des saisies.

Voir aussi
-  les documentations de Vérifier avec sa Références des vérifications
-  la doc de afficher_si
-  la doc pour « Créer ses propres saisies »
-  Saisies : faire son marché et son extrait spécialisé Saisies : faire son marché de sélecteurs pour une liste de sélecteurs introduits par SPIP-Bonux : selecteur générique, selecteurs_article, selecteur_document, selection, selection_par_groupe, etc. Voir aussi le « Sélecteur générique avec autocomplétion » et la saisie Liste



Passage de tableaux en paramètres

Certains paramètres de diverses saisies peuvent recevoir un tableau en paramètre :
-  data= 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 chaêne simple, soit un tableau de plusieurs valeurs. Pour passer un tableau de plusieurs valeurs, on peut passer un #ARRAY directement, ou une #LISTE :

[(#SAISIE{selection, test2, data=[(#ARRAY{valeur1,texte1})]})] 

Tableaux sous forme de chaîne

Dans les anciennes versions de SAISIE, on pouvait passer ce tableau sous la forme d’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 (comme la syntaxe d’un tableau spip mais sans les pipe au début et à la fin de la ligne) :

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

Ce n’est désormais plus possible (il vaut mieux une description PHP des saisies et utiliser #GENERER_SAISIES).

En tout cas si votre code utilise l’ancien format, la fonction saisies_valeur2tableau vous permettra de décoder ce format sous la forme d’un tableau PHP. Il est en effet possible de l’appeler en l’appliquant aux chaines à l’ancien format :

#SAISIE{
  selection, test1,
  data=[(#VAL{'valeur1|texte1'}|saisies_valeur2tableau)]
}

Pour la saisie selection, on pouvait créer des sous-groupes (correspondant à la balise optgroup en HTML) sous forme de chaîne aussi.
Dans la chaîne définissant les options, un sous-groupe commence par une ligne sous la forme *Label. Il finit par un autre sous groupe, ou bien par /*.

*Sousgroupe1
|cle1|valeur1|
|cle2|valeur2|
*Sousgroupe2
cle3|valeur3
cle4|valeur4
/*
cle5|valeur5
cle6|valeur6

Ne surtout pas utiliser de clés implicites, qui posent des problèmes de cohérence à moyen terme.


Saisie selection_multiple : écriture/Lecture de sélections multiples en base de données

(attention : solution testée, mais est-ce la meilleure ? à confirmer par un expert !)

Avec selection_multiple, on ne peut enregistrer directement la valeur du champ dans la base de données. Voici une façon de faire utilisant la sérialisation de l’array représentant la sélection. Dans la base de données, le champ sera de type chaine de caractères, par exemple VARCHAR(62).

Supposons que l’on ait un formulaire editer_entreprise html avec la saisie suivante :

[(#SAISIE{selection_multiple, annuaire, obligatoire=oui,
label=<:entreprise:champ_annuaire_label:>,
explication=<:entreprise:champ_annuaire_explication:>,
data=[(#ARRAY{1,Nogentech,2,FrenchTech,3,CCIHM})]})]

Dans editer_entreprise.php, les fonctions traiter et charger devront comporter la sérialisation et la désérialisation de l’array représentant les sélections dans le champ annuaire :

function formulaires_editer_entreprise_charger_dist($id_entreprise = 'new', $retour = '', $associer_objet = '', $lier_trad = 0, $config_fonc = '', $row = array(), $hidden = '') {
  $valeurs = formulaires_editer_objet_charger('entreprise', $id_entreprise, '', $lier_trad, $retour, $config_fonc, $row, $hidden);

  // désérialiser la valeur du champ annuaire :
  $valeurs['annuaire'] =  unserialize($valeurs['annuaire']);
    
  return $valeurs;
}

function formulaires_editer_entreprise_traiter_dist($id_entreprise = 'new', $retour = '', $associer_objet = '', $lier_trad = 0, $config_fonc = '', $row = array(), $hidden = '') {
	
  // sérialiser la valeur du champ annuaire :
  set_request('annuaire', serialize(_request('annuaire')));
    
  $retours = formulaires_editer_objet_traiter('entreprise', $id_entreprise, '', $lier_trad, $retour, $config_fonc, $row, $hidden);
    
  ...

  return $retours;
}

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

Depuis saisies v5, utiliser la saisie conteneur_inline, qui propose différentes options pour mettre des saisies côte à côte. Voir les références des saisies.



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

	#SET{readonly,''}
	[(#VAL{_TICKETS_LISTE_VERSIONS}|defined|?#SET{versions_readonly,readonly},#SET{versions_readonly,''}})]
	[(#GET{versions_readonly}|?{#SET{explications_versions,<:tickets:cfg_explication_readonly:>},#SET{explications_versions,<:tickets:cfg_explication_versions:>}})]
	[(#SAISIE{input, versions,
		label=<:tickets:cfg_lbl_versions:>,
		readonly=#GET{versions_readonly},
		explication=#GET{explications_versions},
		valeur_forcee=[(#GET{versions_readonly}|?{#EVAL{'_TICKETS_LISTE_VERSIONS'},''})]})]

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.

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


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


Passer son environnement à une saisie

Par défaut, les saisies ne reçoivent pas l’environnement de leur contexte d’appel (sauf si elles ont des enfants).
Pour qu’une saisie reçoive tout son environnement, il faut lui passer un paramètre env=oui. (cf Source concerné)



Générer des saisies automatiquement à partir des champs extra

Exemple : champs extra sur spip_articles

<BOUCLE_champs_extra(DATA){source table,#CONFIG*{champs_extras_spip_articles}|unserialize }>
    [(#SAISIE{[(#VALEUR|table_valeur{saisie}|print_r{1})],[(#VALEUR|table_valeur{options}|table_valeur{nom}|print_r{1})]}
    {label=[(#VALEUR|table_valeur{options}|table_valeur{label}|print_r{1})]}
    {data=[(#VALEUR|table_valeur{options}|table_valeur{data})]}
    )]
</BOUCLE_champs_extra>

CSS selon choix boutons radios

Un formulaire de choix par bouton radio, dont les valeurs de choix sont

4|Très satisfait
3|Plutôt satisfait
2|Plutôt pas satisfait
1|Pas du tout satisfait

donne :

<div class="choix choix_4">
  <input id="champ_radio_2_1" class="radio" type="radio" value="4" name="radio_2">
  <label for="champ_radio_2_1"> Très satisfait</label>
</div>

<div class="choix choix_3">
  <input id="champ_radio_2_2" class="radio" type="radio" value="3" checked="checked" name="radio_2">
  <label for="champ_radio_2_2"> Plutôt satisfait</label>
</div>

<div>...

Pour que le bouton activé prenne une couleur différente selon le choix, on peut utiliser la pseudo-classe :checked sur input (et NON input[checked=checked] ) :

div.choix_4 input[type=radio]:checked + label {    background-color: #0f0; }

div.choix_3 input[type=radio]:checked + label {    background-color: #00f; }

div.choix_2 input[type=radio]:checked + label {    background-color: #f90; }

div.choix_1 input[type=radio]:checked + label { background-color: #f00; }

Ainsi quand je coche un bouton radio, son label passe dans la couleur correspondante, mettant ainsi en valeur l’impression générale des saisies.

(Voir http://www.thecssninja.com/css/custom-inputs-using-css)



Restreindre une date

Il est possible de restreindre les dates affichées et ne pas afficher une date antérieure à la date du jour, depuis la révision 21482 , au moyen de l’option « attributs » avec dedans une valeur ’data-yearRange="lacontrainte"’. Voir la doc de l’option-yearRange pour la syntaxe détaillée.

Cela n’impacte que la saisie par le calendrier dépliant, mais pas la saisie manuelle dans l’input.

Restreindre à 80 ans avant ou après la date actuellement saisie :

    [(#SAISIE{date,date_de_rendezvous,
    	attributs='data-yearRange="c-80:c+0"',
    	label=Date du rendez-vous})]

Restreindre à l’année actuelle et aux 2 suivantes :

    [(#SAISIE{date,date_naissance,
    	attributs='data-yearRange="-0:+2"',
    	label=Date de naissance})]

Par contre, comment utiliser minDate et maxDate ???


Autre type de saisie : liste

Cette saisie est implémentée par un autre plugin : saisie_liste, qu’il faut installer en plus de ’saisie’.

Voir la doc complète et à jour

Cette saisie permet de gérer des listes.
On peut par exemple s’en servir pour demander à l’utilisateur de saisir une liste de personnes ou d’événements.

On commence par passer en paramètre une liste de saisies qui définissent alors chacun des éléments de la liste.
La saisie générée permet ensuite à l’utilisateur d’éditer, de créer ou de supprimer des éléments de cette liste et/ou de modifier leur ordre.

Elle peut fonctionner sans javascript, mais pour les utilisateurs qui l’activent, on peut réordonner les éléments par glisser-déposer via le plugin jqueryui.sortable.

Un fois le plugin installé, on peut voir des exemples d’utilisation de la saisie sur la page /ecrire/?exec=exemples_saisie_liste.

Appel de la saisie

La saisie s’appelle dans les squelettes comme n’importe quelle saisie.

[(#SAISIE{liste, ma-liste,
          label=Objets,
          saisies=#ARRAY{0, #ARRAY{saisie, input,
                                   label, Titre de l'objet,
                                   nom, titre_objet},
                         1, #ARRAY{saisie, textarea,
                                   nom, description,
                                   label, Description}}
})]

On peut aussi utiliser le format de la balise #GENERER_SAISIES

$ma_saisie = array(
    'saisie'  => 'liste',
    'options' => array(
        'nom'     => 'ma-liste',
        'label'   => 'Objets',
    ),
    'saisies' => array(
        array(
            'saisie'  => 'input',
            'options' => array(
                'label' => "Titre de l'objet",
                'nom'   => 'titre_objet',
            ),
        ),
        array(
            'saisie'  => 'textarea',
            'options' => array(
                'label' => "Description",
                'nom'   => 'description',
            ),
        ),
    ),
);

Paramètres :

-  nom => Le nom de la saisie. Obligatoire, le reste est
optionnel
-  label => Le label
-  legende => La légende du fieldset qui contient la liste
-  saisies => La liste de saisies définissant un élément
-  defaut => Le tableau des valeurs par défaut de la saisie
-  interdire_ajout => Interdit d’ajouter des éléments à la liste.
-  ordre_fixe => Interdit de réordonner les éléments de la liste
-  cacher_supprimer => Cache les boutons supprimer sur les éléments
de la liste
-  texte_bouton_ajouter => Le texte du bouton ajouter. « Ajouter » sinon.
-  texte_bouton_supprimer => Le texte du bouton supprimer
-  masquer_nouveaux => Ajoute un javascript qui masque le nouvel élément
de la liste jusqu’à ce qu’on clique sur « Ajouter ».

Traitement des valeurs postées

Pour que la saisie puisse fonctionner correctement, il faut exécuter des traitements au début des fonctions verifier et traiter. Le plus simple est de toujours commencer vos fonctions verifier et traiter par :

if (saisies_liste_verifier('ma-liste'))
    return array();

et vos fonctions traiter par :

if (saisies_liste_traiter('ma-liste')) 
    return array('editable' => 'oui');

ma-liste est le nom de la saisie liste que vous avez créé.

Si le formulaire contient plusieurs saisies liste, il faut passer à ces fonctions un tableau des noms des saisies, par exemple :

if (saisies_liste_verifier(array('liste-1', 'liste-2', 'liste-3')))
    return array();

Les fonctions saisies_liste_verifier et saisies_liste_traiter s’occupent de préparer les valeurs postées de manière à cacher celles qui ne sont utiles que pour le fonctionnement interne de la saisie. Utiliser la fonction _request avant des les avoir appelées est à vos risques et périls…

Elle retournent le nom de la saisie si le formulaire à été posté par un submit propre à une saisie liste, comme le bouton supprimer ou les flèches. Dans ce cas on souhaite en général interrompre les traitements du formulaire comme dans les exemples ci-dessus.

Dans le cas où le formulaire à été posté par un autre submit, saisies_liste_verfier et saisies_liste_traiter retournent FALSE. On peut alors récupérer les valeurs saisies en appelant :
_request('ma-liste');

qui aura la forme suivante (si on reprend l’exemple ci-dessus) :

array(
    0 => array(
        'titre_objet' => "Le premier titre saisi par l'utilisateur",
        'description' => "Une longue description de l'objet…",
    ),
    1 => array(
        'titre_objet' => "Le deuxième titre saisi par l'utilisateur",
        'description' => "Une description du deuxième objet…",
    ),
)

On peut évidement utiliser un tableau de ce genre pour pré-remplir la saisie dans la fonction charger, ou pour passer des valeurs par défaut à la saisie.

Personnalisation du glisser-déposer

Pour personnaliser l’appel au plugin jqueryui.sortable, on peut surcharger le squelette javascript/saisie_liste.js.html (voir le code de ce squelette pour plus d’informations).
On peut aussi créer un fichier javascript/saisie_ma-liste.js.html pour surcharger une saisie particulière.


À documenter
-  http://zone.spip.org/trac/spip-zone/changeset/99576]
-  http://zone.spip.org/trac/spip-zone/changeset/99551

Vague idée de ce que ça fait : En définissant la constante _SAISIES_AFFICHAGE_COMPACT dans le fichier d’option :
-  l’intitulé de la saisie et sa réponse se retrouvent sur la même ligne
-  l’affichage devient plus compact pour les checkboxes. Les réponses vides n’y figurent plus.


Id d’une saisie

Depuis z80006 on peut spécifier l’attribut « id= » des input générés, au moyen d’une option « id » qui prend le pas sur l’option « nom » utilisée par défaut, également utilisé pour l’attribut « name ».

Cela permet ainsi de demander le même « nom » (name) pour plusieurs champs différents et sans casser le « for » des labels, simplement en indiquant un « id » différent pour chaque saisie.

JLuc - Mise à jour :21 novembre 2023 à 13h00min

Toutes les versions