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!<dc:statement>! elements, felix@3244: for example felix@3244: \begin{lstlisting} felix@3244: <dc:statement> 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: </dc:statement> 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!<dc:elements>! 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: <dc:statement> 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: </dc:statement> felix@3244: <dc:elements> felix@3244: <additional> felix@3244: <dc:attribute name="name" value="${prot_description}"/> felix@3244: <dc:context> felix@3244: <dc:statement> 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: </dc:statement> felix@3244: <!-- ... --> felix@3244: \end{lstlisting} felix@3244: felix@3244: In both cases, an \verb!<dc:elements>! 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!<additional>! in above example. The elements name is translated by felix@3244: the client. felix@3244: felix@3244: While iterating the final results, \verb!<dc:attributes>! have to be specified felix@3244: to define how the artifact is to be created. felix@3244: felix@3244: \begin{lstlisting} felix@3244: <dc:elements> felix@3244: <column> felix@3244: <dc:attribute name="name" value="${prot_column_name}"/> felix@3244: <dc:attribute name="ids" value="additionals-wstv-${prot_rel_pos}-${prot_id}"/> felix@3244: <dc:attribute name="factory" value="staticwkms"/> felix@3244: </column> felix@3244: </dc:elements> 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!<dc:comment>!, felix@3244: \verb!<dc:if>! and the \verb!<dc:when><dc:otherwise>! structure. felix@3244: \verb!<dc:comment>! is an element to allow comments. Choose these over standard felix@3244: \verb=<!-- -->= xml comments, because they are not transferred to the client. felix@3244: \verb!<dc:if>! and \verb!<dc:when>! allow control (rather: definition) flow within felix@3244: the configuration and work in analogy to the XSL-elements \verb!<xsl:if>! felix@3244: and \verb!<xsl:when>!. 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!<dc:context>! element essentially means a database binding. Thus each felix@3244: query (\verb!<dc:statement>!) 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!<dc:context>!, \verb!<dc:context connection="system">!) felix@3244: context allows queries related to the backend database with existing felix@3244: data (e.g. measurements). felix@3244: The "user" context (\verb!<dc:context connection="user">!) 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: <dc:if test="dc:contains($artifact-outs, 'longitudinal_section')"> felix@3244: <longitudinal_section> felix@3244: <dc:call-macro name="annotations"/> felix@3244: </longitudinal_section> felix@3244: </dc:if> 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: <dc:macro name="basedata_4_heightmarks-wq"> felix@3244: <heightmarks> felix@3244: <dc:context> felix@3244: <dc:statement> 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: </dc:statement> felix@3244: <dc:elements> felix@3244: <!-- ... --> felix@3244: </dc:macro> 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: <dc:call-macro name="basedata_4_heightmarks"/> felix@3244: \end{lstlisting} felix@3244: . felix@3244: