ldapsaisie/doc/conf/LSobject/ioFormat.docbook

332 lines
13 KiB
Text
Raw Normal View History

2015-07-30 16:37:42 +02:00
<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>
2015-07-30 16:37:42 +02:00
<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([...]);
},
2015-07-30 16:37:42 +02:00
[...]
),
'before_import' => array('function1', 'function2'),
'after_import' => 'function3',
2015-07-30 16:37:42 +02:00
),
[...]
);]]>
</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>
2015-07-30 16:37:42 +02:00
</listitem>
</varlistentry>
<varlistentry>
<term>before_import</term>
<listitem>
<simpara>Chaîne de caractères (ou tableau de chaîne de caractères) correspondant
au nom d'une ou plusieurs fonctions qui seront exécutées avant chaque import.
<link linkend="config-LSobject-ioFormat-triggers">Voir la section concernée</link></simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>after_import</term>
<listitem>
<simpara>Chaîne de caractères (ou tableau de chaîne de caractères) correspondant
au nom d'une ou plusieurs fonctions qui seront exécutées après chaque import.
<link linkend="config-LSobject-ioFormat-triggers">Voir la section concernée</link></simpara>
</listitem>
</varlistentry>
2015-07-30 16:37:42 +02:00
</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>
2015-07-30 16:37:42 +02:00
<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.
2015-07-30 16:37:42 +02:00
<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]',
2015-07-30 16:37:42 +02:00
'length' => [longueur maximale d'une ligne],
'escape' => '[caractère d'échappement]',
'multiple_value_delimiter' => '[délimiteur]',
2015-07-30 16:37:42 +02:00
);]]>
</programlisting>
<variablelist>
<title>Paramètres de configuration</title>
<varlistentry>
<term>delimiter</term>
<listitem>
2020-05-19 18:13:02 +02:00
<simpara>Le caractère utilisé pour délimiter les champs (Par défaut, une virgule).</simpara>
2015-07-30 16:37:42 +02:00
</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
2015-07-30 16:37:42 +02:00
</literal>)
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>enclosure</term>
2015-07-30 16:37:42 +02:00
<listitem>
<simpara>Le caractère utilisé pour encadrer les valeurs des champs
2020-05-19 18:13:02 +02:00
(Par défaut : <literal>"</literal>).</simpara>
2015-07-30 16:37:42 +02:00
</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>
2015-07-30 16:37:42 +02:00
</variablelist>
</para>
</sect4>
</sect3>
<sect3 id="config-LSobject-ioFormat-triggers">
<title>Déclencheurs</title>
<para>Cette section décrit la manière de paramétrer des déclencheurs afin que
&LdapSaisie; exécute durant ses processus, et à des moments bien précis des
traitements d'un &ioFormat;, des fonctions que vous pourrez développer vous
même. De plus, le résultat de l'exécution de vos fonctions pourra influer
sur le déroulement des processus.</para>
<para>Actuellement, les évenements suivant sont gérés :
<informaltable>
<tgroup cols="3"> <!-- on décrit le nombre de colonnes -->
<thead> <!-- on passe au "header" du tableau -->
<row>
<entry>Nom</entry>
<entry>Description</entry>
<entry>Bloquant</entry>
</row>
</thead>
<tbody> <!-- et on remplit les lignes -->
<row>
<entry><literal>before_import</literal></entry>
<entry><simpara>Avant l'import.</simpara></entry>
<entry><simpara>Oui</simpara></entry>
</row>
<row>
<entry><literal>after_import</literal></entry>
<entry><simpara>Après l'import'.</simpara></entry>
<entry><simpara>Non</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<note><simpara>Si un événement est dit <emphasis>bloquant</emphasis>, lors de
l'exécution des actions liées, si une des fonctions retourne <literal>false
</literal>, le processus s'arrêtera.</simpara></note>
</para>
<sect4 id="config-LSobject-ioFormat-triggers-config">
<title>Configuration</title>
<para>La configuration des déclencheurs se fait dans la définition des types
d'&ioFormat;. Par exemple, pour définir les fonctions à exécuter après
l'import des LSobjects de type <emphasis>LSpeople</emphasis> avec son LSioFormat <emphasis>
mycsv</emphasis>, c'est à dire lors de leur évènement <literal>after_import</literal>, il faut
définir la variable suivante :
<programlisting linenumbering="unnumbered"><![CDATA[$GLOBALS['LSobjects']['LSpeople']['ioFormat']['mycsv']['after_import']]]></programlisting>
Cette variable peut contenir soit une chaine de caractères correspondant au
nom de la fonction à exécuter, soit un tableau de chaînes de caractères
correspondant aux noms des fonctions à exécuter. Il est également possible de mettre ici directement
des <ulink url='https://www.php.net/manual/fr/functions.anonymous.php'>fonctions anonymes</ulink>.
</para>
</sect4>
<sect4 id="config-LSobject-ioFormat-triggers-writing">
<title>Ecriture d'une fonction</title>
<para>Une fonction exécutée par un déclencheur d'un ioFormat se déclare de la
manière suivante :
<programlisting linenumbering="unnumbered"><![CDATA[
/*
* Ma fonction à exécuter lors de l'evenement [event]
*
* Paramètres :
* - $ioFormat : Le LSioFormat sur lequel l'évènement survient
* - $data : Les données de contexte de l'évènement
*
* Valeurs retournées :
* - True : Tout s'est bien passé
* - False : Une erreur est survenue ou la fonction souhaite bloquer le
* processus lors d'un évènement bloquant.
*/
function maFonction (&$ioFormat, &$data) {
// Actions
}
]]></programlisting>
Cette fonction doit accepter deux paramètres, le LSioFormat sur lequel l'évènement survient et un
tableau des données contextuelles de l'évènement. Elle doit par ailleurs retourner
<literal>True</literal> si tout s'est bien passé ou <literal>False</literal> en cas de problème.
Dans le cas d'un événement bloquant, si la fonction retourne <literal>False</literal>, le processus
est arrêté.</para>
<para>Les données contextuelles de l'évènement, passées en paramètre, pourront dépendre du contexte
et de l'évènement déclencheur, mais pour les moments, il s'agit toujours d'un tableau telque décrit
ci-dessous :
<programlisting linenumbering="unnumbered"><![CDATA[array(
'input_file' => "[/path/of/import.file]",
'updateIfExists' => [boolean],
'justTry' => [boolean],
'objectsData' => array(
[Données des objets chargés depuis le fichier d'import]
),
'return' => array(
'success' => [boolean],
'LSobject' => "[nom du type d'LSobject]",
'ioFormat' => "[nom du type d'ioFormat]",
'updateIfExists' => [boolean],
'justTry' => [boolean],
'imported' => array([objets importés]),
'updated' => array([objets mis à jour]),
'errors' => array(
array(
'data' => [données de l'objet importé ayant déclenché l'erreur],
'errors' => array (
'globals' => array("Erreur 1", [...]),
'attrs' => array(
'attr1' => array("Erreur 1", [...]),
[...]
),
),
),
[...]
),
),
)]]></programlisting>
<note><simpara>Les clés <literal>objectsData</literal> et <literal>return</literal> sont des références.
En cas de modification, cela influencera respectivement sur les données utilisées pour l'import et
sur le résultat de l'import tel qu'affiché dans l'interface.</simpara></note>
</para>
</sect4>
</sect3>
2015-07-30 16:37:42 +02:00
</sect2>