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