LSsearch : add customAction feature
[ldapsaisie.git] / doc / conf / LSobject / LSsearch.docbook
1 <sect2 id="config-LSobject-LSsearch">
2   <title>LSsearch</title>
3   <para>Cette section décrit la manière de paramétrer les recherches dans
4   l'annuaire pour un type d'&LSobject; donné.</para>
5
6 <para>La configuration des <emphasis>LSsearch</emphasis> se situe dans la 
7 configuration des &LSobjects;, dans la variable <varname>LSsearch</varname>
8 (<emphasis>$GLOBALS['LSobjects']['[nom du type d'LSobject]']['LSsearch']</emphasis>).
9 <programlisting>
10 <citetitle>Structure</citetitle>
11 <![CDATA[$GLOBALS['LSobjects']['[nom du type d'LSobject]']['LSsearch'] = array (
12   'attrs' => array(
13     'attr1',
14     'attr2',
15     ...
16     'attr3' => array(
17       'searchLSformat' => '[LSformat]',
18       'approxLSformat' => '[LSformat]',
19     ),
20     ...
21   ),
22   'params' => array(
23     // Paramètres de la recherche
24     'pattern' => '[string]',
25     'sizelimit' => [integer],
26     'recursive' => [boolean],
27     'approx' => [boolean],
28     'withoutCache' => [boolean],
29     // Paramètres de tri
30     'sortBy' => [displayName|subDn],
31     'sortDirection' => [ASC|DESC],
32     'sortlimit' => [integer],
33     // Paramètre d'affichage
34     'displayFormat' => [LSformat],
35     'nbObjectsByPage' => [integer],
36     'nbPageLinkByPage' => [integer]
37   ),
38   'predefinedFilters' => array(
39     'filter1' => 'label filter1',
40     'filter2' => 'label filter2'
41   ),
42   'extraDisplayedColumns' => array(
43     'col1' => array(
44       'label' => 'label column 1',
45       'LSformat' => '[LSformat]'
46     ),
47     'col2' => array(
48       'label' => 'label column 2',
49       'LSformat' => '[LSformat]',
50       'alternativeLSformats' => array (
51         '[LSformat 1]',
52         '[LSformat 2]'
53       )
54     )
55   ),
56   'customActions' =>  array (
57     // Configuration des customActions pour les recherches de ce type d'objet
58   )
59 );]]>
60 </programlisting>
61
62 <variablelist>
63 <title>Paramètres de configuration</title>
64
65 <varlistentry>
66   <term>attrs</term>
67   <listitem>
68     <para>Tableau listant les attributs pouvant être utilisés dans les filtres
69     de recherche LDAP employés par &LdapSaisie;. Lorsqu'un motif de recherche est
70     passé par l'utilisateur, &LdapSaisie; composera un filtre LDAP à partir de
71     cette liste.</para>
72     <para>Lors d'une recherche non-approximative, le filtre de recherche sera
73     composé (par défaut) de la manière suivante :
74     <programlisting>(|(attr1=*motif*)(attr2=*motif*)...)</programlisting></para>
75     <para>Lors d'une recherche approximative, le filtre de recherche sera
76     composé (par défaut) de la manière suivante :
77     <programlisting>(|(attr1=~motif)(attr2~=motif)...)</programlisting></para>
78     <para>Il est également possible de paramétrer la manière dont sera composé le filtre
79     de recherche attribut par attribut à l'aide des paramètres <emphasis>searchLSformat</emphasis>
80     et <emphasis>approxLSformat</emphasis>.</para>
81     <important><simpara>Ces filtres, une fois composés, sont insérés dans un autre,
82     filtrant en plus sur les <emphasis>ObjectClass</emphasis> du type
83     d'&LSobject; de la manière suivante :</simpara>
84     <programlisting><![CDATA[(& (&(objectclass=oc1)(objectclass=oc2)) (filtre) )]]></programlisting></important>
85
86     <variablelist>
87     <title>Paramètres des attributs</title>
88
89 <varlistentry>
90   <term>searchLSformat</term>
91   <listitem>
92     <para>Ce paramètre est un &LSformat; permettant de définir, attribut par attribut, comment le
93     filtre de recherche LDAP est composé à partir d'un motif de recherche et en cas de recherche
94     non-approximative.</para>
95     <para>Ce &LSformat; est composé à l'aide des éléments <emphasis>name</emphasis>, le nom de
96     l'attribut et <emphasis>pattern</emphasis>, le motif de recherche.
97     <programlisting>
98     <citetitle>Exemple</citetitle>
99 <![CDATA[(%{name}=%{pattern})]]>
100     </programlisting></para>
101     <important><simpara>Le filtre déduit doit obligatoirement commencer par <emphasis>(</emphasis> et
102     se terminer par <emphasis>)</emphasis>.</simpara></important>
103   </listitem>
104 </varlistentry>
105
106 <varlistentry>
107   <term>approxLSformat</term>
108   <listitem>
109     <para>Ce paramètre est un &LSformat; permettant de définir, attribut par attribut, comment le
110     filtre de recherche LDAP est composé à partir d'un motif de recherche et en cas de recherche
111     approximative.</para>
112     <para>Ce &LSformat; est composé à l'aide des éléments <emphasis>name</emphasis>, le nom de
113     l'attribut et <emphasis>pattern</emphasis>, le motif de recherche.
114     <programlisting>
115     <citetitle>Exemple</citetitle>
116 <![CDATA[(%{name}=~%{pattern})]]>
117     </programlisting></para>
118     <important><simpara>Le filtre déduit doit obligatoirement commencer par <emphasis>(</emphasis> et
119     se terminer par <emphasis>)</emphasis>.</simpara></important>
120   </listitem>
121 </varlistentry>
122
123     </variablelist>
124
125   </listitem>
126 </varlistentry>
127
128 <varlistentry>
129   <term>params</term>
130   <listitem>
131     <para>Tableau des paramètres par défaut d'une recherche. Ce tableau contient
132 les paramètres qui seront utilisés pour initialisé une recherche. Ces paramètres
133 pourront être redéfini par l'utilisateur ou par l'application en fonction du
134 contexte dans lequel cette recherche est effectuée.</para>
135     
136     <variablelist>
137     <title>Paramètres de configuration</title>
138     
139 <varlistentry>
140   <term>pattern</term>
141   <listitem>
142     <simpara>Mot clé de la recherche.</simpara>
143   </listitem>
144 </varlistentry>
145
146 <varlistentry>
147   <term>sizelimit</term>
148   <listitem>
149     <simpara>Entier determinant le nombre maximum d'objet pouvant être retournés dans
150     une recherche.</simpara>
151   </listitem>
152 </varlistentry>
153
154 <varlistentry>
155   <term>recursive</term>
156   <listitem>
157     <simpara>Booléen déterminant si la recherche récursive est activée.</simpara>
158   </listitem>
159 </varlistentry>
160
161 <varlistentry>
162   <term>approx</term>
163   <listitem>
164     <simpara>Booléen déterminant si la recherche approximative est activée.</simpara>
165   </listitem>
166 </varlistentry>
167
168 <varlistentry>
169   <term>withoutCache</term>
170   <listitem>
171     <simpara>Booléen déterminant si le cache de recherche doit être utilisé.</simpara>
172   </listitem>
173 </varlistentry>
174
175 <varlistentry>
176   <term>sortBy</term>
177   <listitem>
178     <simpara>Mot clé déterminant sur quel valeur/colonne le résultat de recherche
179     sera trié.</simpara>
180     <simpara>Valeurs possibles : <literal>displayName</literal>, <literal>subDn</literal> ou  <literal>NULL</literal>.</simpara>
181   </listitem>
182 </varlistentry>
183
184 <varlistentry>
185   <term>sortDirection</term>
186   <listitem>
187     <simpara>Mot clé déterminant le sens du trie du résultat de la recherche.</simpara>
188     <simpara>Valeurs possibles : <literal>ASC</literal>, <literal>DESC</literal> ou  <literal>NULL</literal>.</simpara>
189   </listitem>
190 </varlistentry>
191
192 <varlistentry>
193   <term>sortlimit</term>
194   <listitem>
195     <simpara>Entier determinant le nombre maximum d'objet pouvant être triés dans
196     le résultat d'une recherche.</simpara>
197   </listitem>
198 </varlistentry>
199
200 <varlistentry>
201   <term>displayFormat</term>
202   <listitem>
203     <simpara>&LSformat; d'affichage du nom de l'objet dans le résultat de la recherche.</simpara>
204   </listitem>
205 </varlistentry>
206
207 <varlistentry>
208   <term>nbObjectsByPage</term>
209   <listitem>
210     <simpara>Entier déterminant le nombre d'objet maximum affichés dans une page
211     de résultat de la recherche.</simpara>
212   </listitem>
213 </varlistentry>
214
215 <varlistentry>
216   <term>nbPageLinkByPage</term>
217   <listitem>
218     <simpara>Entier déterminant le nombre maximum de liens vers d'autres pages
219     affichés sous le résultat de la recherche.</simpara>
220     <simpara>Par défaut : <literal>10</literal></simpara>
221   </listitem>
222 </varlistentry>
223
224     </variablelist>
225     
226   </listitem>
227 </varlistentry>
228
229 <varlistentry>
230   <term>predefinedFilters</term>
231   <listitem>
232     <para>Tableau associatif contenant des filtres prédéfinis pour la recherche.
233     Les clés sont les filtres au format LDAP et les valeurs sont les labels associés.</para>
234   </listitem>
235 </varlistentry> 
236
237 <varlistentry>
238   <term>extraDisplayedColumns</term>
239   <listitem>
240     <para>Tableau associatif contenant des colonnes supplémentaires à afficher dans les
241     résultats de recherche. Les clés sont les identifiants des colonnes supplémentaires
242     et les valeurs sont leur configuration définie à partir des paramètres suivant :</para>
243
244     <variablelist>
245
246       <varlistentry>
247         <term>label</term>
248         <listitem>
249           <simpara>Le label de la colonne.</simpara>
250         </listitem>
251       </varlistentry>
252
253       <varlistentry>
254         <term>LSformat</term>
255         <listitem>
256           <simpara>Le &LSformat; d'affichage de la colonne. Ce format est composé à partir
257           des attributs des objets LDAP dans leur format brut.</simpara>
258         </listitem>
259       </varlistentry>
260
261       <varlistentry>
262         <term>alternativeLSformats</term>
263         <listitem>
264           <simpara>Tableau des &LSformats; alternatifs à utiliser si le résultat du format
265           principal est vide. Les formats définis dans cette liste sont essayés les uns
266           après les autres et le premier &LSformat; retournant une valeur non-vide est
267           utilisé.</simpara>
268         </listitem>
269       </varlistentry>
270
271     </variablelist>
272   </listitem>
273 </varlistentry>
274
275 <varlistentry>
276   <term>customActions</term>
277   <listitem>
278     <simpara>Tableau associatif contenant les paramètres de configuration
279     des &customSearchActions;. <link linkend="config-LSobject-customSearchActions">Voir la section
280     concernée</link>.</simpara>
281   </listitem>
282 </varlistentry>
283
284 </variablelist>
285 </para>
286
287 <sect3 id="config-LSobject-customSearchActions">
288   <title>customActions</title>
289   <para>Cette section décrit la manière de configurer les actions personnalisées exécutables
290   sur les recherches d'&LSobjects; appelées &customSearchActions;.</para>
291
292 <programlisting>
293 <citetitle>Structure</citetitle>
294 <![CDATA[$GLOBALS['LSobjects']['[nom du type d'LSobject]']['LSsearch']['customActions'] = array (
295   'action1' => array(
296     'label' => '[label l'action]',
297     'hideLabel' => '[booléen]',
298     'icon' => '[nom de l'icône de l'action]',
299     'function' => '[fonction à exécuter]',
300     'question_format' => '[LSformat de la question de confirmation]',
301     'onSuccessMsgFormat' => '[LSformat du message à afficher en cas de succès de l'action]',
302     'disableOnSuccessMsg' => '[booléen]',
303     'noConfirmation' => '[booléen]',
304     'redirectToObjectList' => '[booléen]',
305     'rights' => array(
306       'LSprofile1',
307       'LSprofile2',
308       ...
309     )
310   )
311 );]]>
312 </programlisting>
313
314 <variablelist>
315 <title>Paramètres de configuration</title>
316
317 <varlistentry>
318   <term>label</term>
319   <listitem>
320     <simpara>Le label de l'action.</simpara>
321   </listitem>
322 </varlistentry>
323
324 <varlistentry>
325   <term>hideLabel</term>
326   <listitem>
327     <simpara>Cache le label dans le bouton de l'action.</simpara>
328   </listitem>
329 </varlistentry>
330
331 <varlistentry>
332   <term>icon</term>
333   <listitem>
334     <simpara>Nom de l'îcone à afficher dans le bouton de l'action. Ce nom correspond
335     au nom du fichier de l'image (sans l'extention) qui devra se trouver dans le 
336     dossier <emphasis>/public_html/images/[nom du theme d'images]/</emphasis>.</simpara>
337   </listitem>
338 </varlistentry>
339
340 <varlistentry>
341   <term>function</term>
342   <listitem>
343     <simpara>Le nom de la fonction à exécuter qui implémente l'action personnalisée
344     Cette fonction prendra en seule paramètre l'objet &LSsearch; sur lequel l'action
345     devra être exécutée et retournera <emphasis>True</emphasis> en cas de succès ou 
346     <emphasis>False</emphasis> en cas d'échec d'exécution de la fonction.</simpara>
347   </listitem>
348 </varlistentry>
349
350 <varlistentry>
351   <term>question_format</term>
352   <listitem>
353     <simpara>Le &LSformat; de la question de confirmation d'exécution de l'action.
354     Ce &LSformat; sera composé à l'aide du label de l'action.</simpara>
355   </listitem>
356 </varlistentry>
357
358 <varlistentry>
359   <term>onSuccessMsgFormat</term>
360   <listitem>
361     <simpara>Le &LSformat; du message à afficher en cas de succès d'exécution de
362     l'action. Ce &LSformat; sera composé à l'aide du label de l'action.</simpara>
363   </listitem>
364 </varlistentry>
365
366 <varlistentry>
367   <term>disableOnSuccessMsg</term>
368   <listitem>
369     <simpara>Booléen permetant de désactiver le message afficher en cas de succès
370     d'exécution de l'action.</simpara>
371   </listitem>
372 </varlistentry>
373
374 <varlistentry>
375   <term>noConfirmation</term>
376   <listitem>
377     <simpara>Booléen permetant de désactiver la confirmation de l'exécution de
378     l'action.</simpara>
379   </listitem>
380 </varlistentry>
381
382 <varlistentry>
383   <term>redirectToObjectList</term>
384   <listitem>
385     <simpara>Booléen permetant de rediriger ou non l'utilisateur vers la liste
386     des objets (Vrai par défaut). Si l'utilisateur n'est redirigé, le template
387     par défaut (ou celui défini durant l'éxécution de la fonction) sera affiché.
388     </simpara>
389   </listitem>
390 </varlistentry>
391
392 <varlistentry>
393   <term>rights</term>
394   <listitem>
395     <simpara>Tableau contenant la liste des noms des &LSprofiles; ayant le droit
396     d'exécuter cette action.</simpara>
397   </listitem>
398 </varlistentry>
399
400 </variablelist>
401
402 <sect4>
403     <title>Ecriture d'une fonction implémentant une customAction</title>
404     <para>Une fonction implémentant une <emphasis>customAction</emphasis> se déclare de
405     la manière suivante :
406     <programlisting linenumbering="unnumbered"><![CDATA[
407 /*
408  * Ma fonction implémentant ma customAction
409  *
410  * Paramètre :
411  *     - $search : L'objet LSsearch de la recherche sur lequel mon action doit être exécutée
412  *
413  * Valeurs retournées :
414  *     - True : Tout s'est bien passé
415  *     - False : Une erreur est survenue
416  */
417 function maFonction ($search) {
418
419   // Actions
420
421 }
422     ]]></programlisting>
423 Cette fonction doit prendre pour seul paramètre, l'objet &LSsearch; sur lequel l'action
424 personnalisée doit être exécutée et doit retourner soit <literal>True</literal> si
425 tout s'est bien passé, soit <literal>False</literal> en cas de problème.</para>
426
427 <important><simpara>La recherche passée en paramètre n'a pas encore été exécutée. En conséquence,
428 si vous avez besoin d'accéder au résultat de la recherche, il est nécessaire d'exécuter au préalable :
429 <literal>$search -> run();</literal>. Cela permet en outre, de modifier les paramètres de la recherche
430 avant de l'exécuter. Cela peut par exemple être utile, si vous avez besoin d'accèder aux valeurs
431 d'attributs particuliers, d'ajouter des attributs au résultat de la recherche :
432 <literal>$search -> setParam('attributes',array('attr1','attr2'));</literal>.</simpara></important>
433
434 <note><simpara>Ces fonctions sont le plus couramment définies au sein d'&LSaddon;.</simpara></note>
435
436 </sect4>
437
438 </sect3>
439
440 </sect2>