XSLTools

Annotated docs/template-design.html

567:83425ff09945
2007-02-28 paulb [project @ 2007-02-28 23:44:13 by paulb] Added WebStack as a build dependency so that the examples are generated.
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>&lt;?xml version="1.0"?&gt;<br />&lt;html xmlns="http://www.w3.org/1999/xhtml"<br />      xmlns:template="http://www.boddie.org.uk/ns/xmltools/template"&gt;<br />&lt;head&gt;<br />  &lt;title&gt;Some title&lt;/title&gt;<br />&lt;/head&gt;<br />&lt;body template:element="structure"&gt;<br /><br />&lt;!-- The interesting part goes here... --&gt;<br /><br />&lt;/body&gt;<br />&lt;/html&gt;</pre><p>Since we will want to edit the data produced by such a template, an HTML&nbsp;<code>form</code> element is usually necessary within the&nbsp;<code>body</code> element:</p><pre>&lt;body template:element="structure"&gt;<br />&lt;form action="" method="POST"&gt;<br /><br />&lt;!-- The interesting part goes here... --&gt;<br /><br />&lt;/form&gt;<br />&lt;/body&gt;</pre><p>We usually define the&nbsp;<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>&lt;div template:element="hard-disks"&gt;<br />  &lt;input template:selector-field="add-hard-disk,hard-disk" type="submit" name="..." value="Add hard disk"/&gt;<br />  &lt;p template:element="hard-disk"&gt;<br />    ...<br />  &lt;/p&gt;<br />&lt;/div&gt;</pre><p>Here, the&nbsp;<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&nbsp;<code>template:init</code> attribute to the annotated template element:</p><pre>&lt;div template:element="hard-disks" template:init="yes"&gt;<br />  ...<br />&lt;/div&gt;</pre><p>See the <a href="reference.html">"Template Attribute Reference"</a> document for more information on the&nbsp;<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>&lt;p template:element="hard-disk"&gt;<br />  ...<br />&lt;/p&gt;</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&nbsp;<code>template:init</code> attribute on the annotated template element: if the&nbsp;<code>template:init</code> attribute is present, the value of that attribute will determine whether such elements (named in the&nbsp;<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&nbsp;<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>&lt;input template:selector-field="add-hard-disk,hard-disk" type="submit" name="..." value="Add hard disk"/&gt;</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&nbsp;<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&nbsp;<code>template:init</code> attribute to have the same effect:</p><pre>&lt;p template:element="hard-disk" template:init="no"&gt;<br />  ...<br />&lt;/p&gt;</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>&lt;input template:selector-field="add-hard-disk,hard-disk" type="submit" name="..." value="Add hard disk"/&gt;</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&nbsp;<code>add-hard-disk</code>)
paulb@391 54
could be obtained in the application itself, and the&nbsp;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>&lt;input template:selector-field="remove-hard-disk" type="submit" name="..." value="Remove hard disk"/&gt;</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>&lt;input template:selector-field="select-hard-disk" type="checkbox" name="..." value="..."/&gt;</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>&lt;element attribute="value"/&gt;</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>&lt;input template:attribute-field="attribute" name="..." value="..." type="text"/&gt;</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&nbsp;<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>&lt;span template:attribute-area="attribute"&gt;some text to be replaced with the value&lt;/span&gt;</pre><p>This would insert the value of the attribute in the document within the defined&nbsp;<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&nbsp;are to be retained and submitted again by the
paulb@379 77
user, but probably not edited, we&nbsp;need to include them as hidden
paulb@379 78
elements:</p><pre>&lt;input template:attribute-field="attribute" name="..." value="..." type="hidden"/&gt;</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&nbsp;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>&lt;input template:attribute-button="attribute,true,checked" name="..." value="..." type="checkbox"/&gt;</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&nbsp;<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>&lt;input type="radio" template:attribute-button="attribute,some-choice,checked" name="..." value="..." /&gt;</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&nbsp;<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&nbsp;Menus</h4><ul><li>See <a href="reference.html#multiple-choice-field">"template:multiple-choice-field"</a> and&nbsp;<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>&lt;select template:multiple-choice-field="-,attribute" name="..."&gt;<br />  &lt;option template:multiple-choice-value="element-enum,value,selected" value="..."&gt;&lt;/option&gt;<br />&lt;/select&gt;</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&nbsp;<code>template:multiple-choice-field</code> annotation on
paulb@396 110
the <code>select</code> element (as described&nbsp;in the <a href="reference.html">"Template Attribute Reference"</a> document) and replace the&nbsp;<code>-</code> with a name such as&nbsp;<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&nbsp;<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&nbsp;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>&lt;select name="..." template:multiple-choice-list-field="-,element-enum,attribute" multiple="multiple"&gt;<br />  &lt;option template:multiple-choice-list-value="element-enum,value,selected" value="..."&gt;&lt;/option&gt;<br />&lt;/select&gt;</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&nbsp;<code>template:multiple-choice-list-field</code> annotation, but the first parameter is given as the placeholder value&nbsp;<code>-</code> (and is regarded as not having been stated). However, had the first parameter been stated (as opposed to being given as&nbsp;<code>-</code>)
paulb@379 118
the consequence would merely have been that upon submission of the
paulb@379 119
form, the&nbsp;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&nbsp;<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>