From 9d5d94c8bad2e365449c1609b3b16fd3e97d0c4e Mon Sep 17 00:00:00 2001
From: Benjamin Renard <brenard@easter-eggs.com>
Date: Fri, 20 May 2011 17:44:42 +0200
Subject: [PATCH] Doc : Added config informations about customActions

---
 doc/LS.entities.xml                     |   1 +
 doc/conf/LSobject.docbook               |  15 ++++
 doc/conf/LSobject/customActions.docbook | 109 ++++++++++++++++++++++++
 doc/conf/conf.entities.xml              |   1 +
 4 files changed, 126 insertions(+)
 create mode 100644 doc/conf/LSobject/customActions.docbook

diff --git a/doc/LS.entities.xml b/doc/LS.entities.xml
index aff845ba..c25c8959 100644
--- a/doc/LS.entities.xml
+++ b/doc/LS.entities.xml
@@ -16,6 +16,7 @@
 <!ENTITY LSobjects "<link linkend='config-LSobject'>LSobjects</link>">
 <!ENTITY LSattribute "<link linkend='config-LSattribute'>LSattribute</link>">
 <!ENTITY LSattributes "<link linkend='config-LSattribute'>LSattributes</link>">
+<!ENTITY customActions "<link linkend='config-LSobject-customActions'>customActions</link>">
 <!ENTITY LSrelation "<link linkend='config-LSobject-LSrelation'>LSrelation</link>">
 <!ENTITY LSrelations "<link linkend='config-LSobject-LSrelation'>LSrelations</link>">
 <!ENTITY LSform "<link linkend='config-LSobject-LSform'>LSform</link>">
diff --git a/doc/conf/LSobject.docbook b/doc/conf/LSobject.docbook
index 6b27456b..687fef75 100644
--- a/doc/conf/LSobject.docbook
+++ b/doc/conf/LSobject.docbook
@@ -44,6 +44,11 @@
   'label' => 'objet1',  
   'display_name_format' => '[format]',
   'displayAttrName' => '[booleen]',
+
+  //Custom Actions
+  'customActions' => array (
+    // Configuration des customActions pour ce type d'objet
+  ),
   
   // LSrelation
   'LSrelation' => array(
@@ -195,6 +200,15 @@
   </listitem>
 </varlistentry>
 
+<varlistentry>
+  <term>customActions</term>
+  <listitem>
+    <simpara>Tableau associatif contenant les paramètres de configuration
+    des &customActions;. <link linkend="config-LSobject-customActions">Voir la section
+    concernée</link>.</simpara>
+  </listitem>
+</varlistentry>
+
 <varlistentry>
   <term>LSrelation</term>
   <listitem>
@@ -246,6 +260,7 @@
   &conf-LSattribute;
   &conf-LSobject-container_auto_create;
   &conf-LSobject-triggers;
+  &conf-LSobject-customActions;
   &conf-LSobject-LSrelation;
   &conf-LSobject-LSform;
   &conf-LSobject-LSsearch;
diff --git a/doc/conf/LSobject/customActions.docbook b/doc/conf/LSobject/customActions.docbook
new file mode 100644
index 00000000..b48ce647
--- /dev/null
+++ b/doc/conf/LSobject/customActions.docbook
@@ -0,0 +1,109 @@
+<sect2 id="config-LSobject-customActions">
+  <title>customActions</title>
+  <para>Cette section décrit la manière de configurer les actions personnalisées exécutables
+  sur les &LSobjects; appelées &customActions;.</para>
+  
+<programlisting>
+<citetitle>Structure</citetitle>
+<![CDATA[$GLOBALS['LSobjects']['[nom du type d'LSobject]']['customActions'] = array (
+  'action1' => array(
+    'label' => '[label l'action]',
+    '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]',
+    'rights' => array(
+      'LSprofile1',
+      'LSprofile2',
+      ...
+    )
+  )
+);]]>
+</programlisting>
+
+<variablelist>
+<title>Paramètres de configuration</title>
+
+<varlistentry>
+  <term>label</term>
+  <listitem>
+    <simpara>Le label de la relation.</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 le &LSobject; 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 nom de l'objet.</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 nom de l'objet.</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>
+
+<sect3>
+    <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 :
+ *     - $object : Le LSobject 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 ($object) {
+
+  // Actions
+
+}
+    ]]></programlisting>
+Cette fonction doit prendre pour seul paramètre, le &LSobject; 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>
+
+<note><simpara>Ces fonctions sont le plus couramment définies au sein d'&LSaddon;.</simpara></note>
+
+</sect3>
+
+
+</sect2>
diff --git a/doc/conf/conf.entities.xml b/doc/conf/conf.entities.xml
index ca7211b2..81693fe7 100644
--- a/doc/conf/conf.entities.xml
+++ b/doc/conf/conf.entities.xml
@@ -17,6 +17,7 @@
 <!ENTITY conf-LSobject-triggers SYSTEM "LSobject/triggers.docbook">
 <!ENTITY conf-LSobject-LSform SYSTEM "LSobject/LSform.docbook">
 <!ENTITY conf-LSobject-LSsearch SYSTEM "LSobject/LSsearch.docbook">
+<!ENTITY conf-LSobject-customActions SYSTEM "LSobject/customActions.docbook">
 <!ENTITY conf-LSobject-LSrelation SYSTEM "LSobject/LSrelation.docbook">
 
 <!ENTITY conf-LSattribute SYSTEM "LSattribute.docbook">