<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">
felix@3244: \section{Configuration of the Datacage}
felix@3244: 
felix@3244: \subsection{Tasks and Recommendation types of the datacage}
felix@3244: 
felix@3244: The datacage serves two purposes.
felix@3244: It handles automatic 'recommendations', which are instructions
felix@3244: sent by the client to add newly created artifacts to the collection.
felix@3244: From a user perspective, these artifacts mainly represent curves or data
felix@3244: points in the resulting diagrams.
felix@3244: The second task is to let the user add already existing artifacts (i.e.
felix@3244: previous calculations) or new artifacts with access to related data.
felix@3244: 
felix@3244: Irrelevant of the type of elements (recommendations or user picked data) the
felix@3244: datacage can iterate over possible artifacts by accessing its own database.
felix@3244: Thus, to create a list of matching entries, database queries are used.
felix@3244: 
felix@3244: \subsection{Structure of the datacage configuration file meta-data.conf}
felix@3244: 
felix@3244: The datacages behaviour is defined in the file conf/meta-data.xml .
felix@3244: 
felix@3244: In meta-data.xml, database queries are defined as \verb!&lt;dc:statement&gt;! elements,
felix@3244: for example
felix@3244: \begin{lstlisting}
felix@3244:                 &lt;dc:statement&gt;
felix@3244:                   SELECT id          AS prot_id,
felix@3244:                          description AS prot_description
felix@3244:                   FROM wsts WHERE kind = 1 AND river_id = ${river_id}
felix@3244:                 &lt;/dc:statement&gt;
felix@3244: \end{lstlisting}
felix@3244: 
felix@3244: As can be seen from the example, the datacage configuration file can maintain
felix@3244: its own stack of variables (\${river\_id} in above example).
felix@3244: 
felix@3244: The database query will usually deliver one or many results, over which is
felix@3244: iterated using the \verb!&lt;dc:elements&gt;! elements.
felix@3244: 
felix@3244: Information from this results can be used for two goals.
felix@3244: It can be taken as output, in which
felix@3244: case the client will either request the creation of these artifacts (considering
felix@3244: recommendations), or shown by the client in a the 'datacage widget',
felix@3244: the graphical representation of data which can be added in the current
felix@3244: context.  The later is seen when the user clicks on the Datacage button in
felix@3244: a diagram.
felix@3244: Or information can be used to feed a second (or third...) database query.
felix@3244: Following above example:
felix@3244: 
felix@3244: \begin{lstlisting}
felix@3244:                 &lt;dc:statement&gt;
felix@3244:                   SELECT id          AS prot_id,
felix@3244:                          description AS prot_description
felix@3244:                   FROM wsts WHERE kind = 1 AND river_id = ${river_id}
felix@3244:                 &lt;/dc:statement&gt;
felix@3244:                 &lt;dc:elements&gt;
felix@3244:                   &lt;additional&gt;
felix@3244:                     &lt;dc:attribute name="name" value="${prot_description}"/&gt;
felix@3244:                     &lt;dc:context&gt;
felix@3244:                       &lt;dc:statement&gt;
felix@3244:                         SELECT id       AS prot_column_id,
felix@3244:                                name     AS prot_column_name,
felix@3244:                                position AS prot_rel_pos
felix@3244:                         FROM wst_columns WHERE wst_id = ${prot_id}
felix@3244:                         ORDER by position
felix@3244:                       &lt;/dc:statement&gt;
felix@3244:                       &lt;!-- ... --&gt;
felix@3244: \end{lstlisting}
felix@3244: 
felix@3244: In both cases, an \verb!&lt;dc:elements&gt;! element makes database queries available.
felix@3244: Also
felix@3244: note how the variables are defined in the first query and reused in the second
felix@3244: query (\$\{prot\_it\}).
felix@3244: 
felix@3244: Any alement not prefixed with "dc" represents a (sub-) node in the resulting
felix@3244: tree.  The client will display these nodes and maybe subnodes in the datacage
felix@3244: widget - \verb!&lt;additional&gt;! in above example.  The elements name is translated by
felix@3244: the client.
felix@3244: 
felix@3244: While iterating the final results, \verb!&lt;dc:attributes&gt;! have to be specified
felix@3244: to define how the artifact is to be created.
felix@3244: 
felix@3244: \begin{lstlisting}
felix@3244:                       &lt;dc:elements&gt;
felix@3244:                         &lt;column&gt;
felix@3244:                           &lt;dc:attribute name="name" value="${prot_column_name}"/&gt;
felix@3244:                           &lt;dc:attribute name="ids" value="additionals-wstv-${prot_rel_pos}-${prot_id}"/&gt;
felix@3244:                           &lt;dc:attribute name="factory" value="staticwkms"/&gt;
felix@3244:                         &lt;/column&gt;
felix@3244:                       &lt;/dc:elements&gt;
felix@3244: \end{lstlisting}
felix@3244: 
felix@3244: The "name" attribute is what is to be displayed in the client, the "ids" are given
felix@3244: to the server and pass important information about the chosen data.
felix@3244: The "factory" is chosen according to the type of data displayed.
felix@3244: 
felix@3244: So far, three other elements have not yet been mentioned: \verb!&lt;dc:comment&gt;!,
felix@3244: \verb!&lt;dc:if&gt;! and the \verb!&lt;dc:when&gt;&lt;dc:otherwise&gt;! structure.
felix@3244: \verb!&lt;dc:comment&gt;! is an element to allow comments.  Choose these over standard
felix@3244: \verb=&lt;!-- --&gt;= xml comments, because they are not transferred to the client.
felix@3244: \verb!&lt;dc:if&gt;! and \verb!&lt;dc:when&gt;! allow control (rather: definition) flow within
felix@3244: the configuration and work in analogy to the XSL-elements \verb!&lt;xsl:if&gt;!
felix@3244: and \verb!&lt;xsl:when&gt;!.
felix@3244: 
felix@3244: When dealing with the behaviour specification of the datacage, multiple
felix@3244: interpretations for the term "context" are possible.
felix@3244: A \verb!&lt;dc:context&gt;! element essentially means a database binding.  Thus each
felix@3244: query (\verb!&lt;dc:statement&gt;!) needs to be nested in its own context.
felix@3244: Furthermore, two types of databases with own bindings exist:
felix@3244: The "system" (default for \verb!&lt;dc:context&gt;!, \verb!&lt;dc:context connection="system"&gt;!)
felix@3244: context allows queries related to the backend database with existing
felix@3244: data (e.g. measurements).
felix@3244: The "user" context (\verb!&lt;dc:context connection="user"&gt;!) allows queries against
felix@3244: the database which stores information about already existing artifacts and
felix@3244: calculations.
felix@3244: 
felix@3244: Another connotation for the term "context" is the situation from which
felix@3244: the datacage is queried.  The standard case is a from the datacage widget.
felix@3244: When the user opens the datacage from the graphical client, this is done
felix@3244: from one of possible multiple diagrams.
felix@3244: When the datacage is queried, it gets as an argument the "out" of
felix@3244: the current artifact.  The out corresponds to the diagram type.
felix@3244: 
felix@3244: For example the inner block of
felix@3244: 
felix@3244: \begin{lstlisting}
felix@3244:           &lt;dc:if test="dc:contains($artifact-outs, 'longitudinal_section')"&gt;
felix@3244:               &lt;longitudinal_section&gt;
felix@3244:                 &lt;dc:call-macro name="annotations"/&gt;
felix@3244:               &lt;/longitudinal_section&gt;
felix@3244:           &lt;/dc:if&gt;
felix@3244: \end{lstlisting}
felix@3244: 
felix@3244: will only be executed if called from the datacage within a
felix@3244: longitudinal\_section diagram.
felix@3244: 
felix@3244: In the given example another concept of the datacage configuration is
felix@3244: encountered: Macros.
felix@3244: 
felix@3244: Macros help to avoid duplication of parts of the document.  As the datacage
felix@3244: of some diagrams should include the same type of data, the same query should
felix@3244: be executed in multiple situations.
felix@3244: 
felix@3244: Therefore a macro can be defined, like in
felix@3244: 
felix@3244: \begin{lstlisting}
felix@3244:         &lt;dc:macro name="basedata_4_heightmarks-wq"&gt;
felix@3244:           &lt;heightmarks&gt;
felix@3244:             &lt;dc:context&gt;
felix@3244:               &lt;dc:statement&gt;
felix@3244:                 SELECT id          AS prot_id,
felix@3244:                        description AS prot_description
felix@3244:                 FROM wsts WHERE kind = 4 AND river_id = ${river_id}
felix@3244:               &lt;/dc:statement&gt;
felix@3244:               &lt;dc:elements&gt;
felix@3244:               &lt;!-- ... --&gt;
felix@3244:         &lt;/dc:macro&gt;
felix@3244: \end{lstlisting}
felix@3244: 
felix@3244: and invoked from another location within the document, e.g. with
felix@3244: 
felix@3244: \begin{lstlisting}
felix@3244: 
felix@3244:                 &lt;dc:call-macro name="basedata_4_heightmarks"/&gt;
felix@3244: \end{lstlisting}
felix@3244: .
felix@3244: 




</pre></body></html>