ldapsaisie/doc/conf/LSobject/ioFormat.docbook

<sect2 id="config-LSobject-ioFormat">
  <title>ioFormat</title>
  <para>Cette section décrit la manière de paramétrer les formats d'import/export
  pour un type d'&LSobject; donné.</para>

<para>La configuration des <emphasis>ioFormats</emphasis> se situe dans la
configuration des &LSobjects;, dans la variable <varname>ioFormat</varname>
(<emphasis>$GLOBALS['LSobjects']['[nom du type d'LSobject]']['ioFormat']</emphasis>).
Cette variable est un tableau associatif dont la clé est l'identifiant du format et
dont la valeur associée est la configuration du format.

<important><para>Le moteur d'importation simule la validation d'un formulaire de
création du type d'&LSobject;. En conséquence :
<itemizedlist>
  <listitem><simpara>seul les attributs présent dans le formulaire de création peuvent
  être importés.</simpara></listitem>
  <listitem><simpara>tous les attributs obligatoires présents dans le formulaire de
  création doivent être fournis par le fichier source ou générer à partir des autres
  attributs.</simpara></listitem>
  <listitem><simpara>Les valeurs des attributs issus de l'importation seront vue comme
  des valeurs retournées par le formulaire et non comme des valeurs des attribus LDAP
  eux-même. Ainsi et par exemple, un attribut traité comme un booléen dans un formulaire
  pourra prendre comme valeur par défaut <literal>yes</literal> ou <literal>no</literal>.
  </simpara></listitem>
</itemizedlist>
</para></important>
<programlisting>
<citetitle>Structure</citetitle>
<![CDATA[$GLOBALS['LSobjects']['[nom du type d'LSobject]']['ioFormat'] = array (
  '[ioFormat ID]' => array (
    'label' => '[Label du type de fichier]',
    'driver' => '[Pilote d'ioFormat utilisé]',
    'driver_options' => array([Options du pilote d'ioFormat utilisé]),
    'fields => array (
      '[champ 1]' => '[attribut 1]',
      '[champ 2]' => '[attribut 2]',
      [...]
    ),
    'generated_fields' => array (
      '[attribute 3]' => '[LSformat]',
      '[attribute 4]' => array('[LSformat1]', '[LSformat2]', ...)
      '[attribute 5]' => function($attrs, $row) {
        return array([...]);
      },
      [...]
    )
  ),
  [...]
);]]>
</programlisting>

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

<varlistentry>
  <term>label</term>
  <listitem>
    <simpara>Le label du format</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>driver</term>
  <listitem>
    <simpara>Le pilote a utilisé pour ce format. Le pilote permet de gérér la lecture
    et l'écriture dans un type de fichier d'import/export. Pour plus d'information sur
    les pilotes disponibles, <link linkend='config-LSobject-ioFormat-drivers'>Voir la
    section concernée.</link></simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>driver_options</term>
  <listitem>
    <simpara>Tableau associatif des options du pilote utilisé pour ce format. Pour
    plus d'informations, consulter la documentation du pilote utilisé.</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>fields</term>
  <listitem>
    <simpara>Tableau associatif permettant d'associer un champ du fichier source (la clé)
    avec attribut de l'objet LDAP (la valeur).</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>generated_fields</term>
  <listitem>
    <simpara>Tableau associatif permettant de définir soit des &LSformats;, soit un
    <emphasis>callable</emphasis> (au sens PHP) pour générer les valeurs d'attributs automatiquement.
    Ce tableau contient en clé, le nom de l'attribut à générer, et en valeur associée, un ou plusieurs
    &LSformat; ou un <emphasis>callable</emphasis> à utiliser pour générer ses valeurs. En cas de
    &LSformat;, ils seront composés à l'aide des valeurs des autres attributs de l'objet. En cas d'un
    <emphasis>callable</emphasis>, il sera appeler avec en paramètre le tableau des valeurs des autres
    attributs (<literal>$attrs</literal>), le tableau des données issues du fichier source
    (<literal>$row</literal>) et devra retourner le tableau des valeurs générées de l'attribut.
    </simpara>
  </listitem>
</varlistentry>

</variablelist>
</para>

<sect3 id="config-LSobject-ioFormat-drivers">
  <title>Pilote d'ioFormat</title>
  <para>Cette section décrit la manière de configurer les pilotes d'ioFormat utilisés
  lors des imports/exports d'&LSobjects;.</para>

<sect4 id="config-LSobject-ioFormat-drivers-CSV">
    <title>Pilote de fichiers CSV</title>
    <para>Ce pilote permet de gérer l'import/export de &LSobject; à partir d'un fichier
    <literal>CSV</literal>. Depuis la version 4 d'LdapSaisie, ce pilote utilise les
    fonctions standards <literal>fgetcsv()</literal> et <literal>fputcsv</literal>
    fournis par PHP. Avant cela, la classe PEAR <application>
    <ulink url='http://pear.php.net/package/File_CSV_DataSource'>File_CSV_DataSource
    </ulink></application> était utilisée. Par défaut, les paramètres de lecture et
    d'écriture des fichiers sont : la virgule sert de délimiteur, le caractère
    <literal>"</literal> peut être utilisé pour encadrer les valeurs des champs et la
    longueur maximale d'une ligne est infini. Ces paramètres peuvent être modifiés en
    configurant les options du pilote.
<programlisting>
<citetitle>Structure</citetitle>
<![CDATA[$GLOBALS['LSobjects']['[nom du type d'LSobject]']['ioFormat']['[ID ioFormat]']['driver_options'] = array (
  'delimiter' => '[délimiteur]',
  'enclosure' => '[caractère d'encadrement de texte]',
  'length' => [longueur maximale d'une ligne],
  'escape' => '[caractère d'échappement]',
  'multiple_value_delimiter' => '[délimiteur]',
);]]>
</programlisting>

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

<varlistentry>
  <term>delimiter</term>
  <listitem>
    <simpara>Le caractère utilisé pour délimiter les champs (Par défaut, une virgule).</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>length</term>
  <listitem>
    <simpara>La longueur maximale d'une ligne du fichier. Si zéro est spécifié, la longueur d'une
    ligne ne sera pas limité, mais la lecture du fichier sera ralentie. (Par défaut : <literal>0
    </literal>)
    </simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>enclosure</term>
  <listitem>
    <simpara>Le caractère utilisé pour encadrer les valeurs des champs
    (Par défaut : <literal>"</literal>).</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>escape</term>
  <listitem>
    <simpara>Le caractère d'échappement utilisé si un des champs d'une ligne de fichier contient le
    caractère utilisé pour encadrer les valeurs. (Par défaut : <literal>\</literal>).</simpara>
    <note><simpara>Selon la RFC4180, l'echappement du caractère utilisé pour encadrer les valeurs des
    champs doit se faire en le doublant. Le caractère défini ici est une alternative à ce comportement
    par défaut. Pour désactiver ce caractère d'échappement alternatif, il est possible depuis de la
    version 7.4.0 de PHP de mettre ici une chaine vide.</simpara></note>
  </listitem>
</varlistentry>

<varlistentry>
  <term>multiple_value_delimiter</term>
  <listitem>
    <simpara>Le caractère utilisé pour délimiter au sein d'un champs, les valeurs valeurs multiples d'un
    attribut (Par défaut : <literal>|</literal>).</simpara>
  </listitem>
</varlistentry>

</variablelist>

</para>

</sect4>

</sect3>

</sect2>