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