1.1 --- a/docs/reference.html Wed Oct 05 23:24:40 2005 +0000
1.2 +++ b/docs/reference.html Fri Oct 07 21:13:57 2005 +0000
1.3 @@ -1,27 +1,74 @@
1.4 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.5 <html xmlns="http://www.w3.org/1999/xhtml"><head> <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /><title>Template Attribute Reference</title>
1.6 <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> <link href="styles.css" rel="stylesheet" type="text/css" /></head>
1.7 -
1.8 <body><h1>Template Attribute Reference</h1>
1.9 <p>This document presents each of the attributes used in
1.10 templates to annotate the structure of the XML documents being
1.11 -presented.</p><table width="100%" border="1" cellpadding="5" cellspacing="0"><tbody><tr><th width="15%">Attribute</th><th width="20%">Purpose</th><th width="15%">Parameter
1.12 -Formats</th><th width="20%">Suitable HTML Elements</th><th width="15%">Related
1.13 -Attributes</th><th width="15%">Implementing Attributes</th></tr><tr><td colspan="1" rowspan="2">template:element</td><td colspan="1" rowspan="2">Marks a section corresponding to an
1.14 -element. Many element names can be given to provide a path into the
1.15 -document.</td><td>element-name</td><td colspan="1" rowspan="2">Almost any</td><td colspan="1" rowspan="2"></td><td colspan="1" rowspan="2"></td></tr><tr><td>element-name1,<br />element-name2,<br />...</td></tr><tr><td>template:attribute</td><td>Marks a section
1.16 -corresponding to an attribute.</td><td>attribute-name</td><td>Almost any</td><td></td><td></td></tr><tr><td>template:attribute-field</td><td>Lets a template
1.17 -element support the editing of an attribute by providing name and value
1.18 -attributes on that template element.</td><td>attribute-name</td><td>input (with type
1.19 -"text" or "hidden")</td><td><br /></td><td>template:attribute</td></tr><tr><td colspan="1" rowspan="2">template:attribute-area</td><td colspan="1" rowspan="2">Lets a template element support the
1.20 -editing of an attribute by providing a name attribute on that template
1.21 -element, and by either inserting the value of the attribute inside the
1.22 -template element, or by replacing the template element with
1.23 -the value.</td><td>attribute-name</td><td colspan="1" rowspan="2">textarea</td><td colspan="1" rowspan="2"></td><td colspan="1" rowspan="2">template:attribute<br />template:value<br />template:effect</td></tr><tr><td>attribute-name,<br />
1.24 -"insert" | "replace"</td></tr><tr><td>template:attribute-button</td><td>Provides support
1.25 -for a template element to reflect the presence of an attribute on a
1.26 -single element (having a particular value).</td><td>attribute-name,<br />attribute-value,<br />template-attribute</td><td>input (with type
1.27 -"checkbox" or "radio")</td><td></td><td>template:attribute<br />template:expr<br />template:expr-attr</td></tr><tr><td>template:attribute-list-button</td><td>Provides
1.28 -support for a template element to reflect the presence of an attribute
1.29 -value on one of a collection of elements.</td><td>attribute-name,<br />template-attribute</td><td>input
1.30 -(with type "checkbox" or "radio")</td><td>template:multiple-choice-list-element<br /></td><td>template:attribute<br />template:expr<br />template:expr-attr</td></tr><tr><td colspan="1" rowspan="2">template:selector-field</td><td colspan="1" rowspan="2"></td><td>selector-name<span style="font-style: italic;"></span></td><td colspan="1" rowspan="2">input (with type "submit", "checkbox" or "radio")</td><td colspan="1" rowspan="2">template:element</td><td colspan="1" rowspan="2"></td></tr><tr><td>selector-name,<br />affected-element-name</td></tr><tr><td colspan="1" rowspan="2">template:multiple-choice-field</td><td colspan="1" rowspan="2"></td><td>element-name | "-",<br />attribute-name</td><td colspan="1" rowspan="2">select</td><td colspan="1" rowspan="2">template:multiple-choice-value</td><td colspan="1" rowspan="2">template:element<br />template:attribute</td></tr><tr><td>element-name | "-",<br />attribute-name,<br />"new"</td></tr><tr><td>template:multiple-choice-list-field</td><td></td><td>element-name | "-",<br />list-element-name,<br />list-attribute-name</td><td>select</td><td>template:multiple-choice-list-value</td><td>template:element</td></tr><tr><td>template:multiple-choice-list-element</td><td></td><td>element-name | "-",<br />list-element-name,<br />list-attribute-name</td><td>Almost any</td><td>template:attribute-list-button</td><td>template:element</td></tr><tr><td>template:multiple-choice-value</td><td></td><td>element-name,<br />attribute-name,<br />template-attribute</td><td>option</td><td>template:multiple-choice-field</td><td>template:element<br />template:expr<br />template:expr-attr<br />template:value</td></tr><tr><td>template:multiple-choice-list-value</td><td></td><td>element-name,<br />attribute-name,<br />template-attribute</td><td>option</td><td>template:multiple-choice-list-field</td><td>template:element<br />template:expr<br />template:expr-attr<br />template:value</td></tr></tbody></table></body></html>
1.31 +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>, it is usually preferable to use the annotations listed in the "Convenience Annotations" section below.</p><h3>template:element</h3><p>This
1.32 +attribute associates the template element on which it is used with an
1.33 +element from the XML document being presented. Matching elements are
1.34 +found from the current position (or context), where the position
1.35 +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>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></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>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>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>template:if</h3><p>This
1.36 +attribute permits the inclusion of a section of the template document
1.37 +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.38 +the underlying XPath mechanisms are exposed, and any XPath expression
1.39 +which tests aspects of the XML document can be written.</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>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.40 +means that the initialisation process will attempt to guess whether an
1.41 +element should be created automatically (by looking for selectors which
1.42 +use the element's name and only creating elements where no such
1.43 +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.44 +annotation attributes in this section provide more convenient ways of
1.45 +presenting the XML document information in the final output.</p><h3>template:attribute-field</h3><p>This
1.46 +attribute associates the template element on which it is used with an
1.47 +attribute from the XML document, whilst providing certain other
1.48 +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>template:attribute-area</h3><p>This
1.49 +attribute associates the template element on which it is used with an
1.50 +attribute from the XML document being presented, much in the way
1.51 +that <code>template:attribute-field</code> does. However, the
1.52 +attribute value is not inserted into an attribute in the final output;
1.53 +instead it is inserted into the output in a different way according to
1.54 +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>template:attribute-button</h3><p>This attribute associates the template element on which it is used
1.55 +with an attribute from the XML document, whilst providing certain other
1.56 +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>template:selector-field</h3><p>This
1.57 +attribute permits the definition of references to the parts of the XML
1.58 +document being presented which are associated with the template
1.59 +elements in which it is used. When used in certain HTML form-related
1.60 +elements, it becomes possible to receive and obtain such references
1.61 +from the XSLForms toolkit and to then access the selected parts of the
1.62 +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.63 +optional element name can be used to associate the selector with other
1.64 +elements; when this is done, the initialisation of the XML document
1.65 +will be affected such that the named element will not be automatically
1.66 +created in the initialisation process, since the presence of the
1.67 +selector implies that such elements can be added and removed in the
1.68 +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>template:multiple-choice-field</h3><p>This
1.69 +attribute associates the template element on which it is used with an
1.70 +attribute in the XML document being presented whose value is to be
1.71 +chosen from a list of possibilities. The list itself is represented by
1.72 +a list of elements, each having an attribute with a distinct
1.73 +value; such information is added in the initialisation of the
1.74 +document before it is presented, since it is not part of the
1.75 +"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>]</pre><p>Where the special value <code>-</code>
1.76 +is given as the element name, the context element is chosen as the
1.77 +element in the XML document being presented whose attribute is
1.78 +involved. Where the optional parameter <code>new</code> is given, the attribute is assumed not to already exist on the element.</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>template:multiple-choice-value</h3><p>This
1.79 +attribute associates the template element on which it is used with an
1.80 +element in the XML document being presented whose purpose is to hold
1.81 +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><p>Syntax:</p><pre>list-element-name,list-attribute-name,attribute-to-create-when-selected</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>template:multiple-choice-list-field</h3><p>This attribute is similar to <code>template:multiple-choice-field</code>
1.82 +except that it associates the template element on which it is used with
1.83 +an element in the XML document being presented containing a list
1.84 +of elements whose values have been selected. This list of selected
1.85 +elements is expanded before presentation to include elements whose
1.86 +values have not been selected. Consequently, the selected elements are
1.87 +marked in a particular way to distinguish them from the non-selected
1.88 +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</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-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>template:multiple-choice-list-value</h3><p>This attribute is similar to <code>template:multiple-choice-value</code>
1.89 +in that it associates the template element on which it is used with an
1.90 +element holding a value in a list of selectable values, with the
1.91 +principal difference that potentially many such values may be selected
1.92 +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><p>Syntax:</p><pre>list-element-name,list-attribute-name,attribute-to-create-when-selected</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>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>template:attribute-list-button</h3><p>This attribute works in much the same way as <code>template:attribute-button</code>
1.93 +does, but instead presents a button or related user interface control
1.94 +whose state reflects the presence of an attribute on an element in a
1.95 +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.96 +are used respectively to test an XPath expression in the current
1.97 +context and to provide the name of an attribute which is to be created
1.98 +in the final output, should the expression evaluate to a true value.</p></body></html>
1.99 \ No newline at end of file