paulb@118 | 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
paulb@118 | 2 | <html xmlns="http://www.w3.org/1999/xhtml"> |
paulb@118 | 3 | <head> |
paulb@118 | 4 | |
paulb@119 | 5 | |
paulb@119 | 6 | |
paulb@119 | 7 | |
paulb@121 | 8 | |
paulb@121 | 9 | |
paulb@119 | 10 | |
paulb@119 | 11 | |
paulb@119 | 12 | |
paulb@118 | 13 | |
paulb@118 | 14 | <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> |
paulb@118 | 15 | |
paulb@119 | 16 | |
paulb@119 | 17 | |
paulb@119 | 18 | |
paulb@121 | 19 | |
paulb@121 | 20 | |
paulb@121 | 21 | |
paulb@119 | 22 | |
paulb@119 | 23 | |
paulb@119 | 24 | |
paulb@119 | 25 | |
paulb@119 | 26 | |
paulb@119 | 27 | |
paulb@118 | 28 | |
paulb@118 | 29 | |
paulb@118 | 30 | <title>Creating Applications: Add Structure</title> |
paulb@118 | 31 | <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> |
paulb@118 | 32 | |
paulb@119 | 33 | |
paulb@119 | 34 | |
paulb@119 | 35 | |
paulb@121 | 36 | |
paulb@121 | 37 | |
paulb@119 | 38 | |
paulb@119 | 39 | |
paulb@119 | 40 | |
paulb@118 | 41 | |
paulb@118 | 42 | <link href="styles.css" rel="stylesheet" type="text/css" /> |
paulb@118 | 43 | </head> |
paulb@118 | 44 | |
paulb@118 | 45 | |
paulb@118 | 46 | <body> |
paulb@118 | 47 | |
paulb@119 | 48 | |
paulb@119 | 49 | |
paulb@119 | 50 | |
paulb@121 | 51 | |
paulb@118 | 52 | <h1>Creating Applications: Add Structure</h1> |
paulb@118 | 53 | |
paulb@119 | 54 | |
paulb@119 | 55 | |
paulb@119 | 56 | |
paulb@121 | 57 | |
paulb@118 | 58 | <p>During the <a href="design.html">design</a> activity, it was |
paulb@118 | 59 | necessary to consider the structure of the information being presented. |
paulb@118 | 60 | In proper XSLForms templates, we make such structural information |
paulb@118 | 61 | explicit by adding special attributes to the HTML code. Consider the |
paulb@118 | 62 | hierarchy example presented in the previous activity:</p> |
paulb@119 | 63 | |
paulb@119 | 64 | |
paulb@119 | 65 | |
paulb@121 | 66 | |
paulb@118 | 67 | <ul> |
paulb@119 | 68 | |
paulb@119 | 69 | |
paulb@119 | 70 | |
paulb@121 | 71 | |
paulb@119 | 72 | <li>A list of editable items, each containing...<br /> |
paulb@119 | 73 | |
paulb@119 | 74 | |
paulb@119 | 75 | |
paulb@121 | 76 | |
paulb@121 | 77 | |
paulb@119 | 78 | |
paulb@119 | 79 | |
paulb@119 | 80 | |
paulb@119 | 81 | <ul> |
paulb@119 | 82 | |
paulb@119 | 83 | |
paulb@119 | 84 | |
paulb@121 | 85 | |
paulb@119 | 86 | <li>A list of editable items.</li> |
paulb@119 | 87 | |
paulb@119 | 88 | |
paulb@119 | 89 | |
paulb@121 | 90 | |
paulb@119 | 91 | |
paulb@119 | 92 | |
paulb@119 | 93 | |
paulb@121 | 94 | |
paulb@119 | 95 | </ul> |
paulb@119 | 96 | |
paulb@119 | 97 | |
paulb@119 | 98 | |
paulb@121 | 99 | |
paulb@119 | 100 | </li> |
paulb@119 | 101 | |
paulb@119 | 102 | |
paulb@119 | 103 | |
paulb@121 | 104 | |
paulb@118 | 105 | </ul> |
paulb@119 | 106 | |
paulb@121 | 107 | |
paulb@119 | 108 | <p> |
paulb@119 | 109 | 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 |
paulb@118 | 110 | the data described above as an XML document; something like this might |
paulb@119 | 111 | be appropriate: |
paulb@119 | 112 | </p> |
paulb@119 | 113 | |
paulb@121 | 114 | |
paulb@119 | 115 | <pre><?xml version="1.0"?><br /><structure><br /> <item value="some value"><br /> <subitem subvalue="some other value"/><br /> </item><br /></structure></pre> |
paulb@119 | 116 | |
paulb@119 | 117 | |
paulb@119 | 118 | |
paulb@121 | 119 | |
paulb@118 | 120 | <p>Therefore, we must seek to add the following structural information to our HTML code:</p> |
paulb@119 | 121 | |
paulb@119 | 122 | |
paulb@119 | 123 | |
paulb@121 | 124 | |
paulb@118 | 125 | <ul> |
paulb@119 | 126 | |
paulb@119 | 127 | |
paulb@119 | 128 | |
paulb@121 | 129 | |
paulb@119 | 130 | <li>Each list item is represented by an XML element called <code>item</code>.</li> |
paulb@119 | 131 | |
paulb@119 | 132 | |
paulb@119 | 133 | |
paulb@121 | 134 | |
paulb@119 | 135 | <li>The value of each list item is represented by an XML attribute called <code>value</code>.</li> |
paulb@119 | 136 | |
paulb@119 | 137 | |
paulb@119 | 138 | |
paulb@121 | 139 | |
paulb@119 | 140 | <li>Items within items are represented by XML elements called <code>subitem</code>.</li> |
paulb@119 | 141 | |
paulb@119 | 142 | |
paulb@119 | 143 | |
paulb@121 | 144 | |
paulb@119 | 145 | <li>Each value of these subitems is represented by an XML attribute called <code>subvalue</code>.</li> |
paulb@121 | 146 | |
paulb@119 | 147 | <li>Outside all this is a containing <code>structure</code>.</li> |
paulb@119 | 148 | |
paulb@119 | 149 | |
paulb@119 | 150 | |
paulb@121 | 151 | |
paulb@118 | 152 | </ul> |
paulb@119 | 153 | |
paulb@119 | 154 | |
paulb@119 | 155 | |
paulb@121 | 156 | |
paulb@118 | 157 | <p>What we must do is to find a way to describe how our template will |
paulb@118 | 158 | map onto the form data and present it as a Web page for the purpose of |
paulb@118 | 159 | user interaction.<br /> |
paulb@119 | 160 | |
paulb@119 | 161 | |
paulb@119 | 162 | |
paulb@121 | 163 | |
paulb@118 | 164 | </p> |
paulb@119 | 165 | |
paulb@119 | 166 | |
paulb@119 | 167 | |
paulb@121 | 168 | |
paulb@118 | 169 | <h2>Annotating the Template</h2> |
paulb@119 | 170 | |
paulb@119 | 171 | |
paulb@119 | 172 | |
paulb@121 | 173 | |
paulb@118 | 174 | <p>Taking the HTML example from before, we add special annotations to the template to produce something like this:</p> |
paulb@119 | 175 | |
paulb@119 | 176 | |
paulb@119 | 177 | |
paulb@121 | 178 | |
paulb@121 | 179 | <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> |
paulb@121 | 180 | |
paulb@119 | 181 | |
paulb@119 | 182 | |
paulb@119 | 183 | |
paulb@118 | 184 | <p>The following annotations have been added:</p> |
paulb@119 | 185 | |
paulb@119 | 186 | |
paulb@119 | 187 | |
paulb@121 | 188 | |
paulb@118 | 189 | <ul> |
paulb@119 | 190 | |
paulb@119 | 191 | |
paulb@119 | 192 | |
paulb@121 | 193 | |
paulb@118 | 194 | <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> |
paulb@119 | 195 | |
paulb@119 | 196 | |
paulb@119 | 197 | |
paulb@121 | 198 | |
paulb@121 | 199 | <li>For attributes, the <code>template:attribute</code> attributes were added to some new HTML <code>span</code> elements.</li> |
paulb@121 | 200 | |
paulb@119 | 201 | |
paulb@119 | 202 | |
paulb@119 | 203 | |
paulb@118 | 204 | </ul> |
paulb@119 | 205 | |
paulb@119 | 206 | |
paulb@119 | 207 | |
paulb@121 | 208 | |
paulb@118 | 209 | <p>In addition, some of the attributes in the original HTML code have been changed:</p> |
paulb@119 | 210 | |
paulb@119 | 211 | |
paulb@119 | 212 | |
paulb@121 | 213 | |
paulb@118 | 214 | <ul> |
paulb@119 | 215 | |
paulb@119 | 216 | |
paulb@119 | 217 | |
paulb@121 | 218 | |
paulb@118 | 219 | <li>The <code>input</code> elements' <code>name</code> attributes have been redefined to use the special <code>{template:field-name()}</code> value.</li> |
paulb@119 | 220 | |
paulb@119 | 221 | |
paulb@119 | 222 | |
paulb@121 | 223 | |
paulb@118 | 224 | <li>The <code>input</code> elements' <code>value</code> attributes have been redefined to use the special <code>{$this-value}</code> value.</li> |
paulb@119 | 225 | |
paulb@119 | 226 | |
paulb@119 | 227 | |
paulb@121 | 228 | |
paulb@118 | 229 | </ul> |
paulb@119 | 230 | |
paulb@119 | 231 | |
paulb@119 | 232 | |
paulb@121 | 233 | |
paulb@118 | 234 | <p>Whereas the first set of annotations reproduce the desired |
paulb@118 | 235 | structure, the latter modifications are really housekeeping measures to |
paulb@118 | 236 | make sure that the final output contains the correct names and values |
paulb@118 | 237 | for each of the form fields shown to the user.</p> |
paulb@121 | 238 | <h3>The Template Namespace</h3> |
paulb@121 | 239 | <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> |
paulb@121 | 240 | |
paulb@119 | 241 | |
paulb@119 | 242 | |
paulb@119 | 243 | |
paulb@118 | 244 | <div class="WebStack"> |
paulb@118 | 245 | <h3>Basic Template Annotation</h3> |
paulb@119 | 246 | |
paulb@119 | 247 | |
paulb@119 | 248 | |
paulb@121 | 249 | |
paulb@118 | 250 | <p>The following special annotations can be used to describe XML document structures in templates:</p> |
paulb@119 | 251 | |
paulb@119 | 252 | |
paulb@119 | 253 | |
paulb@121 | 254 | |
paulb@118 | 255 | <dl> |
paulb@119 | 256 | |
paulb@119 | 257 | |
paulb@119 | 258 | |
paulb@121 | 259 | |
paulb@118 | 260 | <dt><code>template:element</code></dt> |
paulb@119 | 261 | |
paulb@119 | 262 | |
paulb@119 | 263 | |
paulb@121 | 264 | |
paulb@118 | 265 | <dd>This attribute should be added to an element in the template in |
paulb@118 | 266 | order to mark that element and its contents as mapping onto or |
paulb@118 | 267 | representing an element in the XML document version of the |
paulb@118 | 268 | 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 /> |
paulb@119 | 269 | |
paulb@119 | 270 | |
paulb@119 | 271 | |
paulb@121 | 272 | |
paulb@121 | 273 | |
paulb@119 | 274 | |
paulb@119 | 275 | |
paulb@119 | 276 | |
paulb@118 | 277 | <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> |
paulb@119 | 278 | |
paulb@119 | 279 | |
paulb@119 | 280 | |
paulb@121 | 281 | |
paulb@118 | 282 | </dd> |
paulb@119 | 283 | |
paulb@119 | 284 | |
paulb@119 | 285 | |
paulb@121 | 286 | |
paulb@118 | 287 | <dd>The meaning of this is that the annotated element maps onto all <code>child</code> elements within all <code>parent</code> |
paulb@118 | 288 | elements in the XML document version of the form. In other words, |
paulb@118 | 289 | instead of having to create separate HTML elements in the template for |
paulb@118 | 290 | each XML document element being represented, we can collapse the |
paulb@118 | 291 | annotations into a single <code>template:element</code> attribute on a single HTML element.</dd> |
paulb@119 | 292 | |
paulb@119 | 293 | |
paulb@119 | 294 | |
paulb@121 | 295 | |
paulb@118 | 296 | <dt><code>template:attribute</code></dt> |
paulb@119 | 297 | |
paulb@119 | 298 | |
paulb@119 | 299 | |
paulb@121 | 300 | |
paulb@118 | 301 | <dd>This attribute should be added to an element in the template in |
paulb@121 | 302 | order to mark that element and its contents as mapping onto or |
paulb@118 | 303 | representing an attribute in the XML document version of the form. |
paulb@118 | 304 | The <code>template:attribute</code> annotation exposes various |
paulb@118 | 305 | special values which are described below - such value insert dynamic |
paulb@118 | 306 | content from the XML document version of the form into the final output |
paulb@118 | 307 | generated from the template.</dd> |
paulb@119 | 308 | |
paulb@119 | 309 | |
paulb@119 | 310 | |
paulb@121 | 311 | |
paulb@118 | 312 | <dt><code>{$this-value}</code></dt> |
paulb@119 | 313 | |
paulb@119 | 314 | |
paulb@119 | 315 | |
paulb@121 | 316 | |
paulb@118 | 317 | <dd>This special value should be used in HTML attributes where the |
paulb@118 | 318 | value of an attribute from the XML document version of the form is |
paulb@118 | 319 | to be included or presented in the final output. In the example, |
paulb@118 | 320 | 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> |
paulb@119 | 321 | |
paulb@119 | 322 | |
paulb@119 | 323 | |
paulb@121 | 324 | |
paulb@118 | 325 | <dt><code>{template:field-name()}</code></dt> |
paulb@119 | 326 | |
paulb@119 | 327 | |
paulb@119 | 328 | |
paulb@121 | 329 | |
paulb@118 | 330 | <dd>This special value should be used in HTML attributes where the |
paulb@118 | 331 | name of an attribute from the XML document version of the form is to be |
paulb@118 | 332 | included or presented in the final output.</dd> |
paulb@119 | 333 | |
paulb@119 | 334 | |
paulb@119 | 335 | |
paulb@121 | 336 | |
paulb@118 | 337 | </dl> |
paulb@119 | 338 | |
paulb@119 | 339 | |
paulb@119 | 340 | |
paulb@121 | 341 | |
paulb@118 | 342 | <p>The <a href="reference.html">reference guide</a> provides a complete list of special values for use in template annotations.</p> |
paulb@119 | 343 | |
paulb@119 | 344 | |
paulb@119 | 345 | |
paulb@121 | 346 | |
paulb@118 | 347 | </div> |
paulb@119 | 348 | |
paulb@119 | 349 | |
paulb@119 | 350 | |
paulb@121 | 351 | |
paulb@118 | 352 | <p>Whilst the above annotations permit the template to display the data |
paulb@118 | 353 | in XML documents containing form data, the other aspects of the user |
paulb@118 | 354 | interface - the addition and removal of items and subitems - are not |
paulb@119 | 355 | 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> |
paulb@119 | 356 | |
paulb@119 | 357 | |
paulb@119 | 358 | |
paulb@119 | 359 | |
paulb@119 | 360 | |
paulb@118 | 361 | |
paulb@121 | 362 | |
paulb@118 | 363 | </body> |
paulb@118 | 364 | </html> |