--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/artifacts/doc/datacage-config-manual/content.tex	Thu Apr 25 15:23:37 2013 +0200
@@ -0,0 +1,164 @@
+\section{Configuration of the Datacage}
+
+\subsection{Tasks and Recommendation types of the datacage}
+
+The datacage serves two purposes.
+It handles automatic 'recommendations', which are instructions
+sent by the client to add newly created artifacts to the collection.
+From a user perspective, these artifacts mainly represent curves or data
+points in the resulting diagrams.
+The second task is to let the user add already existing artifacts (i.e.
+previous calculations) or new artifacts with access to related data.
+
+Irrelevant of the type of elements (recommendations or user picked data) the
+datacage can iterate over possible artifacts by accessing its own database.
+Thus, to create a list of matching entries, database queries are used.
+
+\subsection{Structure of the datacage configuration file meta-data.conf}
+
+The datacages behaviour is defined in the file conf/meta-data.xml .
+
+In meta-data.xml, database queries are defined as \verb!<dc:statement>! elements,
+for example
+\begin{lstlisting}
+                <dc:statement>
+                  SELECT id          AS prot_id,
+                         description AS prot_description
+                  FROM wsts WHERE kind = 1 AND river_id = ${river_id}
+                </dc:statement>
+\end{lstlisting}
+
+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 \verb!<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:
+
+\begin{lstlisting}
+                <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>
+                      <!-- ... -->
+\end{lstlisting}
+
+In both cases, an \verb!<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 - \verb!<additional>! in above example.  The elements name is translated by
+the client.
+
+While iterating the final results, \verb!<dc:attributes>! have to be specified
+to define how the artifact is to be created.
+
+\begin{lstlisting}
+                      <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>
+\end{lstlisting}
+
+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.
+
+So far, three other elements have not yet been mentioned: \verb!<dc:comment>!,
+\verb!<dc:if>! and the \verb!<dc:when><dc:otherwise>! structure.
+\verb!<dc:comment>! is an element to allow comments.  Choose these over standard
+\verb=<!-- -->= xml comments, because they are not transferred to the client.
+\verb!<dc:if>! and \verb!<dc:when>! allow control (rather: definition) flow within
+the configuration and work in analogy to the XSL-elements \verb!<xsl:if>!
+and \verb!<xsl:when>!.
+
+When dealing with the behaviour specification of the datacage, multiple
+interpretations for the term "context" are possible.
+A \verb!<dc:context>! element essentially means a database binding.  Thus each
+query (\verb!<dc:statement>!) needs to be nested in its own context.
+Furthermore, two types of databases with own bindings exist:
+The "system" (default for \verb!<dc:context>!, \verb!<dc:context connection="system">!)
+context allows queries related to the backend database with existing
+data (e.g. measurements).
+The "user" context (\verb!<dc:context connection="user">!) allows queries against
+the database which stores information about already existing artifacts and
+calculations.
+
+Another connotation for the term "context" is the situation from which
+the datacage is queried.  The standard case is a from the datacage widget.
+When the user opens the datacage from the graphical client, this is done
+from one of possible multiple diagrams.
+When the datacage is queried, it gets as an argument the "out" of
+the current artifact.  The out corresponds to the diagram type.
+
+For example the inner block of
+
+\begin{lstlisting}
+          <dc:if test="dc:contains($artifact-outs, 'longitudinal_section')">
+              <longitudinal_section>
+                <dc:call-macro name="annotations"/>
+              </longitudinal_section>
+          </dc:if>
+\end{lstlisting}
+
+will only be executed if called from the datacage within a
+longitudinal\_section diagram.
+
+In the given example another concept of the datacage configuration is
+encountered: Macros.
+
+Macros help to avoid duplication of parts of the document.  As the datacage
+of some diagrams should include the same type of data, the same query should
+be executed in multiple situations.
+
+Therefore a macro can be defined, like in
+
+\begin{lstlisting}
+        <dc:macro name="basedata_4_heightmarks-wq">
+          <heightmarks>
+            <dc:context>
+              <dc:statement>
+                SELECT id          AS prot_id,
+                       description AS prot_description
+                FROM wsts WHERE kind = 4 AND river_id = ${river_id}
+              </dc:statement>
+              <dc:elements>
+              <!-- ... -->
+        </dc:macro>
+\end{lstlisting}
+
+and invoked from another location within the document, e.g. with
+
+\begin{lstlisting}
+
+                <dc:call-macro name="basedata_4_heightmarks"/>
+\end{lstlisting}
+.
+