1.1 --- a/docs/structure.html Sun Jul 17 22:33:17 2005 +0000
1.2 +++ b/docs/structure.html Sun Jul 17 22:34:52 2005 +0000
1.3 @@ -5,6 +5,8 @@
1.4
1.5
1.6
1.7 +
1.8 +
1.9
1.10
1.11
1.12 @@ -14,6 +16,9 @@
1.13
1.14
1.15
1.16 +
1.17 +
1.18 +
1.19
1.20
1.21
1.22 @@ -28,6 +33,8 @@
1.23
1.24
1.25
1.26 +
1.27 +
1.28
1.29
1.30
1.31 @@ -41,11 +48,13 @@
1.32
1.33
1.34
1.35 +
1.36 <h1>Creating Applications: Add Structure</h1>
1.37
1.38
1.39
1.40
1.41 +
1.42 <p>During the <a href="design.html">design</a> activity, it was
1.43 necessary to consider the structure of the information being presented.
1.44 In proper XSLForms templates, we make such structural information
1.45 @@ -54,14 +63,18 @@
1.46
1.47
1.48
1.49 +
1.50 <ul>
1.51
1.52
1.53
1.54 +
1.55 <li>A list of editable items, each containing...<br />
1.56
1.57
1.58
1.59 +
1.60 +
1.61
1.62
1.63
1.64 @@ -69,81 +82,102 @@
1.65
1.66
1.67
1.68 +
1.69 <li>A list of editable items.</li>
1.70
1.71
1.72
1.73 +
1.74
1.75
1.76
1.77 +
1.78 </ul>
1.79
1.80
1.81
1.82 +
1.83 </li>
1.84
1.85
1.86
1.87 +
1.88 </ul>
1.89
1.90 +
1.91 <p>
1.92 Since XSLForms is all about the processing of <a href="model.html">form data as simple XML documents</a>, it becomes important to imagine how we would represent
1.93 the data described above as an XML document; something like this might
1.94 be appropriate:
1.95 </p>
1.96
1.97 +
1.98 <pre><?xml version="1.0"?><br /><structure><br /> <item value="some value"><br /> <subitem subvalue="some other value"/><br /> </item><br /></structure></pre>
1.99
1.100
1.101
1.102 +
1.103 <p>Therefore, we must seek to add the following structural information to our HTML code:</p>
1.104
1.105
1.106
1.107 +
1.108 <ul>
1.109
1.110
1.111
1.112 +
1.113 <li>Each list item is represented by an XML element called <code>item</code>.</li>
1.114
1.115
1.116
1.117 +
1.118 <li>The value of each list item is represented by an XML attribute called <code>value</code>.</li>
1.119
1.120
1.121
1.122 +
1.123 <li>Items within items are represented by XML elements called <code>subitem</code>.</li>
1.124
1.125
1.126
1.127 +
1.128 <li>Each value of these subitems is represented by an XML attribute called <code>subvalue</code>.</li>
1.129 +
1.130 <li>Outside all this is a containing <code>structure</code>.</li>
1.131
1.132
1.133
1.134 +
1.135 </ul>
1.136
1.137
1.138
1.139 +
1.140 <p>What we must do is to find a way to describe how our template will
1.141 map onto the form data and present it as a Web page for the purpose of
1.142 user interaction.<br />
1.143
1.144
1.145
1.146 +
1.147 </p>
1.148
1.149
1.150
1.151 +
1.152 <h2>Annotating the Template</h2>
1.153
1.154
1.155
1.156 +
1.157 <p>Taking the HTML example from before, we add special annotations to the template to produce something like this:</p>
1.158
1.159
1.160
1.161 -<pre><html xmlns="http://www.w3.org/1999/xhtml"<br /> xmlns:template="http://www.boddie.org.uk/ns/xmltools/template"><br /><head><br /> <title>Example</title><br /></head><br /><body template:element="structure"><br /><br /><!-- Template text between the start and the interesting part. --><br /><br /><div template:element="item"><br /> <p><br /> Some item: <input template:attribute="value" name="{template:field-name()}" type="text" value="{$this-value}" /><br /> <input name="remove" type="submit" value="Remove" /><br /> </p><br /> <p><br /> Itself containing more items:<br /> </p><br /> <p template:element="subitem"><br /> Sub-item: <input template:attribute="subvalue" name="{template:field-name()}" type="text" value="{$this-value}" /><br /> <input name="remove2" type="submit" value="Remove" /><br /> </p><br /></div><br /><br /><!-- Template text between the interesting part and the end. --><br /><br /></body><br /></html></pre>
1.162 +
1.163 +<pre><html xmlns="http://www.w3.org/1999/xhtml"<br /> <span style="font-weight: bold;">xmlns:template="http://www.boddie.org.uk/ns/xmltools/template"</span>><br /><head><br /> <title>Example</title><br /></head><br /><span style="font-weight: bold;"><body template:element="structure"></span><br /><form action="" method="POST"><br /><br /><!-- Template text between the start and the interesting part. --><br /><br /><span style="font-weight: bold;"><div template:element="item"></span><br /> <p><br /> <span style="font-weight: bold;"><span template:attribute="value"><br /></span> Some item: <span style="font-weight: bold;"><input name="{template:field-name()}" type="text" value="{$this-value}" /><br /> </span><br /></span> <input name="remove" type="submit" value="Remove" /><br /> </p><br /> <p><br /> Itself containing more items:<br /> </p><br /> <span style="font-weight: bold;"><p template:element="subitem"></span><br /> <span style="font-weight: bold;"><span template:attribute="subvalue"></span><br /> Sub-item: <span style="font-weight: bold;"><input name="{template:field-name()}" type="text" value="{$this-value}" /><br /> </span><br /></span> <input name="remove2" type="submit" value="Remove" /><br /> </p><br /></div><br /><br /><!-- Template text between the interesting part and the end. --><br /><br /></form><br /></body><br /></html></pre>
1.164 +
1.165
1.166
1.167
1.168 @@ -151,15 +185,19 @@
1.169
1.170
1.171
1.172 +
1.173 <ul>
1.174
1.175
1.176
1.177 +
1.178 <li>For elements, the <code>template:element</code> attributes were added to the HTML elements which will be replicated when presenting the final output.</li>
1.179
1.180
1.181
1.182 - <li>For attributes, the <code>template:attribute</code> attributes were added to the form <code>input</code> elements.</li>
1.183 +
1.184 + <li>For attributes, the <code>template:attribute</code> attributes were added to some new HTML <code>span</code> elements.</li>
1.185 +
1.186
1.187
1.188
1.189 @@ -167,30 +205,39 @@
1.190
1.191
1.192
1.193 +
1.194 <p>In addition, some of the attributes in the original HTML code have been changed:</p>
1.195
1.196
1.197
1.198 +
1.199 <ul>
1.200
1.201
1.202
1.203 +
1.204 <li>The <code>input</code> elements' <code>name</code> attributes have been redefined to use the special <code>{template:field-name()}</code> value.</li>
1.205
1.206
1.207
1.208 +
1.209 <li>The <code>input</code> elements' <code>value</code> attributes have been redefined to use the special <code>{$this-value}</code> value.</li>
1.210
1.211
1.212
1.213 +
1.214 </ul>
1.215
1.216
1.217
1.218 +
1.219 <p>Whereas the first set of annotations reproduce the desired
1.220 structure, the latter modifications are really housekeeping measures to
1.221 make sure that the final output contains the correct names and values
1.222 for each of the form fields shown to the user.</p>
1.223 +<h3>The Template Namespace</h3>
1.224 +<p>Note also that a namespace declaration is required for the <code>template</code> attributes, and it is usually best to put this declaration on the top-level <code>html</code> element in the template.</p>
1.225 +
1.226
1.227
1.228
1.229 @@ -199,18 +246,22 @@
1.230
1.231
1.232
1.233 +
1.234 <p>The following special annotations can be used to describe XML document structures in templates:</p>
1.235
1.236
1.237
1.238 +
1.239 <dl>
1.240
1.241
1.242
1.243 +
1.244 <dt><code>template:element</code></dt>
1.245
1.246
1.247
1.248 +
1.249 <dd>This attribute should be added to an element in the template in
1.250 order to mark that element and its contents as mapping onto or
1.251 representing an element in the XML document version of the
1.252 @@ -218,6 +269,8 @@
1.253
1.254
1.255
1.256 +
1.257 +
1.258
1.259
1.260
1.261 @@ -225,10 +278,12 @@
1.262
1.263
1.264
1.265 +
1.266 </dd>
1.267
1.268
1.269
1.270 +
1.271 <dd>The meaning of this is that the annotated element maps onto all <code>child</code> elements within all <code>parent</code>
1.272 elements in the XML document version of the form. In other words,
1.273 instead of having to create separate HTML elements in the template for
1.274 @@ -237,12 +292,14 @@
1.275
1.276
1.277
1.278 +
1.279 <dt><code>template:attribute</code></dt>
1.280
1.281
1.282
1.283 +
1.284 <dd>This attribute should be added to an element in the template in
1.285 -order to mark that element and its contents as mapping onto or
1.286 +order to mark that element and its contents as mapping onto or
1.287 representing an attribute in the XML document version of the form.
1.288 The <code>template:attribute</code> annotation exposes various
1.289 special values which are described below - such value insert dynamic
1.290 @@ -251,10 +308,12 @@
1.291
1.292
1.293
1.294 +
1.295 <dt><code>{$this-value}</code></dt>
1.296
1.297
1.298
1.299 +
1.300 <dd>This special value should be used in HTML attributes where the
1.301 value of an attribute from the XML document version of the form is
1.302 to be included or presented in the final output. In the example,
1.303 @@ -262,28 +321,34 @@
1.304
1.305
1.306
1.307 +
1.308 <dt><code>{template:field-name()}</code></dt>
1.309
1.310
1.311
1.312 +
1.313 <dd>This special value should be used in HTML attributes where the
1.314 name of an attribute from the XML document version of the form is to be
1.315 included or presented in the final output.</dd>
1.316
1.317
1.318
1.319 +
1.320 </dl>
1.321
1.322
1.323
1.324 +
1.325 <p>The <a href="reference.html">reference guide</a> provides a complete list of special values for use in template annotations.</p>
1.326
1.327
1.328
1.329 +
1.330 </div>
1.331
1.332
1.333
1.334 +
1.335 <p>Whilst the above annotations permit the template to display the data
1.336 in XML documents containing form data, the other aspects of the user
1.337 interface - the addition and removal of items and subitems - are not
1.338 @@ -294,5 +359,6 @@
1.339
1.340
1.341
1.342 +
1.343 </body>
1.344 </html>