1.1 --- a/docs/template-design.html Wed Nov 09 17:41:12 2005 +0000
1.2 +++ b/docs/template-design.html Wed Nov 09 17:41:35 2005 +0000
1.3 @@ -21,65 +21,65 @@
1.4 representing the information in the user interface. The most common
1.5 medium for presentation is HTML and its derivatives, and we consider
1.6 here the different HTML elements available to present different
1.7 -"patterns" in a document structure.</p><h3>General Template Structure</h3><p>Templates based on HTML usually have the following general structure:</p><pre><?xml version="1.0"?><br /><html xmlns="http://www.w3.org/1999/xhtml"<br /> xmlns:template="http://www.boddie.org.uk/ns/xmltools/template"><br /><head><br /> <title>Some title</title><br /></head><br /><body template:element="structure"><br /><br /><!-- The interesting part goes here... --><br /><br /></body><br /></html></pre><p>Since we will want to edit the data produced by such a template, an HTML <code>form</code> element is usually necessary within the <code>body</code> element:</p><pre><body template:element="structure"><br /><form action="" method="POST"><br /><br /><!-- The interesting part goes here... --><br /><br /></form><br /></body></pre><p>We usually define the <code>method</code> as <code>post</code> in order to minimise complications with handling the data in the XSLForms toolkit.</p><h3>Static Elements</h3><p>Static
1.8 +"patterns" in a document structure.</p><h3>General Template Structure</h3><ul><li>Described in the <a href="design.html">"Creating Applications: Design a Template"</a> document.</li></ul><p>Templates based on HTML usually have the following general structure:</p><pre><?xml version="1.0"?><br /><html xmlns="http://www.w3.org/1999/xhtml"<br /> xmlns:template="http://www.boddie.org.uk/ns/xmltools/template"><br /><head><br /> <title>Some title</title><br /></head><br /><body template:element="structure"><br /><br /><!-- The interesting part goes here... --><br /><br /></body><br /></html></pre><p>Since we will want to edit the data produced by such a template, an HTML <code>form</code> element is usually necessary within the <code>body</code> element:</p><pre><body template:element="structure"><br /><form action="" method="POST"><br /><br /><!-- The interesting part goes here... --><br /><br /></form><br /></body></pre><p>We usually define the <code>method</code> as <code>post</code> in order to minimise complications with handling the data in the XSLForms toolkit.</p><h3>Static Elements</h3><ul><li>See <a href="reference.html#element">"template:element"</a> in the <a href="reference.html">"Template Attribute Reference"</a> document.</li></ul><p>Static
1.9 elements, as opposed to collection elements, are elements in the
1.10 form data document structure which maintain some kind of organisation or grouping
1.11 within a document, but whose presence cannot be edited by the user of
1.12 an application. For example, in the <a href="XSLForms-resource.html">"Using the XSLFormsResource API"</a> document the following example is given:</p><pre><div template:element="hard-disks"><br /> <input template:selector-field="add-hard-disk,hard-disk" type="submit" name="..." value="Add hard disk"/><br /> <p template:element="hard-disk"><br /> ...<br /> </p><br /></div></pre><p>Here, the <code>hard-disks</code> element is present to group <code>hard-disk</code>
1.13 elements together. We can insist that elements are treated as static
1.14 -elements in the document initialisation process by adding the <code>template:init</code> attribute to the annotated template element:</p><pre><div template:element="hard-disks" template:init="yes"><br /> ...<br /></div></pre><p>See the <a href="reference.html">"Template Attribute Reference"</a> document for more information on the <code>template:init</code> attribute.</p><h3>Collection Elements</h3><p>Collection
1.15 +elements in the document initialisation process by adding the <code>template:init</code> attribute to the annotated template element:</p><pre><div template:element="hard-disks" template:init="yes"><br /> ...<br /></div></pre><p>See the <a href="reference.html">"Template Attribute Reference"</a> document for more information on the <code>template:init</code> attribute.</p><h3>Collection Elements</h3><ul><li>See <a href="reference.html#element">"template:element"</a> in the <a href="reference.html">"Template Attribute Reference"</a> document.</li><li>Described in the <a href="structure.html#AnnotatingTheTemplate">"Annotating the Template"</a> section of the <a href="design.html">"Creating Applications: Design a Template"</a> document.</li></ul><p>Collection
1.16 elements are elements in the form data document structure which represent a
1.17 collection of items or objects and whose presence may be edited by the
1.18 -user of an application. In the following example, <code>hard-disk</code> elements are collection elements:</p><pre><input template:selector-field="add-hard-disk,hard-disk" type="submit" name="..." value="Add hard disk"/><br /><p template:element="hard-disk"><br /> ...<br /></p></pre><p>Whether
1.19 +user of an application. In the following example, <code>hard-disk</code> elements are collection elements:</p><pre><p template:element="hard-disk"><br /> ...<br /></p></pre><p>Whether
1.20 elements are treated as collection elements in the document
1.21 initialisation process depends on the presence or absence of the <code>template:init</code> attribute on the annotated template element: if the <code>template:init</code> attribute is present, the value of that attribute will determine whether such elements (named in the <code>template:element</code>
1.22 attribute) will be created automatically (and thus behave like static
1.23 elements) or created dynamically (and thus behave like collection
1.24 elements); if the <code>template:init</code> attribute is absent,
1.25 the way such elements are treated will depend on other factors, notably
1.26 -the presence of selectors referring to such elements.</p><p>In the above example, the selector field (see below and in the <a href="reference.html">"Template Attribute Reference"</a> document for more details) mentions the document structure's <code>hard-disk</code>
1.27 +the presence of selectors referring to such elements. Here is such a selector:</p><pre><input template:selector-field="add-hard-disk,hard-disk" type="submit" name="..." value="Add hard disk"/></pre><p>In the above example, the selector field (see below and in the <a href="reference.html">"Template Attribute Reference"</a> document for more details) mentions the document structure's <code>hard-disk</code>
1.28 element; thus, the element is treated as a collection. If we did not
1.29 have such a selector in the template, we could also have used a <code>template:init</code> attribute to have the same effect:</p><pre><p template:element="hard-disk" template:init="no"><br /> ...<br /></p></pre><p>Generally,
1.30 collection elements do have selector fields providing operations on the
1.31 -collection, and so the extra annotation is not usually necessary.</p><h3>Selectors</h3><p>As described in the <a href="selectors.html">"Creating Applications: Add Selectors"</a>
1.32 -document, selectors provide a means to select elements in collections
1.33 +collection, and so the extra annotation is not usually necessary.</p><h3>Selectors</h3><ul><li>Described in the <a href="selectors.html">"Creating Applications: Add Selectors"</a>
1.34 +document.</li></ul><p>Selectors provide a means to select elements in collections
1.35 and to request that some operation be performed on those selected
1.36 elements. Two common selector types are those concerning the addition
1.37 -and removal of elements.</p><h4>Selectors as Buttons</h4><p>In the collection elements example above, we saw the usage of a selector which could be used to add elements to a document:</p><pre><input template:selector-field="add-hard-disk,hard-disk" type="submit" name="..." value="Add hard disk"/></pre><p>This would produce the following HTML form control:</p><p><input name="..." value="Add hard disk" type="submit" /> </p><p>As described in the <a href="XSLForms-resource.html">"Using the XSLFormsResource API"</a> document, the above selector (with the name <code>add-hard-disk</code>)
1.38 +and removal of elements.</p><h4>Selectors as Buttons</h4><ul><li>See <a href="reference.html#selector-field">"template:selector-field"</a> in the <a href="reference.html">"Template Attribute Reference"</a> document.</li></ul><p>In the collection elements example above, we saw the usage of a selector which could be used to add elements to a document:</p><pre><input template:selector-field="add-hard-disk,hard-disk" type="submit" name="..." value="Add hard disk"/></pre><p>This would produce the following HTML form control:</p><p><input name="..." value="Add hard disk" type="submit" /> </p><p>As described in the <a href="XSLForms-resource.html">"Using the XSLFormsResource API"</a> document, the above selector (with the name <code>add-hard-disk</code>)
1.39 could be obtained in the application itself, and the collection of
1.40 elements associated with the selector used as a collection of places to
1.41 insert new elements into the form data document. Similarly, a
1.42 selector which could be used to remove elements from a document could
1.43 be specified as follows:</p><pre><input template:selector-field="remove-hard-disk" type="submit" name="..." value="Remove hard disk"/></pre><p>This would produce the following HTML form control:</p><p><input name="..." value="Remove hard disk" type="submit" /></p><p>Again,
1.44 such a selector could be obtained in the application, and the
1.45 -associated elements could then be removed from the document.</p><h4>Selectors as Checkboxes</h4><p>Whilst
1.46 +associated elements could then be removed from the document.</p><h4>Selectors as Checkboxes</h4><ul><li>See <a href="reference.html#selector-field">"template:selector-field"</a> in the <a href="reference.html">"Template Attribute Reference"</a> document.</li></ul><p>Whilst
1.47 selectors can be modelled conveniently with buttons, since they may
1.48 cause an immediate update to the form data with feedback from the
1.49 operation occurring immediately, other form controls can be used to
1.50 communicate the selection of form data. For example:</p><pre><input template:selector-field="select-hard-disk" type="checkbox" name="..." value="..."/></pre><p>This would produce the following HTML form control:</p><p><input name="..." value="..." type="checkbox" /></p><p>Such
1.51 a checkbox could be used to mark a particular element in the form data
1.52 document as being selected, with the application left to determine what
1.53 -kind of operation should be applied to the selection.</p><h3>Attribute Values</h3><p>A
1.54 +kind of operation should be applied to the selection.</p><h3>Attribute Values</h3><ul><li>See <a href="reference.html#attribute">"template:attribute"</a> in the <a href="reference.html">"Template Attribute Reference"</a> document.</li></ul><p>A
1.55 simple attribute value is defined to be a value, freely editable set in
1.56 an attribute on some element in a document. For example, in the form data document:</p><pre><element attribute="value"/></pre><p>The
1.57 following sections describe ways in which the value can be viewed,
1.58 edited or changed through the presentation of the attribute in the
1.59 -template.</p><h4>Editable Fields</h4><p>If we are to permit an attribute value to be edited, we might choose the following template representation:</p><pre><input template:attribute-field="attribute" name="..." value="..." type="text"/></pre><p>This would produce the following HTML form control:</p><p><input name="..." value="..." /></p><p>Note
1.60 +template.</p><h4>Editable Fields</h4><ul><li>See <a href="reference.html#attribute-field">"template:attribute-field"</a> in the <a href="reference.html">"Template Attribute Reference"</a> document.</li></ul><p>If we are to permit an attribute value to be edited, we might choose the following template representation:</p><pre><input template:attribute-field="attribute" name="..." value="..." type="text"/></pre><p>This would produce the following HTML form control:</p><p><input name="..." value="..." /></p><p>Note
1.61 that the element on which the attribute is defined is not declared in
1.62 the above example, although we could also add such an annotation to
1.63 -the <code>input</code> element (as described above and in the <a href="reference.html">"Template Attribute Reference"</a> document).</p><h4>Read-only Values</h4><p>Where attribute values are only displayed, we can use non-form HTML elements to display them:</p><pre><span template:attribute-area="attribute">some text to be replaced with the value</span></pre><p>This would insert the value of the attribute in the document within the defined <code>span</code> template element.</p><h4>Hidden Values</h4><p>Where
1.64 +the <code>input</code> element (as described above and in the <a href="reference.html">"Template Attribute Reference"</a> document).</p><h4>Read-only Values</h4><ul><li>See <a href="reference.html#attribute-area">"template:attribute-area"</a> in the <a href="reference.html">"Template Attribute Reference"</a> document.</li></ul><p>Where attribute values are only displayed, we can use non-form HTML elements to display them:</p><pre><span template:attribute-area="attribute">some text to be replaced with the value</span></pre><p>This would insert the value of the attribute in the document within the defined <code>span</code> template element.</p><h4>Hidden Values</h4><ul><li>See <a href="reference.html#attribute-field">"template:attribute-field"</a> in the <a href="reference.html">"Template Attribute Reference"</a> document.</li></ul><p>Where
1.65 attribute values are to be retained and submitted again by the
1.66 user, but probably not edited, we need to include them as hidden
1.67 elements:</p><pre><input template:attribute-field="attribute" name="..." value="..." type="hidden"/></pre><p>This
1.68 keeps the contents of the document intact, but it should be noted that
1.69 such values are only uneditable in the way they are presented to
1.70 the user, and that a determined user could easily find a way to change
1.71 -such values and send them in to the application.</p><h4>Checkboxes</h4><p>Sometimes,
1.72 +such values and send them in to the application.</p><h4>Checkboxes</h4><ul><li>See <a href="reference.html#attribute-button">"template:attribute-button"</a> in the <a href="reference.html">"Template Attribute Reference"</a> document.</li></ul><p>Sometimes,
1.73 attributes are used to retain particular values that correspond to a
1.74 boolean state. Such values can be modelled as follows:</p><pre><input template:attribute-button="attribute,true,checked" name="..." value="..." type="checkbox"/></pre><p>This would produce the following HTML form control:</p><p><input name="..." value="..." type="checkbox" /></p><p>If selected, the checkbox would when submitted cause the attribute to contain the value <code>true</code>
1.75 in the form data document. Moreover, the presence of the attribute with
1.76 such a value would cause the checkbox to appear selected when the form
1.77 -data is presented to the user again.</p><h4>Radio Buttons</h4><p>Unlike
1.78 +data is presented to the user again.</p><h4>Radio Buttons</h4><ul><li>See <a href="reference.html#attribute-button">"template:attribute-button"</a> in the <a href="reference.html">"Template Attribute Reference"</a> document.</li></ul><p>Unlike
1.79 checkboxes, radio buttons typically offer a means to select a value
1.80 from a number of alternatives. However, like checkboxes the selected
1.81 value would be stored on a single attribute in the form data document.
1.82 @@ -95,14 +95,14 @@
1.83 and whilst such attributes typically reside in the form data document
1.84 carrying a single, currently set value, the representation of the
1.85 document processed by the template must somehow incorporate the list of
1.86 -acceptable values; this was covered in the <a href="multiple.html">"Creating Applications: Adding Multiple-Choice Fields and Values"</a> document, and involved adding new elements, each carrying a single acceptable value for the attribute concerned.</p><h4>Single Selection Menus</h4><p>In
1.87 +acceptable values; this was covered in the <a href="multiple.html">"Creating Applications: Adding Multiple-Choice Fields and Values"</a> document, and involved adding new elements, each carrying a single acceptable value for the attribute concerned.</p><h4>Single Selection Menus</h4><ul><li>See <a href="reference.html#multiple-choice-field">"template:multiple-choice-field"</a> and <a href="reference.html#multiple-choice-value">"template:multiple-choice-value"</a> in the <a href="reference.html">"Template Attribute Reference"</a> document.</li></ul><p>In
1.88 certain situations, it makes more sense to present acceptable values
1.89 for an attribute in a menu-like representation in the final output
1.90 presented to the user. With the element on which the attribute resides
1.91 now containing a list of sub-elements with each carrying an acceptable
1.92 value in an attribute, a form control can be defined as follows:</p><pre><select template:multiple-choice-field="-,attribute" name="..."><br /> <option template:multiple-choice-value="element-enum,value,selected" value="..."></option><br /></select></pre><p>This would produce the following HTML form control:</p><p><select name="..."><option>First</option><option>Second</option><option>Third</option></select></p><p>Note that the element on which the attribute is defined is not declared
1.93 in the above example, although we could modify the <code>template:multiple-choice-field</code> annotation on
1.94 -the <code>select</code> element (as described in the <a href="reference.html">"Template Attribute Reference"</a> document) and replace the <code>-</code> with a name such as <code>element</code>.</p><h4>Multiple Selection Lists</h4><p>In
1.95 +the <code>select</code> element (as described in the <a href="reference.html">"Template Attribute Reference"</a> document) and replace the <code>-</code> with a name such as <code>element</code>.</p><h4>Multiple Selection Lists</h4><ul><li>See <a href="reference.html#multiple-choice-list-field">"template:multiple-choice-list-field"</a> and <a href="reference.html#multiple-choice-list-value">"template:multiple-choice-list-value"</a> in the <a href="reference.html">"Template Attribute Reference"</a> document.</li></ul><p>In
1.96 other situations, where many values can be chosen, a single attribute
1.97 on a single element is not sufficient to hold all such values.
1.98 Consequently, a collection of elements is employed, each with an