source: spip-zone/_plugins_/saisie_liste/trunk/README.md

Last change on this file was 109984, checked in by bystrano@…, 19 months ago

copie et maj du lien de la doc

File size: 5.3 KB
Line 
1
2La saisie liste
3===============
4
5Cette saisie permet de gérer des listes. On peut par exemple s'en
6servir pour demander à l'utilisateur de saisir une liste de personnes
7ou d'événements.
8
9On commence par passer en paramètre une liste de saisies qui
10définissent alors chacun des éléments de la liste. La saisie générée
11permet ensuite à l'utilisateur d'éditer, de créer ou de supprimer des
12éléments de cette liste et/ou de modifier leur ordre.
13
14Elle peut fonctionner sans javascript, mais pour les utilisateurs qui
15l'activent, on peux réordonner les éléments par glisser-déposer via le
16plugin jqueryui.sortable.
17
18Un fois le plugin installé, on peut voir des exemples d'utilisation de
19la saisie sur la page `/ecrire/?exec=exemples_saisie_liste`.
20
21Appel de la saisie
22------------------
23
24La saisie s'appelle dans les squelettes comme n'importe quelle saisie :
25
26```
27[(#REM)
28  paramètres :
29        - nom              => Le nom de la saisie. Obligatoire, le reste est
30                              optionnel
31        - label            => Le label
32        - legende          => La légende du fieldset qui contient la liste
33        - saisies          => La liste de saisies définissant un élément
34        - defaut           => Le tableau des valeurs par défaut de la saisie
35        - interdire_ajout  => Interdit d'ajouter des éléments à la liste.
36        - ordre_fixe       => Interdit de réordonner les éléments de la liste
37        - cacher_supprimer => Cache les boutons supprimer sur les éléments
38                              de la liste
39        - texte_bouton_ajouter => Le texte du bouton ajouter. "Ajouter" sinon.
40        - texte_bouton_supprimer => Le texte du bouton supprimer
41        - masquer_nouveaux => Ajoute un javascript qui masque le nouvel élément
42                              de la liste jusqu'à ce qu'on clique sur "Ajouter".
43]
44
45[(#SAISIE{liste, ma-liste,
46          label=Objets,
47          saisies=#ARRAY{0, #ARRAY{saisie, input,
48                                   label, Titre de l'objet,
49                                   nom, titre_objet},
50                         1, #ARRAY{saisie, textarea,
51                                   nom, description,
52                                   label, Description}}
53})]
54```
55
56On peut aussi utiliser le format de la balise `#GENERER_SAISIES` :
57
58```php
59$ma_saisie = array(
60    'saisie'  => 'liste',
61    'options' => array(
62        'nom'     => 'ma-liste',
63        'label'   => 'Objets',
64    ),
65    'saisies' => array(
66        array(
67            'saisie'  => 'input',
68            'options' => array(
69                'label' => "Titre de l'objet",
70                'nom'   => 'titre_objet',
71            ),
72        ),
73        array(
74            'saisie'  => 'textarea',
75            'options' => array(
76                'label' => "Description",
77                'nom'   => 'description',
78            ),
79        ),
80    ),
81);
82```
83
84Traitement des valeurs postées
85------------------------------
86
87Pour que la saisie puisse fonctionner correctement, il faut exécuter
88des traitements au début des fonctions `verifier` et `traiter`. Le
89plus simple est de toujours commencer vos fonctions `verifier` et
90`traiter` par :
91
92```php
93if (saisies_liste_verifier('ma-liste'))
94    return array();
95```
96
97et vos fonctions traiter par :
98
99```php
100if (saisies_liste_traiter('ma-liste'))
101    return array('editable' => 'oui');
102```
103
104où `ma-liste` est le nom de la saisie liste que vous avez créé. Si le
105formulaire contient plusieurs saisies liste, il faut passer à ces
106fonctions un tableau des noms des saisies, par exemple :
107
108```php
109if (saisies_liste_verifier(array('liste-1', 'liste-2', 'liste-3')))
110    return array();
111```
112
113Les fonctions `saisies_liste_verifier` et `saisies_liste_traiter`
114s'occupent de préparer les valeurs postées de manière à cacher celles
115qui ne sont utiles que pour le fonctionnement interne de la
116saisie. Utiliser la fonction `_request` avant des les avoir appelées
117est à vos risques et périls… Elle retournent le nom de la saisie si le
118formulaire à été posté par un submit propre à une saisie liste, comme
119le bouton supprimer ou les flèches. Dans ce cas on souhaite en général
120interrompre les traitements du formulaire comme dans les exemples
121ci-dessus.
122
123Dans le cas où le formulaire à été posté par un autre submit,
124`saisies_liste_verifier` et `saisies_liste_traiter` retournent
125`FALSE`. On peux alors récupérer les valeurs saisies en appelant :
126
127```php
128_request('ma-liste');
129```
130
131qui aura la forme suivante (si on reprend l'exemple ci-dessus) :
132
133```php
134array(
135    0 => array(
136        'titre_objet' => "Le premier titre saisi par l'utilisateur",
137        'description' => "Une longue description de l'objet…",
138    ),
139    1 => array(
140        'titre_objet' => "Le deuxième titre saisi par l'utilisateur",
141        'description' => "Une description du deuxième objet…",
142    ),
143)
144```
145
146On peut évidement utiliser un tableau de ce genre pour pré-remplir la
147saisie dans la fonction charger, ou pour passer des valeurs par défaut
148à la saisie.
149
150Personnalisation du glisser-déposer
151-----------------------------------
152
153Pour personnaliser l'appel au plugin jqueryui.sortable, on peut
154surcharger le squelette `javascript/saisie_liste.js.html` (voir le
155code de ce squelette pour plus d'informations). On peut aussi créer un
156fichier `javascript/saisie_ma-liste.js.html` pour surcharger une
157saisie particulière.
Note: See TracBrowser for help on using the repository browser.