1.1 --- a/docs/reference.html Fri Oct 05 23:43:58 2007 +0000
1.2 +++ b/docs/reference.html Fri Oct 05 23:44:19 2007 +0000
1.3 @@ -3,101 +3,587 @@
1.4 <html xmlns="http://www.w3.org/1999/xhtml"><head>
1.5 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /><title>Template Attribute Reference</title>
1.6 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
1.7 -<body><h1>Template Attribute Reference</h1>
1.8 +<body>
1.9 +
1.10 +<h1>Template Attribute Reference</h1>
1.11 <p>This document presents each of the attributes used in
1.12 templates to annotate the structure of the XML documents being
1.13 -presented and to modify the final output of the presented document.</p><h2>Basic Annotations</h2><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><h3><a name="element"></a>template:element</h3><p>This
1.14 +presented and to modify the final output of the presented document.</p>
1.15 +
1.16 +<h2>Basic Annotations</h2>
1.17 +
1.18 +<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>
1.19 +
1.20 +<h3><a name="element"></a>template:element</h3>
1.21 +
1.22 +<p>This
1.23 attribute associates the template element on which it is used with an
1.24 element from the XML document being presented. Matching elements are
1.25 found from the current position (or context), where the position
1.26 -is updated upon entering a template element with a <code>template:element</code> or <code>template:attribute</code> annotation.</p><p>Example:</p><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><p>Example:</p><pre><p template:element="first,second,third"><br /> For each third element found, this section is produced.<br /></p></pre><p>Syntax:</p><pre>element-name1[,element-name2[,...]]</pre><p>Related attributes:</p><ul><li><code>template:init</code></li></ul><h3><a name="attribute"></a>template:attribute</h3><p>This attribute associates the template element on which it is used with an attribute in the XML document being presented.</p><p>Example:</p><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><p>Syntax:</p><pre>attribute-name</pre><p>Related attributes:</p><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><h3><a name="value"></a>template:value</h3><p>This attribute produces, in the final output, the value of part of the XML document being presented.</p><p>Example:</p><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><p>Example:</p><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><p>Syntax:</p><pre>XPath-expression</pre><p>Here, the underlying XPath mechanisms are exposed, but a number of useful shortcuts are available:</p><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.<p>Related attributes:</p><ul><li><code>template:effect</code></li></ul><h3><a name="effect"></a>template:effect</h3><p>This attribute modifies the effect of a <code>template:value</code> annotation.</p><p>Example:</p><p>(See above.)</p><p>Syntax:</p><pre><span style="font-weight: bold;">insert</span>|<span style="font-weight: bold;">replace</span></pre><p>Related attributes:</p><ul><li><code>template:effect</code></li><li><code>template:attribute-area</code></li></ul><h3><a name="if"></a>template:if</h3><p>This
1.27 +is updated upon entering a template element with a <code>template:element</code> or <code>template:attribute</code> annotation.</p>
1.28 +
1.29 +<p>Example:</p>
1.30 +
1.31 +<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>
1.32 +
1.33 +<p>Example:</p>
1.34 +
1.35 +<pre><p template:element="first,second,third"><br /> For each third element found, this section is produced.<br /></p></pre>
1.36 +
1.37 +<p>Syntax:</p>
1.38 +
1.39 +<pre>element-name1[,element-name2[,...]]</pre>
1.40 +
1.41 +<p>Related attributes:</p>
1.42 +
1.43 +<ul><li><code>template:init</code></li></ul>
1.44 +
1.45 +<h3><a name="attribute"></a>template:attribute</h3>
1.46 +
1.47 +<p>This attribute associates the template element on which it is used with an attribute in the XML document being presented.</p>
1.48 +
1.49 +<p>Example:</p>
1.50 +
1.51 +<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>
1.52 +
1.53 +<p>Syntax:</p>
1.54 +
1.55 +<pre>attribute-name</pre>
1.56 +
1.57 +<p>Related attributes:</p>
1.58 +
1.59 +<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>
1.60 +
1.61 +<h3><a name="value"></a>template:value</h3>
1.62 +
1.63 +<p>This attribute produces, in the final output, the value of part of the XML document being presented.</p>
1.64 +
1.65 +<p>Example:</p>
1.66 +
1.67 +<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>
1.68 +
1.69 +<p>Example:</p>
1.70 +
1.71 +<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>
1.72 +
1.73 +<p>Syntax:</p>
1.74 +
1.75 +<pre>XPath-expression</pre>
1.76 +
1.77 +<p>Here, the underlying XPath mechanisms are exposed, but a number of useful shortcuts are available:</p>
1.78 +
1.79 +<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.
1.80 +
1.81 +<p>Related attributes:</p>
1.82 +
1.83 +<ul><li><code>template:effect</code></li></ul>
1.84 +
1.85 +<h3><a name="effect"></a>template:effect</h3>
1.86 +
1.87 +<p>This attribute modifies the effect of a <code>template:value</code> annotation.</p>
1.88 +
1.89 +<p>Example:</p>
1.90 +
1.91 +<p>(See above.)</p>
1.92 +
1.93 +<p>Syntax:</p>
1.94 +
1.95 +<pre><span style="font-weight: bold;">insert</span>|<span style="font-weight: bold;">replace</span></pre>
1.96 +
1.97 +<p>Related attributes:</p>
1.98 +
1.99 +<ul><li><code>template:effect</code></li><li><code>template:attribute-area</code></li></ul>
1.100 +
1.101 +<h3><a name="if"></a>template:if</h3>
1.102 +
1.103 +<p>This
1.104 attribute permits the inclusion of a section of the template document
1.105 -according to a test performed on the XML document being presented.</p><p>Example:</p><pre><p template:if="@value = 'true'"><br /> If the value attribute is set to the string value 'true', include this section.<br /></p></pre><p>Syntax:</p><pre>XPath-expression</pre><p>Here,
1.106 +according to a test performed on the XML document being presented.</p>
1.107 +
1.108 +<p>Example:</p>
1.109 +
1.110 +<pre><p template:if="@value = 'true'"><br /> If the value attribute is set to the string value 'true', include this section.<br /></p></pre>
1.111 +
1.112 +<p>Syntax:</p>
1.113 +
1.114 +<pre>XPath-expression</pre>
1.115 +
1.116 +<p>Here,
1.117 the underlying XPath mechanisms are exposed, and any XPath expression
1.118 -which tests aspects of the XML document can be written.</p><h3><a name="i18n"></a>template:i18n</h3><p>This
1.119 +which tests aspects of the XML document can be written.</p>
1.120 +
1.121 +<h3><a name="i18n"></a>template:i18n</h3>
1.122 +
1.123 +<p>This
1.124 attribute is used to translate the textual contents of an element to
1.125 another language where additional parameters specifying the language
1.126 and the whereabouts of the translations have been provided to the
1.127 -stylesheet in the output generation process.</p><p>Example:</p><pre><span template:i18n="-">Hello</span></pre><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><p>Example:</p><pre><span template:i18n="hello">Hello</span></pre><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><p>Example:</p><pre><span template:i18n="{$this-value}">Hello</span></pre><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><p>Syntax:</p><pre><span style="font-weight: bold;">-</span>|<span style="font-weight: bold;">{</span>expression<span style="font-weight: bold;">}</span>|token</pre><p>See the <a href="internationalisation.html">"Internationalisation"</a> document for more information on this attribute.</p><h2>Initialisation Annotations</h2><p>The annotation attributes in this section control the initialisation of documents where this is done by the XSLForms toolkit.</p><h3><a name="init"></a>template:init</h3><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><p>Example:</p><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><p>Example:</p><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><p>Syntax:</p><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><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>
1.128 +stylesheet in the output generation process.</p>
1.129 +
1.130 +<p>Example:</p>
1.131 +
1.132 +<pre><span template:i18n="-">Hello</span></pre>
1.133 +
1.134 +<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>
1.135 +
1.136 +<p>Example:</p>
1.137 +
1.138 +<pre><span template:i18n="hello">Hello</span></pre>
1.139 +
1.140 +<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>
1.141 +
1.142 +<p>Example:</p>
1.143 +
1.144 +<pre><span template:i18n="{$this-value}">Hello</span></pre>
1.145 +
1.146 +<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>
1.147 +
1.148 +<p>Syntax:</p>
1.149 +
1.150 +<pre><span style="font-weight: bold;">-</span>|<span style="font-weight: bold;">{</span>expression<span style="font-weight: bold;">}</span>|token</pre>
1.151 +
1.152 +<p>See the <a href="internationalisation.html">"Internationalisation"</a> document for more information on this attribute.</p>
1.153 +
1.154 +<h2>Initialisation Annotations</h2>
1.155 +
1.156 +<p>The annotation attributes in this section control the initialisation of documents where this is done by the XSLForms toolkit.</p>
1.157 +
1.158 +<h3><a name="init"></a>template:init</h3>
1.159 +
1.160 +<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>
1.161 +
1.162 +<p>Example:</p>
1.163 +
1.164 +<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>
1.165 +
1.166 +<p>Example:</p>
1.167 +
1.168 +<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>
1.169 +
1.170 +<p>Syntax:</p>
1.171 +
1.172 +<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>
1.173 +
1.174 +<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>
1.175 means that the initialisation process will attempt to guess whether an
1.176 element should be created automatically (by looking for selectors which
1.177 use the element's name and only creating elements where no such
1.178 -selectors could be found). Where no values are provided, <code>auto</code> is assumed.</p><p>Related attributes:</p><ul><li><code>template:element</code></li></ul><h2>Convenience Annotations</h2><p>The
1.179 +selectors could be found). Where no values are provided, <code>auto</code> is assumed.</p>
1.180 +
1.181 +<p>Related attributes:</p>
1.182 +
1.183 +<ul><li><code>template:element</code></li></ul>
1.184 +
1.185 +<h2>Convenience Annotations</h2>
1.186 +
1.187 +<p>The
1.188 annotation attributes in this section provide more convenient ways of
1.189 -presenting the XML document information in the final output.</p><h3><a name="attribute-field"></a>template:attribute-field</h3><p>This
1.190 +presenting the XML document information in the final output.</p>
1.191 +
1.192 +<h3><a name="attribute-field"></a>template:attribute-field</h3>
1.193 +
1.194 +<p>This
1.195 attribute associates the template element on which it is used with an
1.196 attribute from the XML document, whilst providing certain other
1.197 -attributes in the final output:</p><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><p>Example:</p><pre><input template:attribute-field="name" name="..." value="..." type="text"/></pre><p>This would be output as follows:</p><pre><input name="path-to-name" value="value-of-name" type="text"/></pre><p>...where <code>path-to-name</code> and <code>value-of-name</code> would be replaced with the appropriate computed values.</p><p>Syntax:</p><pre>attribute-name</pre><p>Related attributes:</p><ul><li><code>template:attribute-area</code></li><li><code>template:attribute-button</code></li></ul><p>Implementing attributes:</p><ul><li><code>template:attribute</code></li></ul><h3><a name="attribute-area"></a>template:attribute-area</h3><p>This
1.198 +attributes in the final output:</p>
1.199 +
1.200 +<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>
1.201 +
1.202 +<p>Example:</p>
1.203 +
1.204 +<pre><input template:attribute-field="name" name="..." value="..." type="text"/></pre>
1.205 +
1.206 +<p>This would be output as follows:</p>
1.207 +
1.208 +<pre><input name="path-to-name" value="value-of-name" type="text"/></pre>
1.209 +
1.210 +<p>...where <code>path-to-name</code> and <code>value-of-name</code> would be replaced with the appropriate computed values.</p>
1.211 +
1.212 +<p>Syntax:</p>
1.213 +
1.214 +<pre>attribute-name</pre>
1.215 +
1.216 +<p>Related attributes:</p>
1.217 +
1.218 +<ul><li><code>template:attribute-area</code></li><li><code>template:attribute-button</code></li></ul>
1.219 +
1.220 +<p>Implementing attributes:</p>
1.221 +
1.222 +<ul><li><code>template:attribute</code></li></ul>
1.223 +
1.224 +<h3><a name="attribute-area"></a>template:attribute-area</h3>
1.225 +
1.226 +<p>This
1.227 attribute associates the template element on which it is used with an
1.228 attribute from the XML document being presented, much in the way
1.229 that <code>template:attribute-field</code> does. However, the
1.230 attribute value is not inserted into an attribute in the final output;
1.231 instead it is inserted into the output in a different way according to
1.232 -additional information specified in the annotation.</p><p>Example:</p><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><p>Example:</p><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><p>Syntax:</p><pre>attribute-name[,<span style="font-weight: bold;">insert</span>|<span style="font-weight: bold;">replace</span>]</pre><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><p>Related attributes:</p><ul><li><code>template:attribute-field</code></li></ul><p>Implementing attributes:</p><ul><li><code>template:attribute</code></li></ul><h3><a name="attribute-button"></a>template:attribute-button</h3><p>This attribute associates the template element on which it is used
1.233 +additional information specified in the annotation.</p>
1.234 +
1.235 +<p>Example:</p>
1.236 +
1.237 +<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>
1.238 +
1.239 +<p>Example:</p>
1.240 +
1.241 +<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>
1.242 +
1.243 +<p>Syntax:</p>
1.244 +
1.245 +<pre>attribute-name[,<span style="font-weight: bold;">insert</span>|<span style="font-weight: bold;">replace</span>]</pre>
1.246 +
1.247 +<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>
1.248 +
1.249 +<p>Related attributes:</p>
1.250 +
1.251 +<ul><li><code>template:attribute-field</code></li></ul>
1.252 +
1.253 +<p>Implementing attributes:</p>
1.254 +
1.255 +<ul><li><code>template:attribute</code></li></ul>
1.256 +
1.257 +<h3><a name="attribute-button"></a>template:attribute-button</h3>
1.258 +
1.259 +<p>This attribute associates the template element on which it is used
1.260 with an attribute from the XML document, whilst providing certain other
1.261 -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><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><p>Example:</p><pre><input template:attribute-button="question-type,text,checked" name="..." value="..." type="radio"/></pre><p>This would produce a "radio" button like the following:</p><pre><input name="path-to-question-type" value="text" type="radio"/></pre><p>If the value of <code>question-type</code> was set to text, output like the following would be produced:</p><pre><input name="path-to-question-type" value="text" type="radio" checked="checked"/></pre><p>In an XHTML document, this would cause the "radio" button to appear selected or activated.</p><p>Syntax:</p><pre>attribute-name,attribute-value,attribute-to-create-when-set</pre><p>Related attributes:</p><ul><li><code>template:attribute-field</code></li><li><code>template:attribute-list-button</code></li></ul><p>Implementing attributes:</p><ul><li><code>template:attribute</code></li><li><code>template:expr</code></li><li><code>template:expr-attr</code></li></ul><h3><a name="selector-field"></a>template:selector-field</h3><p>This
1.262 +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>
1.263 +
1.264 +<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>
1.265 +
1.266 +<p>Example:</p>
1.267 +
1.268 +<pre><input template:attribute-button="question-type,text,checked" name="..." value="..." type="radio"/></pre>
1.269 +
1.270 +<p>This would produce a "radio" button like the following:</p>
1.271 +
1.272 +<pre><input name="path-to-question-type" value="text" type="radio"/></pre>
1.273 +
1.274 +<p>If the value of <code>question-type</code> was set to text, output like the following would be produced:</p>
1.275 +
1.276 +<pre><input name="path-to-question-type" value="text" type="radio" checked="checked"/></pre>
1.277 +
1.278 +<p>In an XHTML document, this would cause the "radio" button to appear selected or activated.</p>
1.279 +
1.280 +<p>Syntax:</p>
1.281 +
1.282 +<pre>attribute-name,attribute-value,attribute-to-create-when-set</pre>
1.283 +
1.284 +<p>Related attributes:</p>
1.285 +
1.286 +<ul><li><code>template:attribute-field</code></li><li><code>template:attribute-list-button</code></li></ul>
1.287 +
1.288 +<p>Implementing attributes:</p>
1.289 +
1.290 +<ul><li><code>template:attribute</code></li><li><code>template:expr</code></li><li><code>template:expr-attr</code></li></ul>
1.291 +
1.292 +<h3><a name="selector-field"></a>template:selector-field</h3>
1.293 +
1.294 +<p>This
1.295 attribute permits the definition of references to the parts of the XML
1.296 document being presented which are associated with the template
1.297 elements in which it is used. When used in certain HTML form-related
1.298 elements, it becomes possible to receive and obtain such references
1.299 from the XSLForms toolkit and to then access the selected parts of the
1.300 -original document.</p><p>Example:</p><pre><p template:element="item"><br /> <input template:selector-field="remove" name="..." value="Remove this item" type="submit"/><br /></p></pre><p>Example:</p><pre><p template:element="item"><br /> An item...<br /></p><br /><input template:selector-field="add,item" name="..." value="Add item" type="submit"/></pre><p>Syntax:</p><pre>selector-name[,element-name]</pre><p>The
1.301 +original document.</p>
1.302 +
1.303 +<p>Example:</p>
1.304 +
1.305 +<pre><p template:element="item"><br /> <input template:selector-field="remove" name="..." value="Remove this item" type="submit"/><br /></p></pre>
1.306 +
1.307 +<p>Example:</p>
1.308 +
1.309 +<pre><p template:element="item"><br /> An item...<br /></p><br /><input template:selector-field="add,item" name="..." value="Add item" type="submit"/></pre>
1.310 +
1.311 +<p>Syntax:</p>
1.312 +
1.313 +<pre>selector-name[,element-name]</pre>
1.314 +
1.315 +<p>The
1.316 optional element name can be used to associate the selector with other
1.317 elements; when this is done, the initialisation of the XML document
1.318 will be affected such that the named element will not be automatically
1.319 created in the initialisation process, since the presence of the
1.320 selector implies that such elements can be added and removed in the
1.321 -application user interface.</p><p>Related attributes:</p><ul><li><code>template:element</code></li></ul><h2>Multiple-choice Annotations</h2><p>The annotation attributes in this section provide ways of presenting enumerations and selections of values.</p><h3><a name="multiple-choice-field"></a>template:multiple-choice-field</h3><p>This
1.322 +application user interface.</p>
1.323 +
1.324 +<p>Related attributes:</p>
1.325 +
1.326 +<ul><li><code>template:element</code></li></ul>
1.327 +
1.328 +<h2>Multiple-choice Annotations</h2>
1.329 +
1.330 +<p>The annotation attributes in this section provide ways of presenting enumerations and selections of values.</p>
1.331 +
1.332 +<h3><a name="multiple-choice-field"></a>template:multiple-choice-field</h3>
1.333 +
1.334 +<p>This
1.335 attribute associates the template element on which it is used with an
1.336 attribute in the XML document being presented whose value is to be
1.337 chosen from a list of possibilities. The list itself is represented by
1.338 a list of elements, each having an attribute with a distinct
1.339 value; such information is added in the initialisation of the
1.340 document before it is presented, since it is not part of the
1.341 -"essential" information in the document.</p><p>Example:</p><pre><select template:multiple-choice-field="base-system,value" name="..."><br /> ...<br /></select></pre><p>Example:</p><pre><select template:multiple-choice-field="-,question-type" name="..."><br /> ...<br /></select></pre><p>See below for an example combining this attribute with the <code>template:multiple-choice-value</code> attribute.</p><p>Syntax:</p><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><p>Where the special value <code>-</code>
1.342 +"essential" information in the document.</p>
1.343 +
1.344 +<p>Example:</p>
1.345 +
1.346 +<pre><select template:multiple-choice-field="base-system,value" name="..."><br /> ...<br /></select></pre>
1.347 +
1.348 +<p>Example:</p>
1.349 +
1.350 +<pre><select template:multiple-choice-field="-,question-type" name="..."><br /> ...<br /></select></pre>
1.351 +
1.352 +<p>See below for an example combining this attribute with the <code>template:multiple-choice-value</code> attribute.</p>
1.353 +
1.354 +<p>Syntax:</p>
1.355 +
1.356 +<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>
1.357 +
1.358 +<p>Where the special value <code>-</code>
1.359 is given as the element name, the context element is chosen as the
1.360 element in the XML document being presented whose attribute is
1.361 -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><p>Related attributes:</p><ul><li><code>template:multiple-choice-value</code></li><li><code>template:multiple-choice-list-field</code></li></ul><p>Implementing attributes:</p><ul><li><code>template:element</code></li><li><code>template:attribute</code></li></ul><h3><a name="multiple-choice-value"></a>template:multiple-choice-value</h3><p>This
1.362 +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>
1.363 +
1.364 +<p>Related attributes:</p>
1.365 +
1.366 +<ul><li><code>template:multiple-choice-value</code></li><li><code>template:multiple-choice-list-field</code></li></ul>
1.367 +
1.368 +<p>Implementing attributes:</p>
1.369 +
1.370 +<ul><li><code>template:element</code></li><li><code>template:attribute</code></li></ul>
1.371 +
1.372 +<h3><a name="multiple-choice-value"></a>template:multiple-choice-value</h3>
1.373 +
1.374 +<p>This
1.375 attribute associates the template element on which it is used with an
1.376 element in the XML document being presented whose purpose is to hold
1.377 -one of a list of selectable values (as described above).</p><p>Example:</p><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><p>This presents the following document fragment:</p><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><p>The output from the combination of the above would be as follows:</p><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><h4>Values and Labels</h4><p>Labels different from the actual values employed can be specified using an extra parameter in the annotation:</p><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><p>This
1.378 +one of a list of selectable values (as described above).</p>
1.379 +
1.380 +<p>Example:</p>
1.381 +
1.382 +<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>
1.383 +
1.384 +<p>This presents the following document fragment:</p>
1.385 +
1.386 +<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>
1.387 +
1.388 +<p>The output from the combination of the above would be as follows:</p>
1.389 +
1.390 +<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>
1.391 +
1.392 +<h4>Values and Labels</h4>
1.393 +
1.394 +<p>Labels different from the actual values employed can be specified using an extra parameter in the annotation:</p>
1.395 +
1.396 +<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>
1.397 +
1.398 +<p>This
1.399 additional parameter is an XPath expression whose context is the
1.400 current value-bearing element. The above example selects the text from
1.401 -inside each <code>base-system-enum</code> element in the modified document fragment presented below.</p><p>A modified document fragment providing the labels can be written as follows:</p><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><p>The output from the modified combination would be as follows:</p><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><p>Syntax:</p><pre>list-element-name,list-attribute-name,attribute-to-create-when-selected[,content-expression]</pre><p>Related attributes:</p><ul><li><code>template:multiple-choice-field</code></li><li><code>template:multiple-choice-list-value</code></li></ul><p>Implementing attributes:</p><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><h3><a name="multiple-choice-list-field"></a>template:multiple-choice-list-field</h3><p>This attribute is similar to <code>template:multiple-choice-field</code>
1.402 +inside each <code>base-system-enum</code> element in the modified document fragment presented below.</p>
1.403 +
1.404 +<p>A modified document fragment providing the labels can be written as follows:</p>
1.405 +
1.406 +<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>
1.407 +
1.408 +<p>The output from the modified combination would be as follows:</p>
1.409 +
1.410 +<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>
1.411 +
1.412 +<p>Syntax:</p>
1.413 +
1.414 +<pre>list-element-name,list-attribute-name,attribute-to-create-when-selected[,content-expression]</pre>
1.415 +
1.416 +<p>Related attributes:</p>
1.417 +
1.418 +<ul><li><code>template:multiple-choice-field</code></li><li><code>template:multiple-choice-list-value</code></li></ul>
1.419 +
1.420 +<p>Implementing attributes:</p>
1.421 +
1.422 +<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>
1.423 +
1.424 +<h3><a name="multiple-choice-list-field"></a>template:multiple-choice-list-field</h3>
1.425 +
1.426 +<p>This attribute is similar to <code>template:multiple-choice-field</code>
1.427 except that it associates the template element on which it is used with
1.428 an element in the XML document being presented containing a list
1.429 of elements whose values have been selected. This list of selected
1.430 elements is expanded before presentation to include elements whose
1.431 values have not been selected. Consequently, the selected elements are
1.432 marked in a particular way to distinguish them from the non-selected
1.433 -elements.</p><p>Example:</p><pre><select template:multiple-choice-list-field="question-types,question-type-enum,question-type" name="..." multiple="multiple"><br /> ...<br /></select></pre><p>See below for an example combining this attribute with the <code>template:multiple-choice-list-value</code> attribute.</p><p>Syntax:</p><pre>element-name|<span style="font-weight: bold;">-</span>,list-element-name,list-attribute-name[,<span style="font-weight: bold;">dynamic</span>]</pre><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><p>Related attributes:</p><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><p>Implementing attributes:</p><ul><li><code>template:element</code></li></ul><h3><a name="multiple-choice-list-value"></a>template:multiple-choice-list-value</h3><p>This attribute is similar to <code>template:multiple-choice-value</code>
1.434 +elements.</p>
1.435 +
1.436 +<p>Example:</p>
1.437 +
1.438 +<pre><select template:multiple-choice-list-field="question-types,question-type-enum,question-type" name="..." multiple="multiple"><br /> ...<br /></select></pre>
1.439 +
1.440 +<p>See below for an example combining this attribute with the <code>template:multiple-choice-list-value</code> attribute.</p>
1.441 +
1.442 +<p>Syntax:</p>
1.443 +
1.444 +<pre>element-name|<span style="font-weight: bold;">-</span>,list-element-name,list-attribute-name[,<span style="font-weight: bold;">dynamic</span>]</pre>
1.445 +
1.446 +<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>
1.447 +
1.448 +<p>Related attributes:</p>
1.449 +
1.450 +<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>
1.451 +
1.452 +<p>Implementing attributes:</p>
1.453 +
1.454 +<ul><li><code>template:element</code></li></ul>
1.455 +
1.456 +<h3><a name="multiple-choice-list-value"></a>template:multiple-choice-list-value</h3>
1.457 +
1.458 +<p>This attribute is similar to <code>template:multiple-choice-value</code>
1.459 in that it associates the template element on which it is used with an
1.460 element holding a value in a list of selectable values, with the
1.461 principal difference that potentially many such values may be selected
1.462 -in this case.</p><p>Example:</p><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><p>This presents the following document fragment:</p><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><p>The output from the combination of the above would be as follows:</p><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><h4>Values and Labels</h4><p>Labels different from the actual values employed can be specified using an extra parameter in the annotation:</p><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><p>This additional parameter is an XPath expression whose context is
1.463 +in this case.</p>
1.464 +
1.465 +<p>Example:</p>
1.466 +
1.467 +<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>
1.468 +
1.469 +<p>This presents the following document fragment:</p>
1.470 +
1.471 +<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>
1.472 +
1.473 +<p>The output from the combination of the above would be as follows:</p>
1.474 +
1.475 +<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>
1.476 +
1.477 +<h4>Values and Labels</h4>
1.478 +
1.479 +<p>Labels different from the actual values employed can be specified using an extra parameter in the annotation:</p>
1.480 +
1.481 +<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>
1.482 +
1.483 +<p>This additional parameter is an XPath expression whose context is
1.484 the current value-bearing element. The above example selects the text
1.485 -from inside each <code>base-system-enum</code> element in the modified document fragment presented below.</p><p>A modified document fragment providing the labels can be written as follows:</p><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><p>The output from the modified combination would be as follows:</p><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><p>Syntax:</p><pre>list-element-name,list-attribute-name,attribute-to-create-when-selected[,content-expression]</pre><p>Related attributes:</p><ul><li><code>template:multiple-choice-list-field</code></li><li><code>template:multiple-choice-value</code></li></ul><p>Implementing attributes:</p><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><h3><a name="multiple-choice-list-element"></a>template:multiple-choice-list-element</h3><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><p>Example:</p><pre><p template:multiple-choice-list-element="question,question-types,question-type"><br /> ...<br /></p></pre><p>See below for an example combining this attribute with the <code>template:attribute-list-button</code> attribute.</p><p>Syntax:</p><pre>element-name|<span style="font-weight: bold;">-</span>,list-element-name,list-attribute-name</pre><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><p>Related attributes:</p><ul><li><code>template:multiple-choice-list-field</code></li><li><code>template:attribute-list-button</code></li></ul><p>Implementing attributes:</p><ul><li><code>template:element</code></li></ul><h3><a name="attribute-list-button"></a>template:attribute-list-button</h3><p>This attribute works in much the same way as <code>template:attribute-button</code>
1.486 +from inside each <code>base-system-enum</code> element in the modified document fragment presented below.</p>
1.487 +
1.488 +<p>A modified document fragment providing the labels can be written as follows:</p>
1.489 +
1.490 +<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>
1.491 +
1.492 +<p>The output from the modified combination would be as follows:</p>
1.493 +
1.494 +<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>
1.495 +
1.496 +<p>Syntax:</p>
1.497 +
1.498 +<pre>list-element-name,list-attribute-name,attribute-to-create-when-selected[,content-expression]</pre>
1.499 +
1.500 +<p>Related attributes:</p>
1.501 +
1.502 +<ul><li><code>template:multiple-choice-list-field</code></li><li><code>template:multiple-choice-value</code></li></ul>
1.503 +
1.504 +<p>Implementing attributes:</p>
1.505 +
1.506 +<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>
1.507 +
1.508 +<h3><a name="multiple-choice-list-element"></a>template:multiple-choice-list-element</h3>
1.509 +
1.510 +<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>
1.511 +
1.512 +<p>Example:</p>
1.513 +
1.514 +<pre><p template:multiple-choice-list-element="question,question-types,question-type"><br /> ...<br /></p></pre>
1.515 +
1.516 +<p>See below for an example combining this attribute with the <code>template:attribute-list-button</code> attribute.</p>
1.517 +
1.518 +<p>Syntax:</p>
1.519 +
1.520 +<pre>element-name|<span style="font-weight: bold;">-</span>,list-element-name,list-attribute-name</pre>
1.521 +
1.522 +<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>
1.523 +
1.524 +<p>Related attributes:</p>
1.525 +
1.526 +<ul><li><code>template:multiple-choice-list-field</code></li><li><code>template:attribute-list-button</code></li></ul>
1.527 +
1.528 +<p>Implementing attributes:</p>
1.529 +
1.530 +<ul><li><code>template:element</code></li></ul>
1.531 +
1.532 +<h3><a name="attribute-list-button"></a>template:attribute-list-button</h3>
1.533 +
1.534 +<p>This attribute works in much the same way as <code>template:attribute-button</code>
1.535 does, but instead presents a button or related user interface control
1.536 whose state reflects the presence of an attribute on an element in a
1.537 -collection of elements.</p><p>Example:</p><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><p>Given an XML document like this...</p><pre><question><br /> <question-types question-type="text" value-is-set="true"/><br /> <question-types question-type="choice"/><br /></question></pre><p>...the following would be produced as output:</p><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><p>Syntax:</p><pre>attribute-name,attribute-to-create-when-set</pre><p>Related attributes:</p><ul><li><code>template:multiple-choice-list-element</code></li><li><code>template:attribute-button</code></li></ul><p>Implementing attributes:</p><ul><li><code>template:attribute</code></li><li><code>template:expr</code></li><li><code>template:expr-attr</code></li></ul><h2>Internal Annotations</h2><p>The special annotations <code>template:expr</code> and <code>template:expr-attr</code>
1.538 +collection of elements.</p>
1.539 +
1.540 +<p>Example:</p>
1.541 +
1.542 +<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>
1.543 +
1.544 +<p>Given an XML document like this...</p>
1.545 +
1.546 +<pre><question><br /> <question-types question-type="text" value-is-set="true"/><br /> <question-types question-type="choice"/><br /></question></pre>
1.547 +
1.548 +<p>...the following would be produced as output:</p>
1.549 +
1.550 +<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>
1.551 +
1.552 +<p>Syntax:</p>
1.553 +
1.554 +<pre>attribute-name,attribute-to-create-when-set</pre>
1.555 +
1.556 +<p>Related attributes:</p>
1.557 +
1.558 +<ul><li><code>template:multiple-choice-list-element</code></li><li><code>template:attribute-button</code></li></ul>
1.559 +
1.560 +<p>Implementing attributes:</p>
1.561 +
1.562 +<ul><li><code>template:attribute</code></li><li><code>template:expr</code></li><li><code>template:expr-attr</code></li></ul>
1.563 +
1.564 +<h2>Internal Annotations</h2>
1.565 +
1.566 +<p>The special annotations <code>template:expr</code> and <code>template:expr-attr</code>
1.567 are used respectively to test an XPath expression in the current
1.568 context and to provide the name of an attribute which is to be created
1.569 -in the final output, should the expression evaluate to a true value.</p><h2>Housekeeping Annotations</h2><p>In order to support explicit, additional namespaces in output document processing, the special <code>expr-prefix</code>
1.570 +in the final output, should the expression evaluate to a true value.</p>
1.571 +
1.572 +<h2><a name="housekeeping-annotations"></a>Housekeeping Annotations</h2>
1.573 +
1.574 +<p>In order to support explicit, additional namespaces in output document processing, the special <code>expr-prefix</code>
1.575 attribute can be used to ensure the presence of a namespace declaration
1.576 in the generated stylesheet files. Consider the usage of various
1.577 -stylesheet extension functions:</p><pre><body><br /> <p><br /> <span template:value="sum(str:split('1 2 3 4 5'))">result</span><br /> </p><br /></body></pre><p>For the stylesheet which produces the output, the <code>str</code>
1.578 +stylesheet extension functions:</p>
1.579 +
1.580 +<pre><body><br /> <p><br /> <span template:value="sum(str:split('1 2 3 4 5'))">result</span><br /> </p><br /></body></pre>
1.581 +
1.582 +<p>For the stylesheet which produces the output, the <code>str</code>
1.583 namespace will need to be declared somewhere. To do this, we must not
1.584 only declare the namespace in the template document, but we must also
1.585 provide a hint to the stylesheet processor that the namespace is
1.586 important (even though it is only mentioned in the text of an
1.587 attribute, which might persuade some XML processing toolkits to abandon
1.588 -the namespace declaration).</p><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><p>What the special <code>expr-prefix</code>
1.589 +the namespace declaration).</p>
1.590 +
1.591 +<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>
1.592 +
1.593 +<p>What the special <code>expr-prefix</code>
1.594 attribute does is to provide that hint to the stylesheet processor,
1.595 although XSLTools also uses the attribute for other internal purposes.
1.596 -Consequently, the resulting output stylesheet is able to find the <code>str:split</code> extension function and to evaluate the expected result.</p><h3>Fixing Annotations</h3><p>One important application of the <code>expr-prefix</code>
1.597 +Consequently, the resulting output stylesheet is able to find the <code>str:split</code> extension function and to evaluate the expected result.</p>
1.598 +
1.599 +<h3>Fixing Annotations</h3>
1.600 +
1.601 +<p>One important application of the <code>expr-prefix</code>
1.602 attribute is the restoration of damaged attributes after the editing of
1.603 a template document using a less than careful HTML editor. Consider the
1.604 -above document fragment after a small edit in Nvu:</p><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><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><pre>xslform_fix.py template.xhtml template_fixed.xhtml</pre><p>Since
1.605 +above document fragment after a small edit in Nvu:</p>
1.606 +
1.607 +<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>
1.608 +
1.609 +<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>
1.610 +
1.611 +<pre>xslform_fix.py template.xhtml template_fixed.xhtml</pre>
1.612 +
1.613 +<p>Since
1.614 namespace declarations may be moved to the root element of the new
1.615 template document, it is possible that some problems may result
1.616 with documents using namespaces in advanced ways, but the tool
