1.1 --- a/docs/reference.html Sun Nov 29 02:01:41 2009 +0100
1.2 +++ b/docs/reference.html Wed Feb 24 00:59:37 2010 +0100
1.3 @@ -172,6 +172,46 @@
1.4
1.5 <p>The specified expression is evaluated in the context of the current element.</p>
1.6
1.7 +<h3><a name="sort"></a>template:sort</h3>
1.8 +
1.9 +<p>This attribute imposes a particular ordering on elements retrieved from the
1.10 +XML document being presented based on the expression provided as the value of
1.11 +the attribute. Such an ordering directive only has an effect on sections of the
1.12 +template where a <code>template:element</code> or element traversing annotation
1.13 +(such as a multiple-choice annotation) is in use.</p>
1.14 +
1.15 +<p>Example:</p>
1.16 +
1.17 +<pre>
1.18 +<select template:multiple-choice-field="type,value" name="...">
1.19 + <option template:multiple-choice-value="type-enum,value,selected,template:i18n(text())"
1.20 + template:sort="template:i18n(text())" value="..." />
1.21 +</select>
1.22 +</pre>
1.23 +
1.24 +<p>In this example, the choices will each have a <a href="internationalisation.html">translated</a>
1.25 +label, but it would be desirable to sort these choices according to such labels,
1.26 +instead of sorting them by some other criteria (such as the order in which they
1.27 +are retrieved from a database or the English language order of the labels).
1.28 +Thus, the <code>template:sort</code> annotation is used on the <code>option</code>
1.29 +element, which will be replicated several times to provide all the values, such
1.30 +that the outcome of this replication satisfies the ordering stated by the supplied
1.31 +XPath expression <code>template:i18n(text())</code> evaluated in the context of
1.32 +each of the elements. In other words, the elements will be generated such that
1.33 +their labels are ordered alphabetically.</p>
1.34 +
1.35 +<p>Syntax:</p>
1.36 +
1.37 +<pre>XPath-expression</pre>
1.38 +
1.39 +<p>Related attributes:</p>
1.40 +
1.41 +<ul><li><code>template:element</code></li>
1.42 +<li><code>template:multiple-choice-value</code></li>
1.43 +<li><code>template:multiple-choice-list-value</code></li>
1.44 +<li><code>template:attribute-list-button</code></li>
1.45 +</ul>
1.46 +
1.47 <h2>Initialisation Annotations</h2>
1.48
1.49 <p>The annotation attributes in this section control the initialisation of documents where this is done by the XSLForms toolkit.</p>