1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/template-design.html Sun Oct 09 21:31:06 2005 +0000
1.3 @@ -0,0 +1,58 @@
1.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.5 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
1.6 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
1.7 +
1.8 + <title>Template Design</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.9 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
1.10 +<body>
1.11 +<h1>Template Design</h1>
1.12 +<p>The template is a central concept in the XSLForms toolkit: each
1.13 +template defines the structure of the XML document information being
1.14 +processed by an application (or a resource within an application), and
1.15 +each template presents that document information in a form readable by
1.16 +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>
1.17 +document. Typically, one will have in mind a particular structure to be
1.18 +presented and made editable by the template, and one will begin the
1.19 +template design process with this structure in mind, although the
1.20 +structure definition is likely to be modified by decisions made in the
1.21 +design process and when testing the user interface by using the
1.22 +application itself.</p><h2>Defining the Presentation</h2><p>Given a
1.23 +document structure, one has to think about the most suitable ways of
1.24 +representing the information in the user interface. The most common
1.25 +medium for presentation is HTML and its derivatives, and we consider
1.26 +here the different HTML elements available to present different
1.27 +"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.28 +elements, as opposed to collection elements, are elements in the
1.29 +document structure which maintain some kind of organisation or grouping
1.30 +within a document, but whose presence cannot be edited by the user of
1.31 +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.32 +elements together. We can insist that elements are treated as static
1.33 +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.34 +elements are elements in the document structure which represent a
1.35 +collection of items or objects and whose presence may be edited by the
1.36 +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.37 +elements are treated as collection elements in the document
1.38 +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.39 +attribute) will be created automatically (and thus behave like static
1.40 +elements) or created dynamically (and thus behave like collection
1.41 +elements); if the <code>template:init</code> attribute is absent,
1.42 +the way such elements are treated will depend on other factors, notably
1.43 +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.44 +element; thus, the element is treated as a collection. If we did not
1.45 +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.46 +collection elements do have selector fields providing operations on the
1.47 +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.48 +document, selectors provide a means to select elements in collections
1.49 +and to request that some operation be performed on those selected
1.50 +elements. Two common selector types are those concerning the addition
1.51 +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>)
1.52 +could be obtained and the associated collection of elements used to
1.53 +insert new elements within the specified elements. Similarly, a
1.54 +selector which could be used to remove elements from a document could
1.55 +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
1.56 +simple attribute value is defined to be a value, freely editable set in
1.57 +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
1.58 +keeps the contents of the document intact, but it should be noted that
1.59 +such values are only uneditable in the way they are presented to
1.60 +the user, and that a determined user could easily find a way to change
1.61 +such values and send them in to the application.</p></body></html>
1.62 \ No newline at end of file