1.1 --- a/docs/structure.html Tue Jul 19 00:20:03 2005 +0000
1.2 +++ b/docs/structure.html Tue Jul 19 12:31:03 2005 +0000
1.3 @@ -1,364 +1,87 @@
1.4 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.5 <html xmlns="http://www.w3.org/1999/xhtml">
1.6 <head>
1.7 -
1.8 -
1.9 -
1.10 -
1.11 -
1.12 -
1.13 -
1.14 -
1.15 -
1.16 -
1.17 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
1.18 -
1.19 -
1.20 -
1.21 -
1.22 -
1.23 -
1.24 -
1.25 -
1.26 -
1.27 -
1.28 -
1.29 -
1.30 -
1.31 -
1.32 -
1.33 <title>Creating Applications: Add Structure</title>
1.34 - <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.35 -
1.36 -
1.37 -
1.38 -
1.39 -
1.40 -
1.41 -
1.42 -
1.43 -
1.44 -
1.45 + <meta name="generator"
1.46 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.47 <link href="styles.css" rel="stylesheet" type="text/css" />
1.48 </head>
1.49 -
1.50 -
1.51 <body>
1.52 -
1.53 -
1.54 -
1.55 -
1.56 -
1.57 <h1>Creating Applications: Add Structure</h1>
1.58 -
1.59 -
1.60 -
1.61 -
1.62 -
1.63 -<p>During the <a href="design.html">design</a> activity, it was
1.64 -necessary to consider the structure of the information being presented.
1.65 -In proper XSLForms templates, we make such structural information
1.66 -explicit by adding special attributes to the HTML code. Consider the
1.67 -hierarchy example presented in the previous activity:</p>
1.68 -
1.69 -
1.70 -
1.71 -
1.72 -<ul>
1.73 -
1.74 -
1.75 -
1.76 -
1.77 - <li>A list of editable items, each containing...<br />
1.78 -
1.79 -
1.80 -
1.81 -
1.82 -
1.83 -
1.84 -
1.85 -
1.86 - <ul>
1.87 -
1.88 -
1.89 -
1.90 -
1.91 - <li>A list of editable items.</li>
1.92 -
1.93 -
1.94 -
1.95 -
1.96 -
1.97 -
1.98 -
1.99 -
1.100 - </ul>
1.101 -
1.102 -
1.103 -
1.104 -
1.105 - </li>
1.106 -
1.107 -
1.108 -
1.109 -
1.110 -</ul>
1.111 -
1.112 -
1.113 -<p>
1.114 -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.115 -the data described above as an XML document; something like this might
1.116 -be appropriate:
1.117 -</p>
1.118 -
1.119 -
1.120 -<pre><?xml version="1.0"?><br /><structure><br /> <item value="some value"><br /> <subitem subvalue="some other value"/><br /> </item><br /></structure></pre>
1.121 -
1.122 -
1.123 -
1.124 -
1.125 -<p>Therefore, we must seek to add the following structural information to our HTML code:</p>
1.126 -
1.127 -
1.128 -
1.129 -
1.130 +<p>Earlier, we defined the <a href="data.html">structure of the form
1.131 +data</a>, and during the <a href="design.html">template design</a>
1.132 +activity, it was
1.133 +necessary to consider this structure information and how it should be
1.134 +presented.
1.135 +In XSLForms templates, we need to explicitly connect such information
1.136 +about the structure of the data to the HTML elements representing it by
1.137 +adding special attributes to the HTML code.</p>
1.138 +<p> Consider the interesting parts of the template side by side with
1.139 +the structure information:</p>
1.140 +<pre style=""><structure> <span
1.141 + style="font-weight: bold;"><body><br /><br /></span> <item <span
1.142 + style="font-weight: bold;"><div></span><br /> <p><br /> value="some value"> Some item: <span
1.143 + style="font-weight: bold;"><input name="value" type="text" value="some value" /></span><br /> <input name="remove" type="submit" value="Remove" /><br /> </p><br /> <p><br /> Itself containing more items:<br /> </p><br /> <subitem <span
1.144 + style="font-weight: bold;"><p><br /> </span> subvalue="some other value"/> Sub-item: <span
1.145 + style="font-weight: bold;"><input name="subvalue" type="text" value="some other value" /></span><br /> <input name="remove2" type="submit" value="Remove" /><br /> <span
1.146 + style="font-weight: bold;"></p></span><br /> <p><br /> <input name="add2" type="submit" value="Add subitem" /><br /> </p><br /> </item> <span
1.147 + style="font-weight: bold;"></div></span><br /> <p><br /> <input name="add" type="submit" value="Add item" /><br /> </p><br /><br /></structure> <span
1.148 + style="font-weight: bold;"></body></span></pre>
1.149 +<p>To make such connections, we will annotate the HTML code using
1.150 +special attributes and values.</p>
1.151 <ul>
1.152 -
1.153 -
1.154 -
1.155 -
1.156 - <li>Each list item is represented by an XML element called <code>item</code>.</li>
1.157 -
1.158 -
1.159 -
1.160 -
1.161 - <li>The value of each list item is represented by an XML attribute called <code>value</code>.</li>
1.162 -
1.163 -
1.164 -
1.165 -
1.166 - <li>Items within items are represented by XML elements called <code>subitem</code>.</li>
1.167 -
1.168 -
1.169 -
1.170 -
1.171 - <li>Each value of these subitems is represented by an XML attribute called <code>subvalue</code>.</li>
1.172 -
1.173 - <li>Outside all this is a containing <code>structure</code>.</li>
1.174 -
1.175 -
1.176 -
1.177 -
1.178 </ul>
1.179 -
1.180 -
1.181 -
1.182 -
1.183 -<p>What we must do is to find a way to describe how our template will
1.184 -map onto the form data and present it as a Web page for the purpose of
1.185 -user interaction.<br />
1.186 -
1.187 -
1.188 -
1.189 -
1.190 -</p>
1.191 -
1.192 -
1.193 -
1.194 -
1.195 <h2>Annotating the Template</h2>
1.196 -
1.197 -
1.198 -
1.199 -
1.200 -<p>Taking the HTML example from before, we add special annotations to the template to produce something like this:</p>
1.201 -
1.202 -
1.203 -
1.204 -
1.205 -<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.206 -
1.207 -
1.208 -
1.209 -
1.210 -<p>The following annotations have been added:</p>
1.211 -
1.212 -
1.213 -
1.214 -
1.215 +<p>Taking the template extract from above, we add special annotations
1.216 +to produce something like this:</p>
1.217 +<pre style=""><structure> <body <span
1.218 + style="font-weight: bold;">template:element="structure"</span>><br /><br /> <item <div <span
1.219 + style="font-weight: bold;">template:element="item"</span>><br /> <p><br /> value="some value"> Some item: <input <span
1.220 + style="font-weight: bold;">template:attribute="value"</span> name="<span
1.221 + style="font-weight: bold;">{template:field-name()}</span>" type="text" value="<span
1.222 + style="font-weight: bold;">{$this-value}</span>" /><br /> <input name="remove" type="submit" value="Remove" /><br /> </p><br /> <p><br /> Itself containing more items:<br /> </p><br /> <subitem <p <span
1.223 + style="font-weight: bold;">template:element="subitem"</span>><br /> subvalue="some other value"/> Sub-item: <input <span
1.224 + style="font-weight: bold;">template:attribute="subvalue"</span> name="<span
1.225 + style="font-weight: bold;">{template:field-name()}</span>" type="text" value="<span
1.226 + style="font-weight: bold;">{$this-value}</span>" /><br /> <input name="remove2" type="submit" value="Remove" /><br /> </p><br /> <p><br /> <input name="add2" type="submit" value="Add subitem" /><br /> </p><br /> </item> </div><br /> <p><br /> <input name="add" type="submit" value="Add item" /><br /> </p><br /><br /></structure> </body></pre>
1.227 +<p style="">
1.228 +The following annotations have been added:</p>
1.229 <ul>
1.230 -
1.231 -
1.232 -
1.233 -
1.234 - <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.235 -
1.236 -
1.237 -
1.238 -
1.239 - <li>For attributes, the <code>template:attribute</code> attributes were added to some new HTML <code>span</code> elements.</li>
1.240 -
1.241 -
1.242 -
1.243 -
1.244 + <li>For elements in the structure, <code>template:element</code>
1.245 +attributes have been added to the corresponding HTML elements in the
1.246 +template.</li>
1.247 + <li>For attributes in the structure, <code>template:attribute</code>
1.248 +attributes have been added to the corresponding HTML <code>elements
1.249 +in the template.</code></li>
1.250 </ul>
1.251 -
1.252 -
1.253 -
1.254 -
1.255 -<p>In addition, some of the attributes in the original HTML code have been changed:</p>
1.256 -
1.257 -
1.258 -
1.259 -
1.260 +<p>In addition, some of the attributes in the original HTML code have
1.261 +been changed:</p>
1.262 <ul>
1.263 -
1.264 -
1.265 -
1.266 -
1.267 - <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.268 -
1.269 -
1.270 -
1.271 -
1.272 - <li>The <code>input</code> elements' <code>value</code> attributes have been redefined to use the special <code>{$this-value}</code> value.</li>
1.273 -
1.274 -
1.275 -
1.276 -
1.277 + <li>The <code>input</code> elements' <code>name</code>
1.278 +attributes have been redefined to use the special <code>{template:field-name()}</code>
1.279 +value.</li>
1.280 + <li>The <code>input</code> elements' <code>value</code>
1.281 +attributes have been redefined to use the special <code>{$this-value}</code>
1.282 +value.</li>
1.283 </ul>
1.284 -
1.285 -
1.286 -
1.287 -
1.288 <p>Whereas the first set of annotations reproduce the desired
1.289 structure, the latter modifications are really housekeeping measures to
1.290 make sure that the final output contains the correct names and values
1.291 for each of the form fields shown to the user.</p>
1.292 -<h3>The Template Namespace</h3>
1.293 -<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.294 -
1.295 -
1.296 -
1.297 -
1.298 -<div class="WebStack">
1.299 -<h3>Basic Template Annotation</h3>
1.300 -
1.301 -
1.302 -
1.303 -
1.304 -<p>The following special annotations can be used to describe XML document structures in templates:</p>
1.305 -
1.306 -
1.307 -
1.308 -
1.309 -<dl>
1.310 -
1.311 -
1.312 -
1.313 -
1.314 - <dt><code>template:element</code></dt>
1.315 -
1.316 -
1.317 -
1.318 -
1.319 - <dd>This attribute should be added to an element in the template in
1.320 -order to mark that element and its contents as mapping onto or
1.321 -representing an element in the XML document version of the
1.322 -form. In the example, the <code>div</code> element is annotated with this attribute to indicate that it maps onto the <code>item</code> element in the XML document version of the form. It is possible to specify more than one name as the value for a <code>template:element</code> attribute by separating each name with a comma; for example:<br />
1.323 -
1.324 -
1.325 -
1.326 -
1.327 -
1.328 -
1.329 -
1.330 -
1.331 - <pre><div template:element="parent,child"><br /> <p>This is a child element in the XML document version of the form.</p><br /></div></pre>
1.332 -
1.333 -
1.334 -
1.335 -
1.336 - </dd>
1.337 -
1.338 -
1.339 -
1.340 -
1.341 - <dd>The meaning of this is that the annotated element maps onto all <code>child</code> elements within all <code>parent</code>
1.342 -elements in the XML document version of the form. In other words,
1.343 -instead of having to create separate HTML elements in the template for
1.344 -each XML document element being represented, we can collapse the
1.345 -annotations into a single <code>template:element</code> attribute on a single HTML element.</dd>
1.346 -
1.347 -
1.348 -
1.349 -
1.350 - <dt><code>template:attribute</code></dt>
1.351 -
1.352 -
1.353 -
1.354 -
1.355 - <dd>This attribute should be added to an element in the template in
1.356 -order to mark that element and its contents as mapping onto or
1.357 -representing an attribute in the XML document version of the form.
1.358 -The <code>template:attribute</code> annotation exposes various
1.359 -special values which are described below - such value insert dynamic
1.360 -content from the XML document version of the form into the final output
1.361 -generated from the template.</dd>
1.362 -
1.363 -
1.364 -
1.365 -
1.366 - <dt><code>{$this-value}</code></dt>
1.367 -
1.368 -
1.369 -
1.370 -
1.371 - <dd>This special value should be used in HTML attributes where the
1.372 -value of an attribute from the XML document version of the form is
1.373 -to be included or presented in the final output. In the example,
1.374 -the <code>value</code> and <code>subvalue</code> attributes are presented in the <code>value</code> attributes of the HTML <code>input</code> elements in this way.</dd>
1.375 -
1.376 -
1.377 -
1.378 -
1.379 - <dt><code>{template:field-name()}</code></dt>
1.380 -
1.381 -
1.382 -
1.383 -
1.384 - <dd>This special value should be used in HTML attributes where the
1.385 -name of an attribute from the XML document version of the form is to be
1.386 -included or presented in the final output.</dd>
1.387 -
1.388 -
1.389 -
1.390 -
1.391 -</dl>
1.392 -
1.393 -
1.394 -
1.395 -
1.396 -<p>The <a href="reference.html">reference guide</a> provides a complete list of special values for use in template annotations.</p>
1.397 -
1.398 -
1.399 -
1.400 -
1.401 -</div>
1.402 -
1.403 -
1.404 -
1.405 -
1.406 +<h2>Completing the Template</h2>
1.407 +<p>The template in full should now look something like this:</p>
1.408 +<pre><?xml version="1.0"?><br /><html xmlns="http://www.w3.org/1999/xhtml"<br /> <span
1.409 + style="font-weight: bold;">xmlns:template="http://www.boddie.org.uk/ns/xmltools/template"</span>><br /><head><br /> <title>Example</title><br /></head><br /><body template:element="structure"><br /><form action="" method="POST"><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 /> <p><br /> <input name="add2" type="submit" value="Add subitem" /><br /> </p><br /></div><br /><p><br /> <input name="add" type="submit" value="Add item" /><br /></p><br /><br /><!-- Template text between the interesting part and the end. --><br /><br /></form><br /></body><br /></html></pre>
1.410 +<p>Note also that a namespace declaration is required for the <code>template</code>
1.411 +attributes, and it is usually best to put this declaration on the
1.412 +top-level <code>html</code> element in the template, as shown in
1.413 +the above example code.</p>
1.414 <p>Whilst the above annotations permit the template to display the data
1.415 in XML documents containing form data, the other aspects of the user
1.416 interface - the addition and removal of items and subitems - are not
1.417 -yet modelled in the template. These things will be added to the template as <a href="selectors.html">selectors</a> as part of the next activity in the development <a href="overview.html">process</a>.</p>
1.418 -
1.419 -
1.420 -
1.421 -
1.422 -
1.423 -
1.424 -
1.425 +yet fully modelled in the template. These things will be added to the
1.426 +template as <a href="selectors.html">selectors</a> as part of the
1.427 +next activity in the development <a href="overview.html">process</a>.</p>
1.428 </body>
1.429 </html>