Mercurial > dive4elements > river

comparison flys-artifacts/doc/datacage-config-manual/content.tex @ 3244:1a79d47ed14b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Copied content from doc/datacage.txt to doc/datacage-config-manual (texed). flys-artifacts/trunk@4877 c6561f87-3c4e-4783-a992-168aeb5c3f6f
author Felix Wolfsteller <felix.wolfsteller@intevation.de>
date Thu, 05 Jul 2012 19:23:52 +0000
parents
children
comparison
equal deleted inserted replaced
3243:46208d806da0 3244:1a79d47ed14b
1 \section{Configuration of the Datacage}
2
3 \subsection{Tasks and Recommendation types of the datacage}
4
5 The datacage serves two purposes.
6 It handles automatic 'recommendations', which are instructions
7 sent by the client to add newly created artifacts to the collection.
8 From a user perspective, these artifacts mainly represent curves or data
9 points in the resulting diagrams.
10 The second task is to let the user add already existing artifacts (i.e.
11 previous calculations) or new artifacts with access to related data.
12
13 Irrelevant of the type of elements (recommendations or user picked data) the
14 datacage can iterate over possible artifacts by accessing its own database.
15 Thus, to create a list of matching entries, database queries are used.
16
17 \subsection{Structure of the datacage configuration file meta-data.conf}
18
19 The datacages behaviour is defined in the file conf/meta-data.xml .
20
21 In meta-data.xml, database queries are defined as \verb!<dc:statement>! elements,
22 for example
23 \begin{lstlisting}
24 <dc:statement>
25 SELECT id AS prot_id,
26 description AS prot_description
27 FROM wsts WHERE kind = 1 AND river_id = ${river_id}
28 </dc:statement>
29 \end{lstlisting}
30
31 As can be seen from the example, the datacage configuration file can maintain
32 its own stack of variables (\${river\_id} in above example).
33
34 The database query will usually deliver one or many results, over which is
35 iterated using the \verb!<dc:elements>! elements.
36
37 Information from this results can be used for two goals.
38 It can be taken as output, in which
39 case the client will either request the creation of these artifacts (considering
40 recommendations), or shown by the client in a the 'datacage widget',
41 the graphical representation of data which can be added in the current
42 context. The later is seen when the user clicks on the Datacage button in
43 a diagram.
44 Or information can be used to feed a second (or third...) database query.
45 Following above example:
46
47 \begin{lstlisting}
48 <dc:statement>
49 SELECT id AS prot_id,
50 description AS prot_description
51 FROM wsts WHERE kind = 1 AND river_id = ${river_id}
52 </dc:statement>
53 <dc:elements>
54 <additional>
55 <dc:attribute name="name" value="${prot_description}"/>
56 <dc:context>
57 <dc:statement>
58 SELECT id AS prot_column_id,
59 name AS prot_column_name,
60 position AS prot_rel_pos
61 FROM wst_columns WHERE wst_id = ${prot_id}
62 ORDER by position
63 </dc:statement>
64 <!-- ... -->
65 \end{lstlisting}
66
67 In both cases, an \verb!<dc:elements>! element makes database queries available.
68 Also
69 note how the variables are defined in the first query and reused in the second
70 query (\$\{prot\_it\}).
71
72 Any alement not prefixed with "dc" represents a (sub-) node in the resulting
73 tree. The client will display these nodes and maybe subnodes in the datacage
74 widget - \verb!<additional>! in above example. The elements name is translated by
75 the client.
76
77 While iterating the final results, \verb!<dc:attributes>! have to be specified
78 to define how the artifact is to be created.
79
80 \begin{lstlisting}
81 <dc:elements>
82 <column>
83 <dc:attribute name="name" value="${prot_column_name}"/>
84 <dc:attribute name="ids" value="additionals-wstv-${prot_rel_pos}-${prot_id}"/>
85 <dc:attribute name="factory" value="staticwkms"/>
86 </column>
87 </dc:elements>
88 \end{lstlisting}
89
90 The "name" attribute is what is to be displayed in the client, the "ids" are given
91 to the server and pass important information about the chosen data.
92 The "factory" is chosen according to the type of data displayed.
93
94 So far, three other elements have not yet been mentioned: \verb!<dc:comment>!,
95 \verb!<dc:if>! and the \verb!<dc:when><dc:otherwise>! structure.
96 \verb!<dc:comment>! is an element to allow comments. Choose these over standard
97 \verb=<!-- -->= xml comments, because they are not transferred to the client.
98 \verb!<dc:if>! and \verb!<dc:when>! allow control (rather: definition) flow within
99 the configuration and work in analogy to the XSL-elements \verb!<xsl:if>!
100 and \verb!<xsl:when>!.
101
102 When dealing with the behaviour specification of the datacage, multiple
103 interpretations for the term "context" are possible.
104 A \verb!<dc:context>! element essentially means a database binding. Thus each
105 query (\verb!<dc:statement>!) needs to be nested in its own context.
106 Furthermore, two types of databases with own bindings exist:
107 The "system" (default for \verb!<dc:context>!, \verb!<dc:context connection="system">!)
108 context allows queries related to the backend database with existing
109 data (e.g. measurements).
110 The "user" context (\verb!<dc:context connection="user">!) allows queries against
111 the database which stores information about already existing artifacts and
112 calculations.
113
114 Another connotation for the term "context" is the situation from which
115 the datacage is queried. The standard case is a from the datacage widget.
116 When the user opens the datacage from the graphical client, this is done
117 from one of possible multiple diagrams.
118 When the datacage is queried, it gets as an argument the "out" of
119 the current artifact. The out corresponds to the diagram type.
120
121 For example the inner block of
122
123 \begin{lstlisting}
124 <dc:if test="dc:contains($artifact-outs, 'longitudinal_section')">
125 <longitudinal_section>
126 <dc:call-macro name="annotations"/>
127 </longitudinal_section>
128 </dc:if>
129 \end{lstlisting}
130
131 will only be executed if called from the datacage within a
132 longitudinal\_section diagram.
133
134 In the given example another concept of the datacage configuration is
135 encountered: Macros.
136
137 Macros help to avoid duplication of parts of the document. As the datacage
138 of some diagrams should include the same type of data, the same query should
139 be executed in multiple situations.
140
141 Therefore a macro can be defined, like in
142
143 \begin{lstlisting}
144 <dc:macro name="basedata_4_heightmarks-wq">
145 <heightmarks>
146 <dc:context>
147 <dc:statement>
148 SELECT id AS prot_id,
149 description AS prot_description
150 FROM wsts WHERE kind = 4 AND river_id = ${river_id}
151 </dc:statement>
152 <dc:elements>
153 <!-- ... -->
154 </dc:macro>
155 \end{lstlisting}
156
157 and invoked from another location within the document, e.g. with
158
159 \begin{lstlisting}
160
161 <dc:call-macro name="basedata_4_heightmarks"/>
162 \end{lstlisting}
163 .
164
http://dive4elements.wald.intevation.org