Mercurial > dive4elements > river
comparison flys-artifacts/doc/datacage-config-manual/content.tex @ 3651:06a65baae494
merged flys-artifacts/2.9
| author | Thomas Arendsen Hein <thomas@intevation.de> |
|---|---|
| date | Fri, 28 Sep 2012 12:14:43 +0200 |
| parents | 1a79d47ed14b |
| children |
comparison
equal
deleted
inserted
replaced
| 3549:6a8f83c538e3 | 3651:06a65baae494 |
|---|---|
| 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 |