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@298 | 19 | application itself.</p><h2>Defining the Presentation</h2><p>Given a |
paulb@298 | 20 | document structure, one has to think about the most suitable ways of |
paulb@298 | 21 | representing the information in the user interface. The most common |
paulb@298 | 22 | medium for presentation is HTML and its derivatives, and we consider |
paulb@298 | 23 | here the different HTML elements available to present different |
paulb@298 | 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 |
paulb@298 | 25 | elements, as opposed to collection elements, are elements in the |
paulb@298 | 26 | document structure which maintain some kind of organisation or grouping |
paulb@298 | 27 | within a document, but whose presence cannot be edited by the user of |
paulb@298 | 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> |
paulb@298 | 29 | elements together. We can insist that elements are treated as static |
paulb@298 | 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 |
paulb@298 | 31 | elements are elements in the document structure which represent a |
paulb@298 | 32 | collection of items or objects and whose presence may be edited by the |
paulb@298 | 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 |
paulb@298 | 34 | elements are treated as collection elements in the document |
paulb@298 | 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> |
paulb@298 | 36 | attribute) will be created automatically (and thus behave like static |
paulb@298 | 37 | elements) or created dynamically (and thus behave like collection |
paulb@298 | 38 | elements); if the <code>template:init</code> attribute is absent, |
paulb@298 | 39 | the way such elements are treated will depend on other factors, notably |
paulb@298 | 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> |
paulb@298 | 41 | element; thus, the element is treated as a collection. If we did not |
paulb@298 | 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, |
paulb@298 | 43 | collection elements do have selector fields providing operations on the |
paulb@298 | 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> |
paulb@298 | 45 | document, selectors provide a means to select elements in collections |
paulb@298 | 46 | and to request that some operation be performed on those selected |
paulb@298 | 47 | elements. Two common selector types are those concerning the addition |
paulb@298 | 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>) |
paulb@298 | 49 | could be obtained and the associated collection of elements used to |
paulb@298 | 50 | insert new elements within the specified elements. Similarly, a |
paulb@298 | 51 | selector which could be used to remove elements from a document could |
paulb@298 | 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 |
paulb@298 | 53 | simple attribute value is defined to be a value, freely editable set in |
paulb@298 | 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 |
paulb@298 | 55 | keeps the contents of the document intact, but it should be noted that |
paulb@298 | 56 | such values are only uneditable in the way they are presented to |
paulb@298 | 57 | the user, and that a determined user could easily find a way to change |
paulb@298 | 58 | such values and send them in to the application.</p></body></html> |