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