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