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