--- a/flys-artifacts/doc/datacage.txt	Wed Jun 06 11:52:23 2012 +0000
+++ b/flys-artifacts/doc/datacage.txt	Wed Jun 06 11:53:55 2012 +0000
@@ -1,3 +1,7 @@
+This document describes how the datacage configuration works, from a user
+perspective.  Some rather technical details are omitted and mechanisms
+simplified.
+
 The datacages behaviour is defined in the file conf/meta-data.xml .
 
 The datacage serves two purposes.
@@ -22,3 +26,59 @@
 
 As can be seen from the example, the datacage configuration file can maintain
 its own stack of variables (${river_id} in above example).
+
+The database query will usually deliver one or many results, over which is
+iterated using the <dc:elements> elements.
+
+Information from this results can be used for two goals.
+It can be taken as output, in which
+case the client will either request the creation of these artifacts (considering
+recommendations), or shown by the client in a the 'datacage widget',
+the graphical representation of data which can be added in the current
+context.  The later is seen when the user clicks on the Datacage button in
+a diagram.
+Or information can be used to feed a second (or third...) database query.
+Following above example:
+
+                <dc:statement>
+                  SELECT id          AS prot_id,
+                         description AS prot_description
+                  FROM wsts WHERE kind = 1 AND river_id = ${river_id}
+                </dc:statement>
+                <dc:elements>
+                  <additional>
+                    <dc:attribute name="name" value="${prot_description}"/>
+                    <dc:context>
+                      <dc:statement>
+                        SELECT id       AS prot_column_id,
+                               name     AS prot_column_name,
+                               position AS prot_rel_pos
+                        FROM wst_columns WHERE wst_id = ${prot_id}
+                        ORDER by position
+                      </dc:statement>
+                      <!-- ... -->
+
+In both cases, an <dc:elements> element makes database queries available.
+Also
+note how the variables are defined in the first query and reused in the second
+query (${prot_it}).
+
+Any alement not prefixed with "dc" represents a (sub-) node in the resulting
+tree.  The client will display these nodes and maybe subnodes in the datacage
+widget - <additional> in above example.  The elements name is translated by
+the client.
+
+While iterating the final results, <dc:attributes> have to be specified
+to define how the artifact is to be created.
+
+                      <dc:elements>
+                        <column>
+                          <dc:attribute name="name" value="${prot_column_name}"/>
+                          <dc:attribute name="ids" value="additionals-wstv-${prot_rel_pos}-${prot_id}"/>
+                          <dc:attribute name="factory" value="staticwkms"/>
+                        </column>
+                      </dc:elements>
+
+The "name" attribute is what is to be displayed in the client, the "ids" are given
+to the server and pass important information about the chosen data.
+The "factory" is chosen according to the type of data displayed.