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