paulb@298 | 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
paulb@298 | 2 | <html xmlns="http://www.w3.org/1999/xhtml"><head> |
paulb@298 | 3 | <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> |
paulb@298 | 4 | |
paulb@298 | 5 | <title>Template Design</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> |
paulb@298 | 6 | <link href="styles.css" rel="stylesheet" type="text/css" /></head> |
paulb@298 | 7 | <body> |
paulb@298 | 8 | <h1>Template Design</h1> |
paulb@298 | 9 | <p>The template is a central concept in the XSLForms toolkit: each |
paulb@298 | 10 | template defines the structure of the XML document information being |
paulb@298 | 11 | processed by an application (or a resource within an application), and |
paulb@298 | 12 | each template presents that document information in a form readable by |
paulb@298 | 13 | an application's users.</p><h2>Defining a Structure</h2><p>The relationship between the defined structure and the template itself is described in the <a href="data.html">"Creating Applications: Design the Structure of the Form Data"</a> |
paulb@298 | 14 | document. Typically, one will have in mind a particular structure to be |
paulb@298 | 15 | presented and made editable by the template, and one will begin the |
paulb@298 | 16 | template design process with this structure in mind, although the |
paulb@298 | 17 | structure definition is likely to be modified by decisions made in the |
paulb@298 | 18 | design process and when testing the user interface by using the |
paulb@440 | 19 | application itself.</p><h2>Defining the Presentation</h2><p>Given |
paulb@440 | 20 | a |
paulb@298 | 21 | document structure, one has to think about the most suitable ways of |
paulb@298 | 22 | representing the information in the user interface. The most common |
paulb@440 | 23 | medium for presentation is HTML and its derivatives, and we consider in |
paulb@440 | 24 | this document the different HTML elements available to present |
paulb@440 | 25 | different |
paulb@440 | 26 | "patterns" in a document structure.</p><h3>Multiple Languages and Translations</h3><p>One |
paulb@440 | 27 | presentation issue which is largely separate from the presentation of |
paulb@440 | 28 | the structure of form data involves the use of appropriate languages |
paulb@440 | 29 | for an application's users - this is described in the <a href="internationalisation.html">"Internationalisation"</a> document.</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 |
paulb@298 | 30 | elements, as opposed to collection elements, are elements in the |
paulb@379 | 31 | form data document structure which maintain some kind of organisation or grouping |
paulb@298 | 32 | within a document, but whose presence cannot be edited by the user of |
paulb@298 | 33 | 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> |
paulb@298 | 34 | elements together. We can insist that elements are treated as static |
paulb@393 | 35 | 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 |
paulb@379 | 36 | elements are elements in the form data document structure which represent a |
paulb@298 | 37 | collection of items or objects and whose presence may be edited by the |
paulb@393 | 38 | 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 |
paulb@298 | 39 | elements are treated as collection elements in the document |
paulb@298 | 40 | 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> |
paulb@298 | 41 | attribute) will be created automatically (and thus behave like static |
paulb@298 | 42 | elements) or created dynamically (and thus behave like collection |
paulb@298 | 43 | elements); if the <code>template:init</code> attribute is absent, |
paulb@298 | 44 | the way such elements are treated will depend on other factors, notably |
paulb@393 | 45 | 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> |
paulb@298 | 46 | element; thus, the element is treated as a collection. If we did not |
paulb@298 | 47 | 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, |
paulb@298 | 48 | collection elements do have selector fields providing operations on the |
paulb@393 | 49 | 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> |
paulb@393 | 50 | document.</li></ul><p>Selectors provide a means to select elements in collections |
paulb@298 | 51 | and to request that some operation be performed on those selected |
paulb@298 | 52 | elements. Two common selector types are those concerning the addition |
paulb@393 | 53 | 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>) |
paulb@391 | 54 | could be obtained in the application itself, and the collection of |
paulb@391 | 55 | elements associated with the selector used as a collection of places to |
paulb@391 | 56 | insert new elements into the form data document. Similarly, a |
paulb@298 | 57 | selector which could be used to remove elements from a document could |
paulb@391 | 58 | 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, |
paulb@391 | 59 | such a selector could be obtained in the application, and the |
paulb@393 | 60 | 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 |
paulb@379 | 61 | selectors can be modelled conveniently with buttons, since they may |
paulb@379 | 62 | cause an immediate update to the form data with feedback from the |
paulb@379 | 63 | operation occurring immediately, other form controls can be used to |
paulb@379 | 64 | 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 |
paulb@379 | 65 | a checkbox could be used to mark a particular element in the form data |
paulb@379 | 66 | document as being selected, with the application left to determine what |
paulb@393 | 67 | 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 |
paulb@298 | 68 | simple attribute value is defined to be a value, freely editable set in |
paulb@391 | 69 | an attribute on some element in a document. For example, in the form data document:</p><pre><element attribute="value"/></pre><p>The |
paulb@379 | 70 | following sections describe ways in which the value can be viewed, |
paulb@379 | 71 | edited or changed through the presentation of the attribute in the |
paulb@393 | 72 | 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 |
paulb@379 | 73 | that the element on which the attribute is defined is not declared in |
paulb@379 | 74 | the above example, although we could also add such an annotation to |
paulb@393 | 75 | 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 |
paulb@379 | 76 | attribute values are to be retained and submitted again by the |
paulb@379 | 77 | user, but probably not edited, we need to include them as hidden |
paulb@379 | 78 | elements:</p><pre><input template:attribute-field="attribute" name="..." value="..." type="hidden"/></pre><p>This |
paulb@298 | 79 | keeps the contents of the document intact, but it should be noted that |
paulb@298 | 80 | such values are only uneditable in the way they are presented to |
paulb@298 | 81 | the user, and that a determined user could easily find a way to change |
paulb@393 | 82 | 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, |
paulb@379 | 83 | attributes are used to retain particular values that correspond to a |
paulb@379 | 84 | 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> |
paulb@379 | 85 | in the form data document. Moreover, the presence of the attribute with |
paulb@379 | 86 | such a value would cause the checkbox to appear selected when the form |
paulb@393 | 87 | 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 |
paulb@379 | 88 | checkboxes, radio buttons typically offer a means to select a value |
paulb@379 | 89 | from a number of alternatives. However, like checkboxes the selected |
paulb@379 | 90 | value would be stored on a single attribute in the form data document. |
paulb@379 | 91 | For example:</p><pre><input type="radio" template:attribute-button="attribute,some-choice,checked" name="..." value="..." /></pre><p>This would produce the following HTML form control:</p><p><input name="..." value="..." type="radio" /></p><p>If |
paulb@379 | 92 | selected, the radio button when submitted would cause the attribute to |
paulb@379 | 93 | contain the stated value in the form data document, which would be <code>some-choice</code> |
paulb@379 | 94 | for the button in the above example. Should a different button |
paulb@379 | 95 | associated with the same attribute be pressed, the value stated in the |
paulb@379 | 96 | definition of that button would be stored in the attribute. Like the |
paulb@379 | 97 | checkbox, the selected radio button would remain selected when the form |
paulb@379 | 98 | data is presented to the user again.</p><h3>Attributes Set from Lists of Choices</h3><p>Certain |
paulb@379 | 99 | attributes may have a list of acceptable values associated with them, |
paulb@379 | 100 | and whilst such attributes typically reside in the form data document |
paulb@379 | 101 | carrying a single, currently set value, the representation of the |
paulb@379 | 102 | document processed by the template must somehow incorporate the list of |
paulb@396 | 103 | 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><li>Described in the <a href="multiple.html">"Creating Applications: Adding Multiple-Choice Fields and Values"</a> document.</li></ul><p>In |
paulb@379 | 104 | certain situations, it makes more sense to present acceptable values |
paulb@379 | 105 | for an attribute in a menu-like representation in the final output |
paulb@379 | 106 | presented to the user. With the element on which the attribute resides |
paulb@379 | 107 | now containing a list of sub-elements with each carrying an acceptable |
paulb@379 | 108 | 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 |
paulb@379 | 109 | in the above example, although we could modify the <code>template:multiple-choice-field</code> annotation on |
paulb@396 | 110 | 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><li>Described in the <a href="multivalue.html">"Creating Applications: Adding Multivalued Fields"</a> document.</li></ul><p>In |
paulb@379 | 111 | other situations, where many values can be chosen, a single attribute |
paulb@379 | 112 | on a single element is not sufficient to hold all such values. |
paulb@379 | 113 | Consequently, a collection of elements is employed, each with an |
paulb@379 | 114 | attribute defined to hold a single value. With each value-bearing |
paulb@379 | 115 | element now containing a list of sub-elements with each carrying |
paulb@379 | 116 | an acceptable |
paulb@379 | 117 | value in an attribute, a form control can be defined as follows:</p><pre><select name="..." template:multiple-choice-list-field="-,element-enum,attribute" multiple="multiple"><br /> <option template:multiple-choice-list-value="element-enum,value,selected" value="..."></option><br /></select></pre><p>This would produce the following HTML form control:</p><p><select multiple="multiple" name="..."><option>First</option><option>Second</option><option>Third</option></select></p><p>Note that unlike the single selection menu example, an additional parameter is present in the <code>template:multiple-choice-list-field</code> annotation, but the first parameter is given as the placeholder value <code>-</code> (and is regarded as not having been stated). However, had the first parameter been stated (as opposed to being given as <code>-</code>) |
paulb@379 | 118 | the consequence would merely have been that upon submission of the |
paulb@379 | 119 | form, the elements in the collection would have been enclosed |
paulb@379 | 120 | within a single named element. In the above example, we assume that a |
paulb@379 | 121 | suitable element has already been defined in a template element and |
paulb@379 | 122 | that the above <code>select</code> element resides within that template element, thus providing the necessary enclosure (as recommended in the <a href="advice.html">"Creating Applications: Recommendations and Advice"</a> document).</p></body></html> |