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