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