1 <?xml version="1.0" encoding="iso-8859-1"?> 2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3 <html xmlns="http://www.w3.org/1999/xhtml"><head> 4 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /><title>Template Attribute Reference</title> 5 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 6 <body> 7 8 <h1>Template Attribute Reference</h1> 9 <p>This document presents each of the attributes used in 10 templates to annotate the structure of the XML documents being 11 presented and to modify the final output of the presented document.</p> 12 13 <h2>Basic Annotations</h2> 14 15 <p>The annotation attributes in this section are the most basic of those available. Apart from <code>template:element</code> and <code>template:i18n</code>, it is usually preferable to use the annotations listed in the "Convenience Annotations" section below.</p> 16 17 <h3><a name="element"></a>template:element</h3> 18 19 <p>This 20 attribute associates the template element on which it is used with an 21 element from the XML document being presented. Matching elements are 22 found from the current position (or context), where the position 23 is updated upon entering a template element with a <code>template:element</code> or <code>template:attribute</code> annotation.</p> 24 25 <p>Example:</p> 26 27 <pre><p template:element="item"><br /> For each item element found, this section is produced.<br /> <span template:element="subitem"><br /> For each subitem element found within an item element, this is produced.<br /> </span><br /> <span template:element="other"><br /> This is produced for each other element found within an item element.<br /> </span><br /></p></pre> 28 29 <p>Example:</p> 30 31 <pre><p template:element="first,second,third"><br /> For each third element found, this section is produced.<br /></p></pre> 32 33 <p>Syntax:</p> 34 35 <pre>element-name1[,element-name2[,...]]</pre> 36 37 <p>Related attributes:</p> 38 39 <ul><li><code>template:init</code></li></ul> 40 41 <h3><a name="attribute"></a>template:attribute</h3> 42 43 <p>This attribute associates the template element on which it is used with an attribute in the XML document being presented.</p> 44 45 <p>Example:</p> 46 47 <pre><p template:element="item"><br /> <span template:attribute="value"><br /> This section is associated with the value attribute of the item element.<br /> To be really useful, we should also use other annotations to produce the value of the attribute.<br /> </span><br /></p></pre> 48 49 <p>Syntax:</p> 50 51 <pre>attribute-name</pre> 52 53 <p>Related attributes:</p> 54 55 <ul><li><code>template:value</code></li><li><code>template:attribute-field</code></li><li><code>template:attribute-button</code></li><li><code>template:attribute-area</code></li><li><code>template:attribute-list-button</code></li></ul> 56 57 <h3><a name="value"></a>template:value</h3> 58 59 <p>This attribute produces, in the final output, the value of part of the XML document being presented.</p> 60 61 <p>Example:</p> 62 63 <pre><p template:element="item"><br /> <span template:attribute="value" template:value="$this-value"><br /> This text will be replaced by the value of the attribute, but the span template element will remain.<br /> </span><br /></p></pre> 64 65 <p>Example:</p> 66 67 <pre><p template:element="item"><br /> <span template:attribute="value" template:value="$this-value" template:effect="replace"><br /> This text and its enclosing span element will be replaced by the value of the attribute.<br /> </span><br /></p></pre> 68 69 <p>Syntax:</p> 70 71 <pre>XPath-expression</pre> 72 73 <p>Here, the underlying XPath mechanisms are exposed, but a number of useful shortcuts are available:</p> 74 75 <ul><li><code>$this-value</code> produces the value of the current position (or context) in the XML document being presented.</li><li><code>template:this-attribute()</code> produces a reference to the current attribute (or context).</li></ul>Other XPath expressions can be used to navigate from the current position to other nodes in the XML document. 76 77 <p>Related attributes:</p> 78 79 <ul><li><code>template:effect</code></li></ul> 80 81 <h3><a name="effect"></a>template:effect</h3> 82 83 <p>This attribute modifies the effect of a <code>template:value</code> annotation.</p> 84 85 <p>Example:</p> 86 87 <p>(See above.)</p> 88 89 <p>Syntax:</p> 90 91 <pre><span style="font-weight: bold;">insert</span>|<span style="font-weight: bold;">replace</span></pre> 92 93 <p>Related attributes:</p> 94 95 <ul><li><code>template:effect</code></li><li><code>template:attribute-area</code></li></ul> 96 97 <h3><a name="if"></a>template:if</h3> 98 99 <p>This 100 attribute permits the inclusion of a section of the template document 101 according to a test performed on the XML document being presented.</p> 102 103 <p>Example:</p> 104 105 <pre><p template:if="@value = 'true'"><br /> If the value attribute is set to the string value 'true', include this section.<br /></p></pre> 106 107 <p>Syntax:</p> 108 109 <pre>XPath-expression</pre> 110 111 <p>Here, 112 the underlying XPath mechanisms are exposed, and any XPath expression 113 which tests aspects of the XML document can be written.</p> 114 115 <h3><a name="i18n"></a>template:i18n</h3> 116 117 <p>This 118 attribute is used to translate the textual contents of an element to 119 another language where additional parameters specifying the language 120 and the whereabouts of the translations have been provided to the 121 stylesheet in the output generation process.</p> 122 123 <p>Example:</p> 124 125 <pre><span template:i18n="-">Hello</span></pre> 126 127 <p>In this example, the contents of the <code>span</code> element would be replaced with an appropriate translation for the text <code>Hello</code><span></span>.</p> 128 129 <p>Example:</p> 130 131 <pre><span template:i18n="hello">Hello</span></pre> 132 133 <p>In this example, the contents of the <code>span</code> element would be replaced with an appropriate translation using the token <code>hello</code><span></span> as a key in the translation dictionary.</p> 134 135 <p>Example:</p> 136 137 <pre><span template:i18n="{$this-value}">Hello</span></pre> 138 139 <p>In this example, the value of the special template variable <code>$this-value</code> is used as a key in the translation dictionary.</p> 140 141 <p>Syntax:</p> 142 143 <pre><span style="font-weight: bold;">-</span>|<span style="font-weight: bold;">{</span>expression<span style="font-weight: bold;">}</span>|token</pre> 144 145 <p>See the <a href="internationalisation.html">"Internationalisation"</a> document for more information on this attribute.</p> 146 147 <h3><a name="i18n"></a>template:select</h3> 148 149 <p>This attribute is used to select sections of the XML document being presented 150 which are potentially different from the current element implied by the 151 structure communicated in the template. 152 </p> 153 154 <p>Example:</p> 155 156 <pre> 157 <select template:attribute-field="destination"> 158 <option template:select="../question" template:value="position()" value="{position()}"></option> 159 </select> 160 </pre> 161 162 <p>In this example, the <code>option</code> element is replicated for each 163 <code>question</code> element appearing below the parent element in the XML 164 document being presented. Since a list of results is traversed as a result, the 165 position of each <code>question</code> element can be obtained and used in the 166 resulting output. 167 </p> 168 169 <p>Syntax:</p> 170 171 <pre>XPath-expression</pre> 172 173 <p>The specified expression is evaluated in the context of the current element.</p> 174 175 <h3><a name="sort"></a>template:sort</h3> 176 177 <p>This attribute imposes a particular ordering on elements retrieved from the 178 XML document being presented based on the expression provided as the value of 179 the attribute. Such an ordering directive only has an effect on sections of the 180 template where a <code>template:element</code> or element traversing annotation 181 (such as a multiple-choice annotation) is in use.</p> 182 183 <p>Example:</p> 184 185 <pre> 186 <select template:multiple-choice-field="type,value" name="..."> 187 <option template:multiple-choice-value="type-enum,value,selected,template:i18n(text())" 188 template:sort="template:i18n(text())" value="..." /> 189 </select> 190 </pre> 191 192 <p>In this example, the choices will each have a <a href="internationalisation.html">translated</a> 193 label, but it would be desirable to sort these choices according to such labels, 194 instead of sorting them by some other criteria (such as the order in which they 195 are retrieved from a database or the English language order of the labels). 196 Thus, the <code>template:sort</code> annotation is used on the <code>option</code> 197 element, which will be replicated several times to provide all the values, such 198 that the outcome of this replication satisfies the ordering stated by the supplied 199 XPath expression <code>template:i18n(text())</code> evaluated in the context of 200 each of the elements. In other words, the elements will be generated such that 201 their labels are ordered alphabetically.</p> 202 203 <p>Syntax:</p> 204 205 <pre>XPath-expression</pre> 206 207 <p>Related attributes:</p> 208 209 <ul><li><code>template:element</code></li> 210 <li><code>template:multiple-choice-value</code></li> 211 <li><code>template:multiple-choice-list-value</code></li> 212 <li><code>template:attribute-list-button</code></li> 213 </ul> 214 215 <h2>Initialisation Annotations</h2> 216 217 <p>The annotation attributes in this section control the initialisation of documents where this is done by the XSLForms toolkit.</p> 218 219 <h3><a name="init"></a>template:init</h3> 220 221 <p>This attribute controls the creation of elements in the initialisation process and is used together with <code>template:element</code>. For each element name listed in a <code>template:element</code> annotation, the corresponding value in a <code>template:init</code> annotation states whether or how such elements are to be initialised.</p> 222 223 <p>Example:</p> 224 225 <pre><p template:element="item" template:init="no"><br /> Such item elements will not be created automatically when the document is initialised.<br /></p></pre> 226 227 <p>Example:</p> 228 229 <pre><p template:element="first,second,third" template:init="yes,yes,no"><br /> The first and second elements will be created automatically when the document is initialised.<br /> No third elements will be created automatically when the document is initialised.<br /></p></pre> 230 231 <p>Syntax:</p> 232 233 <pre><span style="font-weight: bold;">yes</span>|<span style="font-weight: bold;">no</span>|<span style="font-weight: bold;">auto</span>[,<span style="font-weight: bold;">yes</span>|<span style="font-weight: bold;">no</span>|<span style="font-weight: bold;">auto</span>[,...]]</pre> 234 235 <p>Here, <code>yes</code> means that an element will be created automatically, <code>no</code> means that an element will not be created automatically (relying on the existence of such elements from before), and <code>auto</code> 236 means that the initialisation process will attempt to guess whether an 237 element should be created automatically (by looking for selectors which 238 use the element's name and only creating elements where no such 239 selectors could be found). Where no values are provided, <code>auto</code> is assumed.</p> 240 241 <p>Related attributes:</p> 242 243 <ul><li><code>template:element</code></li></ul> 244 245 <h2>Convenience Annotations</h2> 246 247 <p>The 248 annotation attributes in this section provide more convenient ways of 249 presenting the XML document information in the final output.</p> 250 251 <h3><a name="attribute-field"></a>template:attribute-field</h3> 252 253 <p>This 254 attribute associates the template element on which it is used with an 255 attribute from the XML document, whilst providing certain other 256 attributes in the final output:</p> 257 258 <ul><li>The <code>name</code> attribute is used to identify the location of the attribute in the XML document being presented.</li><li>The <code>value</code> attribute is used to present the value of the attribute from the XML document.</li></ul> 259 260 <p>Example:</p> 261 262 <pre><input template:attribute-field="name" name="..." value="..." type="text"/></pre> 263 264 <p>This would be output as follows:</p> 265 266 <pre><input name="path-to-name" value="value-of-name" type="text"/></pre> 267 268 <p>...where <code>path-to-name</code> and <code>value-of-name</code> would be replaced with the appropriate computed values.</p> 269 270 <p>Syntax:</p> 271 272 <pre>attribute-name</pre> 273 274 <p>Related attributes:</p> 275 276 <ul><li><code>template:attribute-area</code></li><li><code>template:attribute-button</code></li></ul> 277 278 <p>Implementing attributes:</p> 279 280 <ul><li><code>template:attribute</code></li></ul> 281 282 <h3><a name="attribute-area"></a>template:attribute-area</h3> 283 284 <p>This 285 attribute associates the template element on which it is used with an 286 attribute from the XML document being presented, much in the way 287 that <code>template:attribute-field</code> does. However, the 288 attribute value is not inserted into an attribute in the final output; 289 instead it is inserted into the output in a different way according to 290 additional information specified in the annotation.</p> 291 292 <p>Example:</p> 293 294 <pre><textarea template:attribute-area="name" name="..." cols="40" rows="5"><br /> This text will be replaced by the value of the name attribute from the document being presented.<br /> The textarea element will enclose the attribute value in the final output.<br /></textarea></pre> 295 296 <p>Example:</p> 297 298 <pre><p><br /> The name is:<br /> <span template:attribute-area="name,replace"><br /> This text will be replaced in the final output, and the span element will not be reproduced.<br /> </span><br /></p></pre> 299 300 <p>Syntax:</p> 301 302 <pre>attribute-name[,<span style="font-weight: bold;">insert</span>|<span style="font-weight: bold;">replace</span>]</pre> 303 304 <p>By default, the value of <code>attribute-name</code> is inserted within the template element on which the annotation appears, and this is equivalent to specifying <code>insert</code>. If <code>replace</code> is specified, the template element is entirely replaced by the value of <code>attribute-name</code>.</p> 305 306 <p>Related attributes:</p> 307 308 <ul><li><code>template:attribute-field</code></li></ul> 309 310 <p>Implementing attributes:</p> 311 312 <ul><li><code>template:attribute</code></li></ul> 313 314 <h3><a name="attribute-button"></a>template:attribute-button</h3> 315 316 <p>This attribute associates the template element on which it is used 317 with an attribute from the XML document, whilst providing certain other 318 attributes in the final output, much like <code>template:attribute-field</code> does, but with features which make the presentation of buttons and related user interface controls much simpler:</p> 319 320 <ul><li>The <code>name</code> attribute is used to identify the location of the attribute in the XML document being presented.</li><li>The <code>value</code> attribute is used to present a specified value associated with the button being activated.</li><li>An additional named attribute is used to indicate whether the button was activated or set.</li></ul> 321 322 <p>Example:</p> 323 324 <pre><input template:attribute-button="question-type,text,checked" name="..." value="..." type="radio"/></pre> 325 326 <p>This would produce a "radio" button like the following:</p> 327 328 <pre><input name="path-to-question-type" value="text" type="radio"/></pre> 329 330 <p>If the value of <code>question-type</code> was set to text, output like the following would be produced:</p> 331 332 <pre><input name="path-to-question-type" value="text" type="radio" checked="checked"/></pre> 333 334 <p>In an XHTML document, this would cause the "radio" button to appear selected or activated.</p> 335 336 <p>Syntax:</p> 337 338 <pre>attribute-name,attribute-value,attribute-to-create-when-set</pre> 339 340 <p>Related attributes:</p> 341 342 <ul><li><code>template:attribute-field</code></li><li><code>template:attribute-list-button</code></li></ul> 343 344 <p>Implementing attributes:</p> 345 346 <ul><li><code>template:attribute</code></li><li><code>template:expr</code></li><li><code>template:expr-attr</code></li></ul> 347 348 <h3><a name="selector-field"></a>template:selector-field</h3> 349 350 <p>This 351 attribute permits the definition of references to the parts of the XML 352 document being presented which are associated with the template 353 elements in which it is used. When used in certain HTML form-related 354 elements, it becomes possible to receive and obtain such references 355 from the XSLForms toolkit and to then access the selected parts of the 356 original document.</p> 357 358 <p>Example:</p> 359 360 <pre><p template:element="item"><br /> <input template:selector-field="remove" name="..." value="Remove this item" type="submit"/><br /></p></pre> 361 362 <p>Example:</p> 363 364 <pre><p template:element="item"><br /> An item...<br /></p><br /><input template:selector-field="add,item" name="..." value="Add item" type="submit"/></pre> 365 366 <p>Syntax:</p> 367 368 <pre>selector-name[,element-name]</pre> 369 370 <p>The 371 optional element name can be used to associate the selector with other 372 elements; when this is done, the initialisation of the XML document 373 will be affected such that the named element will not be automatically 374 created in the initialisation process, since the presence of the 375 selector implies that such elements can be added and removed in the 376 application user interface.</p> 377 378 <p>Related attributes:</p> 379 380 <ul><li><code>template:element</code></li></ul> 381 382 <h2>Multiple-choice Annotations</h2> 383 384 <p>The annotation attributes in this section provide ways of presenting enumerations and selections of values.</p> 385 386 <h3><a name="multiple-choice-field"></a>template:multiple-choice-field</h3> 387 388 <p>This 389 attribute associates the template element on which it is used with an 390 attribute in the XML document being presented whose value is to be 391 chosen from a list of possibilities. The list itself is represented by 392 a list of elements, each having an attribute with a distinct 393 value; such information is added in the initialisation of the 394 document before it is presented, since it is not part of the 395 "essential" information in the document.</p> 396 397 <p>Example:</p> 398 399 <pre><select template:multiple-choice-field="base-system,value" name="..."><br /> ...<br /></select></pre> 400 401 <p>Example:</p> 402 403 <pre><select template:multiple-choice-field="-,question-type" name="..."><br /> ...<br /></select></pre> 404 405 <p>See below for an example combining this attribute with the <code>template:multiple-choice-value</code> attribute.</p> 406 407 <p>Syntax:</p> 408 409 <pre>element-name|<span style="font-weight: bold;">-</span>,attribute-name[,<span style="font-weight: bold;">new</span>|,<span style="font-weight: bold;">new</span>,<span style="font-weight: bold;">dynamic</span>|,,<span style="font-weight: bold;">dynamic</span>]</pre> 410 411 <p>Where the special value <code>-</code> 412 is given as the element name, the context element is chosen as the 413 element in the XML document being presented whose attribute is 414 involved. Where the optional parameter <code>new</code> is given, the attribute is assumed not to already exist on the element. Where the optional parameter <code>dynamic</code> is given, the source of the multiple-choice values is considered to be found dynamically rather than from another document.</p> 415 416 <p>Related attributes:</p> 417 418 <ul><li><code>template:multiple-choice-value</code></li><li><code>template:multiple-choice-list-field</code></li></ul> 419 420 <p>Implementing attributes:</p> 421 422 <ul><li><code>template:element</code></li><li><code>template:attribute</code></li></ul> 423 424 <h3><a name="multiple-choice-value"></a>template:multiple-choice-value</h3> 425 426 <p>This 427 attribute associates the template element on which it is used with an 428 element in the XML document being presented whose purpose is to hold 429 one of a list of selectable values (as described above).</p> 430 431 <p>Example:</p> 432 433 <pre><select template:multiple-choice-field="base-system,value" name="..."><br /> <option template:multiple-choice-value="base-system-enum,value,selected" value="..."/><br /></select></pre> 434 435 <p>This presents the following document fragment:</p> 436 437 <pre><base-system value="c"><br /> <base-system-enum value="a"/><br /> <base-system-enum value="b"/><br /> <base-system-enum value="c"/><br /></base-system></pre> 438 439 <p>The output from the combination of the above would be as follows:</p> 440 441 <pre><select name="path-to-base-system"><br /> <option value="a">a</option><br /> <option value="b">b</option><br /> <option value="c" selected="selected">c</option><br /></select></pre> 442 443 <h4>Values and Labels</h4> 444 445 <p>Labels different from the actual values employed can be specified using an extra parameter in the annotation:</p> 446 447 <pre><select template:multiple-choice-field="base-system,value" name="..."><br /> <option template:multiple-choice-value="base-system-enum,value,selected,text()" value="..."/><br /></select></pre> 448 449 <p>This 450 additional parameter is an XPath expression whose context is the 451 current value-bearing element. The above example selects the text from 452 inside each <code>base-system-enum</code> element in the modified document fragment presented below.</p> 453 454 <p>A modified document fragment providing the labels can be written as follows:</p> 455 456 <pre><base-system value="c"><br /> <base-system-enum value="a">A</base-system-enum><br /> <base-system-enum value="b">B</base-system-enum><br /> <base-system-enum value="c">C</base-system-enum><br /></base-system></pre> 457 458 <p>The output from the modified combination would be as follows:</p> 459 460 <pre><select name="path-to-base-system"><br /> <option value="a">A</option><br /> <option value="b">B</option><br /> <option value="c" selected="selected">C</option><br /></select></pre> 461 462 <p>Syntax:</p> 463 464 <pre>list-element-name,list-attribute-name,attribute-to-create-when-selected[,content-expression]</pre> 465 466 <p>Related attributes:</p> 467 468 <ul><li><code>template:multiple-choice-field</code></li><li><code>template:multiple-choice-list-value</code></li></ul> 469 470 <p>Implementing attributes:</p> 471 472 <ul><li><code>template:element</code></li><li><code>template:expr</code></li><li><code>template:expr-attr</code></li><li><code>template:value</code></li></ul> 473 474 <h3><a name="multiple-choice-list-field"></a>template:multiple-choice-list-field</h3> 475 476 <p>This attribute is similar to <code>template:multiple-choice-field</code> 477 except that it associates the template element on which it is used with 478 an element in the XML document being presented containing a list 479 of elements whose values have been selected. This list of selected 480 elements is expanded before presentation to include elements whose 481 values have not been selected. Consequently, the selected elements are 482 marked in a particular way to distinguish them from the non-selected 483 elements.</p> 484 485 <p>Example:</p> 486 487 <pre><select template:multiple-choice-list-field="question-types,question-type-enum,question-type" name="..." multiple="multiple"><br /> ...<br /></select></pre> 488 489 <p>See below for an example combining this attribute with the <code>template:multiple-choice-list-value</code> attribute.</p> 490 491 <p>Syntax:</p> 492 493 <pre>element-name|<span style="font-weight: bold;">-</span>,list-element-name,list-attribute-name[,<span style="font-weight: bold;">dynamic</span>]</pre> 494 495 <p>Here, <code>element-name</code> is the element in the document being presented which contains the selected value elements; if the special value <code>-</code> is given then the context element is the element containing the selected value elements. The <code>list-element-name</code> and <code>list-attribute-name</code> indicate the details of the elements providing the list of selectable values. Where the optional parameter <code>dynamic</code> is given, the source of the multiple-choice values is considered to be found dynamically rather than from another document.</p> 496 497 <p>Related attributes:</p> 498 499 <ul><li><code>template:multiple-choice-list-value</code></li><li><code>template:multiple-choice-list-element</code></li><li><code>template:multiple-choice-field</code></li></ul> 500 501 <p>Implementing attributes:</p> 502 503 <ul><li><code>template:element</code></li></ul> 504 505 <h3><a name="multiple-choice-list-value"></a>template:multiple-choice-list-value</h3> 506 507 <p>This attribute is similar to <code>template:multiple-choice-value</code> 508 in that it associates the template element on which it is used with an 509 element holding a value in a list of selectable values, with the 510 principal difference that potentially many such values may be selected 511 in this case.</p> 512 513 <p>Example:</p> 514 515 <pre><select template:multiple-choice-list-field="question-types,question-type-enum,question-type" multiple="multiple"><br /> <option template:multiple-choice-list-value="question-type-enum,question-type,selected" value="..."/><br /></select></pre> 516 517 <p>This presents the following document fragment:</p> 518 519 <pre><question-types><br /> <question-type-enum question-type="text"/><br /> <question-type-enum question-type="choice" value-is-set="true"/><br /> <question-type-enum question-type="special" value-is-set="true"/><br /></question-types></pre> 520 521 <p>The output from the combination of the above would be as follows:</p> 522 523 <pre><select name="path-to-question-types" multiple="multiple"><br /> <option value="text">text</option><br /> <option value="choice" selected="selected">choice</option><br /> <option value="special" selected="selected">special</option><br /></select></pre> 524 525 <h4>Values and Labels</h4> 526 527 <p>Labels different from the actual values employed can be specified using an extra parameter in the annotation:</p> 528 529 <pre><select template:multiple-choice-list-field="question-types,question-type-enum,question-type" multiple="multiple"><br /> <option template:multiple-choice-list-value="question-type-enum,question-type,selected,text()" value="..."/><br /></select></pre> 530 531 <p>This additional parameter is an XPath expression whose context is 532 the current value-bearing element. The above example selects the text 533 from inside each <code>base-system-enum</code> element in the modified document fragment presented below.</p> 534 535 <p>A modified document fragment providing the labels can be written as follows:</p> 536 537 <pre><question-types><br /> <question-type-enum question-type="text">Text</question-type-enum><br /> <question-type-enum question-type="choice" value-is-set="true">Choice</question-type-enum><br /> <question-type-enum question-type="special" value-is-set="true">Special</question-type-enum><br /></question-types></pre> 538 539 <p>The output from the modified combination would be as follows:</p> 540 541 <pre><select name="path-to-question-types" multiple="multiple"><br /> <option value="text">Text</option><br /> <option value="choice" selected="selected">Choice</option><br /> <option value="special" selected="selected">Special</option><br /></select></pre> 542 543 <p>Syntax:</p> 544 545 <pre>list-element-name,list-attribute-name,attribute-to-create-when-selected[,content-expression]</pre> 546 547 <p>Related attributes:</p> 548 549 <ul><li><code>template:multiple-choice-list-field</code></li><li><code>template:multiple-choice-value</code></li></ul> 550 551 <p>Implementing attributes:</p> 552 553 <ul><li><code>template:element</code></li><li><code>template:expr</code></li><li><code>template:expr-attr</code></li><li><code>template:value</code></li></ul> 554 555 <h3><a name="multiple-choice-list-element"></a>template:multiple-choice-list-element</h3> 556 557 <p>This attribute works in much the same way as <code>template:multiple-choice-list-field</code> except that it does not add a <code>name</code> attribute to the template element on which it is used. The purpose of this attribute, along with <code>template:attribute-list-button</code>, is to provide an alternative approach to presenting lists of selectable values.</p> 558 559 <p>Example:</p> 560 561 <pre><p template:multiple-choice-list-element="question,question-types,question-type"><br /> ...<br /></p></pre> 562 563 <p>See below for an example combining this attribute with the <code>template:attribute-list-button</code> attribute.</p> 564 565 <p>Syntax:</p> 566 567 <pre>element-name|<span style="font-weight: bold;">-</span>,list-element-name,list-attribute-name</pre> 568 569 <p>Here, <code>element-name</code> is the element in the document being presented which contains the selected value elements; if the special value <code>-</code> is given then the context element is the element containing the selected value elements. The <code>list-element-name</code> and <code>list-attribute-name</code> indicate the details of the elements providing the list of selectable values.</p> 570 571 <p>Related attributes:</p> 572 573 <ul><li><code>template:multiple-choice-list-field</code></li><li><code>template:attribute-list-button</code></li></ul> 574 575 <p>Implementing attributes:</p> 576 577 <ul><li><code>template:element</code></li></ul> 578 579 <h3><a name="attribute-list-button"></a>template:attribute-list-button</h3> 580 581 <p>This attribute works in much the same way as <code>template:attribute-button</code> 582 does, but instead presents a button or related user interface control 583 whose state reflects the presence of an attribute on an element in a 584 collection of elements.</p> 585 586 <p>Example:</p> 587 588 <pre><p template:multiple-choice-list-element="question,question-types,question-type"><br /> <input template:attribute-list-button="question-type,checked" name="..." value="..." type="checkbox"/><br /></p></pre> 589 590 <p>Given an XML document like this...</p> 591 592 <pre><question><br /> <question-types question-type="text" value-is-set="true"/><br /> <question-types question-type="choice"/><br /></question></pre> 593 594 <p>...the following would be produced as output:</p> 595 596 <pre><p><br /> <input name="path-to-question-type" value="text" type="checkbox" checked="checked"/><br /></p><br /><p><br /> <input name="path-to-question-type" value="choice" type="checkbox"/><br /></p></pre> 597 598 <p>Syntax:</p> 599 600 <pre>attribute-name,attribute-to-create-when-set</pre> 601 602 <p>Related attributes:</p> 603 604 <ul><li><code>template:multiple-choice-list-element</code></li><li><code>template:attribute-button</code></li></ul> 605 606 <p>Implementing attributes:</p> 607 608 <ul><li><code>template:attribute</code></li><li><code>template:expr</code></li><li><code>template:expr-attr</code></li></ul> 609 610 <h2>Internal Annotations</h2> 611 612 <p>The special annotations <code>template:expr</code> and <code>template:expr-attr</code> 613 are used respectively to test an XPath expression in the current 614 context and to provide the name of an attribute which is to be created 615 in the final output, should the expression evaluate to a true value.</p> 616 617 <h2><a name="housekeeping-annotations"></a>Housekeeping Annotations</h2> 618 619 <p>In order to support explicit, additional namespaces in output document processing, the special <code>expr-prefix</code> 620 attribute can be used to ensure the presence of a namespace declaration 621 in the generated stylesheet files. Consider the usage of various 622 stylesheet extension functions:</p> 623 624 <pre><body><br /> <p><br /> <span template:value="sum(str:split('1 2 3 4 5'))">result</span><br /> </p><br /></body></pre> 625 626 <p>For the stylesheet which produces the output, the <code>str</code> 627 namespace will need to be declared somewhere. To do this, we must not 628 only declare the namespace in the template document, but we must also 629 provide a hint to the stylesheet processor that the namespace is 630 important (even though it is only mentioned in the text of an 631 attribute, which might persuade some XML processing toolkits to abandon 632 the namespace declaration).</p> 633 634 <pre><body xmlns:str="http://exslt.org/strings" str:expr-prefix="str http://exslt.org/strings"><br /> <p><br /> <span template:value="sum(str:split('1 2 3 4 5'))">result</span><br /> </p><br /></body></pre> 635 636 <p>What the special <code>expr-prefix</code> 637 attribute does is to provide that hint to the stylesheet processor, 638 although XSLTools also uses the attribute for other internal purposes. 639 Consequently, the resulting output stylesheet is able to find the <code>str:split</code> extension function and to evaluate the expected result.</p> 640 641 <h3>Fixing Annotations</h3> 642 643 <p>One important application of the <code>expr-prefix</code> 644 attribute is the restoration of damaged attributes after the editing of 645 a template document using a less than careful HTML editor. Consider the 646 above document fragment after a small edit in Nvu:</p> 647 648 <pre><body expr-prefix="str http://exslt.org/strings" str="http://exslt.org/strings"><br /> <p><br /> <span value="sum(str:split('1 2 3 4 5'))">result!</span><br /> </p><br /></body></pre> 649 650 <p>Nvu has obviously decided to remove the <code>str</code> and <code>template</code> namespace prefixes. To revert this damage, a tool is provided with XSLTools called <code>xslform_fix.py</code> (found in the <code>scripts</code> directory in the source distribution), and this tool will attempt to re-add namespace declarations for <code>template</code> automatically (since the <code>template</code> namespace is obviously the basis of XSLForms) along with any namespaces declared using <code>expr-prefix</code> attributes. The tool is invoked as follows:</p> 651 652 <pre>xslform_fix.py template.xhtml template_fixed.xhtml</pre> 653 654 <p>Since 655 namespace declarations may be moved to the root element of the new 656 template document, it is possible that some problems may result 657 with documents using namespaces in advanced ways, but the tool 658 should provide a reasonable solution for most documents.</p></body></html>