Mercurial > dive4elements > river

comparison flys-artifacts/doc/datacage.txt @ 3651:06a65baae494

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