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 a 20 document structure, one has to think about the most suitable ways of 21 representing the information in the user interface. The most common 22 medium for presentation is HTML and its derivatives, and we consider 23 here the different HTML elements available to present different 24 "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 25 elements, as opposed to collection elements, are elements in the 26 document structure which maintain some kind of organisation or grouping 27 within a document, but whose presence cannot be edited by the user of 28 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> 29 elements together. We can insist that elements are treated as static 30 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 31 elements are elements in the document structure which represent a 32 collection of items or objects and whose presence may be edited by the 33 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 34 elements are treated as collection elements in the document 35 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> 36 attribute) will be created automatically (and thus behave like static 37 elements) or created dynamically (and thus behave like collection 38 elements); if the <code>template:init</code> attribute is absent, 39 the way such elements are treated will depend on other factors, notably 40 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> 41 element; thus, the element is treated as a collection. If we did not 42 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, 43 collection elements do have selector fields providing operations on the 44 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> 45 document, selectors provide a means to select elements in collections 46 and to request that some operation be performed on those selected 47 elements. Two common selector types are those concerning the addition 48 and removal of elements.</p><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>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>) 49 could be obtained and the associated collection of elements used to 50 insert new elements within the specified elements. Similarly, a 51 selector which could be used to remove elements from a document could 52 be specified as follows:</p><pre><input template:selector-field="remove-hard-disk" type="submit" name="..." value="Remove hard disk"/></pre><p>Again, such a selector could be obtained and its associated elements removed from the document.</p><h3>Simple Attribute Values</h3><p>A 53 simple attribute value is defined to be a value, freely editable set in 54 an attribute on some element in a document. For example:</p><pre><element attribute="value"/></pre><p>If we are to permit this value to be edited, we might choose the following template representation:</p><pre><input template:attribute-field="attribute" name="..." value="..." type="text"/></pre><p>Note that <code>element</code> is not declared in the above example, although we could also add such an annotation to the <code>input</code> element (as described 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>However, if such values are to be retained and submitted again by the user, we also need to include them as hidden elements:</p><pre><input template:attribute-field="attribute" name="..." value="..." type="hidden"/></pre><p>This 55 keeps the contents of the document intact, but it should be noted that 56 such values are only uneditable in the way they are presented to 57 the user, and that a determined user could easily find a way to change 58 such values and send them in to the application.</p></body></html>
