ldapsaisie/doc/conf/LSobject/LSsearch.docbook

<sect2 id="config-LSobject-LSsearch">
  <title>LSsearch</title>
  <para>Cette section décrit la manière de paramétrer les recherches dans
  l'annuaire pour un type d'&LSobject; donné.</para>

<para>La configuration des <emphasis>LSsearch</emphasis> se situe dans la 
configuration des &LSobjects;, dans la variable <varname>LSsearch</varname>
(<emphasis>$GLOBALS['LSobjects']['[nom du type d'LSobject]']['LSsearch']</emphasis>).
<programlisting>
<citetitle>Structure</citetitle>
<![CDATA[$GLOBALS['LSobjects']['[nom du type d'LSobject]']['LSsearch'] = array (
  'attrs' => array(
    'attr1',
    'attr2',
    ...
    'attr3' => array(
      'searchLSformat' => '[LSformat]',
      'approxLSformat' => '[LSformat]',
    ),
    ...
  ),
  'params' => array(
    // Paramètres de la recherche
    'pattern' => '[string]',
    'sizelimit' => [integer],
    'recursive' => [boolean],
    'approx' => [boolean],
    'withoutCache' => [boolean],
    'onlyAccessible' => [boolean],
    // Paramètres de tri
    'sortBy' => [displayName|subDn],
    'sortDirection' => [ASC|DESC],
    'sortlimit' => [integer],
    // Paramètre d'affichage
    'displayFormat' => [LSformat],
    'nbObjectsByPage' => [integer],
    'nbObjectsByPageChoices' => array([integer], [integer], ...),
    'nbPageLinkByPage' => [integer],
    'validPatternRegex' => '[regex]'
  ),
  'predefinedFilters' => array(
    'filter1' => 'label filter1',
    'filter2' => 'label filter2'
  ),
  'extraDisplayedColumns' => array(
    'col1' => array(
      'label' => 'label column 1',
      'LSformat' => '[LSformat]'
    ),
    'col2' => array(
      'label' => 'label column 2',
      'generateFunction' => '[fonction de génération]',
      'additionalAttrs' => array('[attr1]', '[attr2]', ...),
      'escape' => [booléen],
    ),
    'col3' => array(
      'label' => 'label column 3',
      'LSformat' => '[LSformat]',
      'alternativeLSformats' => array (
        '[LSformat 1]',
        '[LSformat 2]'
      ),
      'formaterLSformat' => '[LSformat]',
      'formaterFunction' => '[fonction de formatage]',
      'cssStyle' => '[CSS style]',
      'visibleTo' => array (
        '[LSprofile 1]',
        '[LSprofile 2]'
      )
    ),
  ),
  'customActions' =>  array (
    // Configuration des customActions pour les recherches de ce type d'objet
  )
);]]>
</programlisting>

<variablelist>
<title>Paramètres de configuration</title>

<varlistentry>
  <term>attrs</term>
  <listitem>
    <para>Tableau listant les attributs pouvant être utilisés dans les filtres
    de recherche LDAP employés par &LdapSaisie;. Lorsqu'un motif de recherche est
    passé par l'utilisateur, &LdapSaisie; composera un filtre LDAP à partir de
    cette liste.</para>
    <para>Lors d'une recherche non-approximative, le filtre de recherche sera
    composé (par défaut) de la manière suivante :
    <programlisting>(|(attr1=*motif*)(attr2=*motif*)...)</programlisting></para>
    <para>Lors d'une recherche approximative, le filtre de recherche sera
    composé (par défaut) de la manière suivante :
    <programlisting>(|(attr1=~motif)(attr2~=motif)...)</programlisting></para>
    <para>Il est également possible de paramétrer la manière dont sera composé le filtre
    de recherche attribut par attribut à l'aide des paramètres <emphasis>searchLSformat</emphasis>
    et <emphasis>approxLSformat</emphasis>.</para>
    <important><simpara>Ces filtres, une fois composés, sont insérés dans un autre,
    filtrant en plus sur les <emphasis>ObjectClass</emphasis> du type
    d'&LSobject; de la manière suivante :</simpara>
    <programlisting><![CDATA[(& (&(objectclass=oc1)(objectclass=oc2)) (filtre) )]]></programlisting></important>

    <variablelist>
    <title>Paramètres des attributs</title>

<varlistentry>
  <term>searchLSformat</term>
  <listitem>
    <para>Ce paramètre est un &LSformat; permettant de définir, attribut par attribut, comment le
    filtre de recherche LDAP est composé à partir d'un motif de recherche et en cas de recherche
    non-approximative.</para>
    <para>Ce &LSformat; est composé à l'aide des éléments <emphasis>name</emphasis>, le nom de
    l'attribut et <emphasis>pattern</emphasis>, le motif de recherche.
    <programlisting>
<citetitle>Exemple</citetitle>
<![CDATA[(%{name}=%{pattern})]]>
    </programlisting></para>
    <important><simpara>Le filtre déduit doit obligatoirement commencer par <emphasis>(</emphasis> et
    se terminer par <emphasis>)</emphasis>.</simpara></important>
  </listitem>
</varlistentry>

<varlistentry>
  <term>approxLSformat</term>
  <listitem>
    <para>Ce paramètre est un &LSformat; permettant de définir, attribut par attribut, comment le
    filtre de recherche LDAP est composé à partir d'un motif de recherche et en cas de recherche
    approximative.</para>
    <para>Ce &LSformat; est composé à l'aide des éléments <emphasis>name</emphasis>, le nom de
    l'attribut et <emphasis>pattern</emphasis>, le motif de recherche.
    <programlisting>
<citetitle>Exemple</citetitle>
<![CDATA[(%{name}=~%{pattern})]]>
    </programlisting></para>
    <important><simpara>Le filtre déduit doit obligatoirement commencer par <emphasis>(</emphasis> et
    se terminer par <emphasis>)</emphasis>.</simpara></important>
  </listitem>
</varlistentry>

    </variablelist>

  </listitem>
</varlistentry>

<varlistentry>
  <term>params</term>
  <listitem>
    <para>Tableau des paramètres par défaut d'une recherche. Ce tableau contient
les paramètres qui seront utilisés pour initialisé une recherche. Ces paramètres
pourront être redéfini par l'utilisateur ou par l'application en fonction du
contexte dans lequel cette recherche est effectuée.</para>
    
    <variablelist>
    <title>Paramètres de configuration</title>
    
<varlistentry>
  <term>pattern</term>
  <listitem>
    <simpara>Mot clé de la recherche.</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>sizelimit</term>
  <listitem>
    <simpara>Entier determinant le nombre maximum d'objet pouvant être retournés dans
    une recherche.</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>recursive</term>
  <listitem>
    <simpara>Booléen déterminant si la recherche récursive est activée.</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>approx</term>
  <listitem>
    <simpara>Booléen déterminant si la recherche approximative est activée.</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>withoutCache</term>
  <listitem>
    <simpara>Booléen déterminant si le cache de recherche doit être utilisé.</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>onlyAccessible</term>
  <listitem>
    <simpara>Booléen déterminant si seul les objets accessibles à l'utilisateur connecté doivent être retournés par la recherche.</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>sortBy</term>
  <listitem>
    <simpara>Mot clé déterminant sur quel valeur/colonne le résultat de recherche
    sera trié.</simpara>
    <simpara>Valeurs possibles : <literal>displayName</literal>, <literal>subDn</literal> ou  <literal>NULL</literal>.</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>sortDirection</term>
  <listitem>
    <simpara>Mot clé déterminant le sens du trie du résultat de la recherche.</simpara>
    <simpara>Valeurs possibles : <literal>ASC</literal>, <literal>DESC</literal> ou  <literal>NULL</literal>.</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>sortlimit</term>
  <listitem>
    <simpara>Entier determinant le nombre maximum d'objet pouvant être triés dans
    le résultat d'une recherche.</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>displayFormat</term>
  <listitem>
    <simpara>&LSformat; d'affichage du nom de l'objet dans le résultat de la recherche.</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>nbObjectsByPage</term>
  <listitem>
    <simpara>Entier déterminant le nombre d'objet maximum affichés dans une page
    de résultat de la recherche.</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>nbObjectsByPageChoices</term>
  <listitem>
    <simpara>Tableau des choix proposés à l'utilisateur pour le nombre d'objets maximum affichés dans une page
    de résultat de la recherche.</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>nbPageLinkByPage</term>
  <listitem>
    <simpara>Entier déterminant le nombre maximum de liens vers d'autres pages
    affichés sous le résultat de la recherche.</simpara>
    <simpara>Par défaut : <literal>10</literal></simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>validPatternRegex</term>
  <listitem>
    <simpara>Expression régulière de validation des mots clés de recherche pour
    ce type d'&LSobject;.</simpara>
    <simpara>(Par défaut :
    <literal>/^[\w \-\_\\\'\"^\[\]\(\)\{\}\=\+\£\%\$\€\.\:\;\,\?\/\@]+$/iu</literal>)
    </simpara>
  </listitem>
</varlistentry>

    </variablelist>
    
  </listitem>
</varlistentry>

<varlistentry>
  <term>predefinedFilters</term>
  <listitem>
    <para>Tableau associatif contenant des filtres prédéfinis pour la recherche.
    Les clés sont les filtres au format LDAP et les valeurs sont les labels associés.</para>
  </listitem>
</varlistentry> 

<varlistentry>
  <term>extraDisplayedColumns</term>
  <listitem>
    <para>Tableau associatif contenant des colonnes supplémentaires à afficher dans les
    résultats de recherche. Les clés sont les identifiants des colonnes supplémentaires
    et les valeurs sont leur configuration définie à partir des paramètres suivant :</para>

    <variablelist>

      <varlistentry>
        <term>label</term>
        <listitem>
          <simpara>Le label de la colonne.</simpara>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>LSformat</term>
        <listitem>
          <simpara>Le &LSformat; d'affichage de la colonne. Ce format est composé à partir
          des attributs des objets LDAP dans leur format brut.</simpara>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>alternativeLSformats</term>
        <listitem>
          <simpara>Tableau des &LSformats; alternatifs à utiliser si le résultat du format
          principal est vide. Les formats définis dans cette liste sont essayés les uns
          après les autres et le premier &LSformat; retournant une valeur non-vide est
          utilisé.</simpara>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>formaterLSformat</term>
        <listitem>
          <simpara>&LSformat; optionnel permettant de mettre en forme le résultat obtenu des
          &LSformats; précédents. Ce &LSformat; ne sera utilisé que si le résultat obtenu
          précédement n'est pas vide. Il est ainsi possible d'utiliser les paramètres <literal>
          LSformat</literal> et <literal>alternativeLSformats</literal> afin de récupérer la
          valeur à afficher, puis de la mettre en forme grâce à ce &LSformat;. Ce format est
          composé à partir des attributs des objets LDAP dans leur format brut et de la valeur
          retournés précedement accessible via la variable <literal>val</literal>.</simpara>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>formaterFunction</term>
        <listitem>
          <simpara>Le nom d'une fonction optionnelle à exécuter pour mettre en forme le résultat
          obtenu des &LSformats; précédents. Cette fonction ne sera appelée que si le résultat
          obtenu précédement n'est pas vide. La fonction prendra en paramètre la valeur à mettre
          en forme et retournera la valeur mise en forme.</simpara>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>generateFunction</term>
        <listitem>
          <simpara>Le nom d'une fonction qui sera utilisée pour générer la valeur d'affichage de
          cette colonne. La fonction prendra en paramètre une référence de l'objet <literal>
          LSsearchEntry</literal> et retournera la valeur de la colonne.</simpara>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>additionalAttrs</term>
        <listitem>
          <simpara>Un tableau de nom d'attributs à inclure dans le resultat de la recherche LDAP.
          Ce tableau permet notamment d'inclure les attributs nécessaires au bon fonctionnement
          de la fonction <literal>generateFunction</literal>.</simpara>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>escape</term>
        <listitem>
          <simpara>Ce paramètre booléen permet de définir si, lors de l'affichage, le contenu de
          la colonne doit être transformé pour protéger les caractères éligibles en entités HTML.
          Par défaut, ce paramètre est <literal>Vrai</literal>.</simpara>
          <warning><simpara>Cette fonctionnalité existe pour des raisons de sécurité et notamment
          en protection des failles <literal>XSS</literal>. Si vous désactivez cette fonctionnalité,
          il est important de gérer la problématique de sécurité par ailleurs.</simpara></warning>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>cssStyle</term>
        <listitem>
          <simpara>Ce paramètre permet de définir un style CSS personnalisé pour la colonne.
          S'il est défini, le contenu de ce paramètre sera ajouté en tant qu'attribut <literal>
          style</literal> des balises <literal>th</literal> et <literal>td</literal> de la
          colone.</simpara>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>visibleTo</term>
        <listitem>
          <simpara>Ce paramètre permet de restreindre la visibilité de cette colonne aux seuls
          &LSprofiles; spécifiés. S'il est omis, la colonne sera visible pour tous.</simpara>
        </listitem>
      </varlistentry>

    </variablelist>
  </listitem>
</varlistentry>

<varlistentry>
  <term>customActions</term>
  <listitem>
    <simpara>Tableau associatif contenant les paramètres de configuration
    des &customSearchActions;. <link linkend="config-LSobject-customSearchActions">Voir la section
    concernée</link>.</simpara>
  </listitem>
</varlistentry>

</variablelist>
</para>

<sect3 id="config-LSobject-customSearchActions">
  <title>customActions</title>
  <para>Cette section décrit la manière de configurer les actions personnalisées exécutables
  sur les recherches d'&LSobjects; appelées &customSearchActions;.</para>

<programlisting>
<citetitle>Structure</citetitle>
<![CDATA[$GLOBALS['LSobjects']['[nom du type d'LSobject]']['LSsearch']['customActions'] = array (
  'action1' => array(
    'label' => '[label l'action]',
    'hideLabel' => '[booléen]',
    'icon' => '[nom de l'icône de l'action]',
    'function' => '[fonction à exécuter]',
    'question_format' => '[LSformat de la question de confirmation]',
    'onSuccessMsgFormat' => '[LSformat du message à afficher en cas de succès de l'action]',
    'disableOnSuccessMsg' => '[booléen]',
    'noConfirmation' => '[booléen]',
    'redirectToObjectList' => '[booléen]',
    'rights' => array(
      'LSprofile1',
      'LSprofile2',
      ...
    )
  )
);]]>
</programlisting>

<variablelist>
<title>Paramètres de configuration</title>

<varlistentry>
  <term>label</term>
  <listitem>
    <simpara>Le label de l'action.</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>hideLabel</term>
  <listitem>
    <simpara>Cache le label dans le bouton de l'action.</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>icon</term>
  <listitem>
    <simpara>Nom de l'îcone à afficher dans le bouton de l'action. Ce nom correspond
    au nom du fichier de l'image (sans l'extention) qui devra se trouver dans le 
    dossier <emphasis>/public_html/images/[nom du theme d'images]/</emphasis>.</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>function</term>
  <listitem>
    <simpara>Le nom de la fonction à exécuter qui implémente l'action personnalisée
    Cette fonction prendra en seule paramètre l'objet &LSsearch; sur lequel l'action
    devra être exécutée et retournera <emphasis>True</emphasis> en cas de succès ou 
    <emphasis>False</emphasis> en cas d'échec d'exécution de la fonction.</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>question_format</term>
  <listitem>
    <simpara>Le &LSformat; de la question de confirmation d'exécution de l'action.
    Ce &LSformat; sera composé à l'aide du label de l'action.</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>onSuccessMsgFormat</term>
  <listitem>
    <simpara>Le &LSformat; du message à afficher en cas de succès d'exécution de
    l'action. Ce &LSformat; sera composé à l'aide du label de l'action.</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>disableOnSuccessMsg</term>
  <listitem>
    <simpara>Booléen permetant de désactiver le message afficher en cas de succès
    d'exécution de l'action.</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>noConfirmation</term>
  <listitem>
    <simpara>Booléen permetant de désactiver la confirmation de l'exécution de
    l'action.</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>redirectToObjectList</term>
  <listitem>
    <simpara>Booléen permetant de rediriger ou non l'utilisateur vers la liste
    des objets (Vrai par défaut). Si l'utilisateur n'est redirigé, le template
    par défaut (ou celui défini durant l'éxécution de la fonction) sera affiché.
    </simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>rights</term>
  <listitem>
    <simpara>Tableau contenant la liste des noms des &LSprofiles; ayant le droit
    d'exécuter cette action.</simpara>
  </listitem>
</varlistentry>

</variablelist>

<sect4>
    <title>Ecriture d'une fonction implémentant une customAction</title>
    <para>Une fonction implémentant une <emphasis>customAction</emphasis> se déclare de
    la manière suivante :
    <programlisting linenumbering="unnumbered"><![CDATA[
/*
 * Ma fonction implémentant ma customAction
 *
 * Paramètre :
 *     - $search : L'objet LSsearch de la recherche sur lequel mon action doit être exécutée
 *
 * Valeurs retournées :
 *     - True : Tout s'est bien passé
 *     - False : Une erreur est survenue
 */
function maFonction ($search) {

  // Actions

}
    ]]></programlisting>
Cette fonction doit prendre pour seul paramètre, l'objet &LSsearch; sur lequel l'action
personnalisée doit être exécutée et doit retourner soit <literal>True</literal> si
tout s'est bien passé, soit <literal>False</literal> en cas de problème.</para>

<important><simpara>La recherche passée en paramètre n'a pas encore été exécutée. En conséquence,
si vous avez besoin d'accéder au résultat de la recherche, il est nécessaire d'exécuter au préalable :
<literal>$search -> run();</literal>. Cela permet en outre, de modifier les paramètres de la recherche
avant de l'exécuter. Cela peut par exemple être utile, si vous avez besoin d'accèder aux valeurs
d'attributs particuliers, d'ajouter des attributs au résultat de la recherche :
<literal>$search -> setParam('attributes',array('attr1','attr2'));</literal>.</simpara></important>

<note><simpara>Ces fonctions sont le plus couramment définies au sein d'&LSaddon;.</simpara></note>

</sect4>

</sect3>

</sect2>