From d8e0d40deee97fb5051615e545281684cbf67668 Mon Sep 17 00:00:00 2001
From: Benjamin Renard <brenard@easter-eggs.com>
Date: Thu, 4 May 2017 17:28:13 +0200
Subject: [PATCH] Add documentation

---
 doc/conf/LSattribute/LSattr_html.docbook      |  1 +
 .../LSattr_html/LSattr_html.entities.xml      |  3 +
 ...LSattr_html_jsonCompositeAttribute.docbook | 96 +++++++++++++++++++
 3 files changed, 100 insertions(+)
 create mode 100644 doc/conf/LSattribute/LSattr_html/LSattr_html_jsonCompositeAttribute.docbook

diff --git a/doc/conf/LSattribute/LSattr_html.docbook b/doc/conf/LSattribute/LSattr_html.docbook
index 2c2bdd1b..59fdd074 100644
--- a/doc/conf/LSattribute/LSattr_html.docbook
+++ b/doc/conf/LSattribute/LSattr_html.docbook
@@ -6,6 +6,7 @@
   &conf-LSattr_html_boolean;
   &conf-LSattr_html_date;
   &conf-LSattr_html_image;
+  &conf-LSattr_html_jsonCompositeAttribute;
   &conf-LSattr_html_mail;
   &conf-LSattr_html_maildir;
   &conf-LSattr_html_mailQuota;
diff --git a/doc/conf/LSattribute/LSattr_html/LSattr_html.entities.xml b/doc/conf/LSattribute/LSattr_html/LSattr_html.entities.xml
index 3be2d267..3e342b14 100644
--- a/doc/conf/LSattribute/LSattr_html/LSattr_html.entities.xml
+++ b/doc/conf/LSattribute/LSattr_html/LSattr_html.entities.xml
@@ -2,6 +2,7 @@
 <!ENTITY conf-LSattr_html_boolean SYSTEM "LSattr_html_boolean.docbook">
 <!ENTITY conf-LSattr_html_date SYSTEM "LSattr_html_date.docbook">
 <!ENTITY conf-LSattr_html_image SYSTEM "LSattr_html_image.docbook">
+<!ENTITY conf-LSattr_html_jsonCompositeAttribute SYSTEM "LSattr_html_jsonCompositeAttribute.docbook">
 <!ENTITY conf-LSattr_html_mail SYSTEM "LSattr_html_mail.docbook">
 <!ENTITY conf-LSattr_html_maildir SYSTEM "LSattr_html_maildir.docbook">
 <!ENTITY conf-LSattr_html_mailQuota SYSTEM "LSattr_html_mailQuota.docbook">
@@ -17,3 +18,5 @@
 <!ENTITY conf-LSattr_html_url SYSTEM "LSattr_html_url.docbook">
 <!ENTITY conf-LSattr_html_valueWithUnit SYSTEM "LSattr_html_valueWithUnit.docbook">
 <!ENTITY conf-LSattr_html_xmpp SYSTEM "LSattr_html_xmpp.docbook">
+
+<!ENTITY LSattr_html_select_list "<link linkend='config-LSattr_html_select_list'>LSattr_html_select_list</link>">
diff --git a/doc/conf/LSattribute/LSattr_html/LSattr_html_jsonCompositeAttribute.docbook b/doc/conf/LSattribute/LSattr_html/LSattr_html_jsonCompositeAttribute.docbook
new file mode 100644
index 00000000..09fe1097
--- /dev/null
+++ b/doc/conf/LSattribute/LSattr_html/LSattr_html_jsonCompositeAttribute.docbook
@@ -0,0 +1,96 @@
+<sect4 id="config-LSattr_html_jsonCompositeAttribute">
+  <title>LSattr_html_jsonCompositeAttribute</title>
+  <para>Ce type est utilisé pour la gestion des attributs dont les valeurs sont
+  des dictionnaires de valeurs encodées aux formats <emphasis>JSON</emphasis>.</para>
+  
+  <programlisting linenumbering="unnumbered">
+<citetitle>Exemple de valeur gérée</citetitle>
+<![CDATA[{"component1": "value1", "component2": "value2", "component3": "value3"}]]>
+</programlisting>
+
+  <para>Le principe est que ces dictionnaires contienent plusieurs composants référencés
+  par leur clé et stockant une valeur dont le type peut être un texte libre ou
+  bien être issue d'une liste déroulante configurable selon le même principe que
+  le type d'attribut &LSattr_html_select_list;.</para>
+  
+  <programlisting linenumbering="unnumbered">
+<citetitle>Structure</citetitle>...
+<![CDATA['html_options' => array (
+   'components' => array (
+     '[clé composant 1]' => array (
+       'label' => '[Label du composant]',
+       'type' => '[Type de la valeur stocké]',
+       'required' => [Booléen],
+       'check_data' => => array (
+         // Régle de vérification syntaxique des données saisies
+       ),
+     ),
+     '[clé composant 2]' => array (
+       'label' => '[Label du composant 2]',
+       'type' => 'select_list',
+       'required' => [Booléen],
+       'options' => array (
+         [Configuration équivalente à un attribut LSattr_html_select_list]
+       )
+     ),
+     [...]
+   ),
+),]]>
+...
+</programlisting>
+
+<variablelist>
+<title>Paramètres de configuration</title>
+
+<varlistentry>
+  <term>components</term>
+  <listitem>
+    <para>Tableau associatif obligatoire contenant en valeur clé, l'identifiant des
+    composants, correspondant à la clé dans le dictionnaire <emphasis>JSON</emphasis>,
+    et en valeurs associés, la configuration du composant.</para>
+
+<variablelist>
+  <varlistentry>
+    <term>label</term>
+    <listitem>
+      <simpara>Le label du composant.</simpara>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>type</term>
+    <listitem>
+      <simpara>Le type de valeur du composant. Les types possibles sont
+      <literal>text</literal> ou <literal>select_list</literal> pour respectivement
+      soit une valeur saisie librement, soit une valeur sélectionnée parmis une liste
+      déroulante.</simpara>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>options</term>
+    <listitem>
+      <simpara>Dans le cadre d'un composant de type <literal>select_list</literal>, cela
+      correspond à la configuration de la liste déroulante. Cette configuration utilise la
+      même syntaxe de configuration que celle du type d'attribut &LSattr_html_select_list;
+      et son paramètre <literal>html_options</literal>.</simpara>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>check_data</term>
+    <listitem>
+	  <simpara>Tableau associatif contenant les règles de vérification syntaxique
+	  des données du composant. Ces règles sont configurables de la même manière
+	  que les celles des valeurs attributs. 
+	  <link linkend='config-LSattribute-check-data'>Voir la section concernée.</link>
+	  </simpara>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+  </listitem>
+</varlistentry>
+
+</variablelist>
+</sect4>