The template is a central concept in the XSLForms toolkit: each template defines the structure of the XML document information being processed by an application (or a resource within an application), and each template presents that document information in a form readable by an application's users.
The relationship between the defined structure and the template itself is described in the "Creating Applications: Design the Structure of the Form Data" document. Typically, one will have in mind a particular structure to be presented and made editable by the template, and one will begin the template design process with this structure in mind, although the structure definition is likely to be modified by decisions made in the design process and when testing the user interface by using the application itself.
Given a document structure, one has to think about the most suitable ways of representing the information in the user interface. The most common medium for presentation is HTML and its derivatives, and we consider in this document the different HTML elements available to present different "patterns" in a document structure.
One presentation issue which is largely separate from the presentation of the structure of form data involves the use of appropriate languages for an application's users - this is described in the "Internationalisation" document.
Templates based on HTML usually have the following general structure:
<?xml version="1.0"?>
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:template="http://www.boddie.org.uk/ns/xmltools/template">
<head>
<title>Some title</title>
</head>
<body template:element="structure">
<!-- The interesting part goes here... -->
</body>
</html>
Since we will want to edit the data produced by such a template, an HTML form
element is usually necessary within the body
element:
<body template:element="structure">
<form action="" method="POST">
<!-- The interesting part goes here... -->
</form>
</body>
We usually define the method
as post
in order to minimise complications with handling the data in the XSLForms toolkit.
Static elements, as opposed to collection elements, are elements in the form data document structure which maintain some kind of organisation or grouping within a document, but whose presence cannot be edited by the user of an application. For example, in the "Using the XSLFormsResource API" document the following example is given:
<div template:element="hard-disks">
<input template:selector-field="add-hard-disk,hard-disk" type="submit" name="..." value="Add hard disk"/>
<p template:element="hard-disk">
...
</p>
</div>
Here, the hard-disks
element is present to group hard-disk
elements together. We can insist that elements are treated as static
elements in the document initialisation process by adding the template:init
attribute to the annotated template element:
<div template:element="hard-disks" template:init="yes">
...
</div>
See the "Template Attribute Reference" document for more information on the template:init
attribute.
Collection
elements are elements in the form data document structure which represent a
collection of items or objects and whose presence may be edited by the
user of an application. In the following example, hard-disk
elements are collection elements:
<p template:element="hard-disk">
...
</p>
Whether
elements are treated as collection elements in the document
initialisation process depends on the presence or absence of the template:init
attribute on the annotated template element: if the template:init
attribute is present, the value of that attribute will determine whether such elements (named in the template:element
attribute) will be created automatically (and thus behave like static
elements) or created dynamically (and thus behave like collection
elements); if the template:init
attribute is absent,
the way such elements are treated will depend on other factors, notably
the presence of selectors referring to such elements. Here is such a selector:
<input template:selector-field="add-hard-disk,hard-disk" type="submit" name="..." value="Add hard disk"/>
In the above example, the selector field (see below and in the "Template Attribute Reference" document for more details) mentions the document structure's hard-disk
element; thus, the element is treated as a collection. If we did not
have such a selector in the template, we could also have used a template:init
attribute to have the same effect:
<p template:element="hard-disk" template:init="no">
...
</p>
Generally, collection elements do have selector fields providing operations on the collection, and so the extra annotation is not usually necessary.
Selectors provide a means to select elements in collections and to request that some operation be performed on those selected elements. Two common selector types are those concerning the addition and removal of elements.
In the collection elements example above, we saw the usage of a selector which could be used to add elements to a document:
<input template:selector-field="add-hard-disk,hard-disk" type="submit" name="..." value="Add hard disk"/>
This would produce the following HTML form control:
As described in the "Using the XSLFormsResource API" document, the above selector (with the name add-hard-disk
)
could be obtained in the application itself, and the collection of
elements associated with the selector used as a collection of places to
insert new elements into the form data document. Similarly, a
selector which could be used to remove elements from a document could
be specified as follows:
<input template:selector-field="remove-hard-disk" type="submit" name="..." value="Remove hard disk"/>
This would produce the following HTML form control:
Again, such a selector could be obtained in the application, and the associated elements could then be removed from the document.
Whilst selectors can be modelled conveniently with buttons, since they may cause an immediate update to the form data with feedback from the operation occurring immediately, other form controls can be used to communicate the selection of form data. For example:
<input template:selector-field="select-hard-disk" type="checkbox" name="..." value="..."/>
This would produce the following HTML form control:
Such a checkbox could be used to mark a particular element in the form data document as being selected, with the application left to determine what kind of operation should be applied to the selection.
A simple attribute value is defined to be a value, freely editable set in an attribute on some element in a document. For example, in the form data document:
<element attribute="value"/>
The following sections describe ways in which the value can be viewed, edited or changed through the presentation of the attribute in the template.
If we are to permit an attribute value to be edited, we might choose the following template representation:
<input template:attribute-field="attribute" name="..." value="..." type="text"/>
This would produce the following HTML form control:
Note
that the element on which the attribute is defined is not declared in
the above example, although we could also add such an annotation to
the input
element (as described above and in the "Template Attribute Reference" document).
Where attribute values are only displayed, we can use non-form HTML elements to display them:
<span template:attribute-area="attribute">some text to be replaced with the value</span>
This would insert the value of the attribute in the document within the defined span
template element.
Where attribute values are to be retained and submitted again by the user, but probably not edited, we need to include them as hidden elements:
<input template:attribute-field="attribute" name="..." value="..." type="hidden"/>
This keeps the contents of the document intact, but it should be noted that such values are only uneditable in the way they are presented to the user, and that a determined user could easily find a way to change such values and send them in to the application.
Sometimes, attributes are used to retain particular values that correspond to a boolean state. Such values can be modelled as follows:
<input template:attribute-button="attribute,true,checked" name="..." value="..." type="checkbox"/>
This would produce the following HTML form control:
If selected, the checkbox would when submitted cause the attribute to contain the value true
in the form data document. Moreover, the presence of the attribute with
such a value would cause the checkbox to appear selected when the form
data is presented to the user again.
Unlike checkboxes, radio buttons typically offer a means to select a value from a number of alternatives. However, like checkboxes the selected value would be stored on a single attribute in the form data document. For example:
<input type="radio" template:attribute-button="attribute,some-choice,checked" name="..." value="..." />
This would produce the following HTML form control:
If
selected, the radio button when submitted would cause the attribute to
contain the stated value in the form data document, which would be some-choice
for the button in the above example. Should a different button
associated with the same attribute be pressed, the value stated in the
definition of that button would be stored in the attribute. Like the
checkbox, the selected radio button would remain selected when the form
data is presented to the user again.
Certain attributes may have a list of acceptable values associated with them, and whilst such attributes typically reside in the form data document carrying a single, currently set value, the representation of the document processed by the template must somehow incorporate the list of acceptable values; this was covered in the "Creating Applications: Adding Multiple-Choice Fields and Values" document, and involved adding new elements, each carrying a single acceptable value for the attribute concerned.
In certain situations, it makes more sense to present acceptable values for an attribute in a menu-like representation in the final output presented to the user. With the element on which the attribute resides now containing a list of sub-elements with each carrying an acceptable value in an attribute, a form control can be defined as follows:
<select template:multiple-choice-field="-,attribute" name="...">
<option template:multiple-choice-value="element-enum,value,selected" value="..."></option>
</select>
This would produce the following HTML form control:
Note that the element on which the attribute is defined is not declared
in the above example, although we could modify the template:multiple-choice-field
annotation on
the select
element (as described in the "Template Attribute Reference" document) and replace the -
with a name such as element
.
In other situations, where many values can be chosen, a single attribute on a single element is not sufficient to hold all such values. Consequently, a collection of elements is employed, each with an attribute defined to hold a single value. With each value-bearing element now containing a list of sub-elements with each carrying an acceptable value in an attribute, a form control can be defined as follows:
<select name="..." template:multiple-choice-list-field="-,element-enum,attribute" multiple="multiple">
<option template:multiple-choice-list-value="element-enum,value,selected" value="..."></option>
</select>
This would produce the following HTML form control:
Note that unlike the single selection menu example, an additional parameter is present in the template:multiple-choice-list-field
annotation, but the first parameter is given as the placeholder value -
(and is regarded as not having been stated). However, had the first parameter been stated (as opposed to being given as -
)
the consequence would merely have been that upon submission of the
form, the elements in the collection would have been enclosed
within a single named element. In the above example, we assume that a
suitable element has already been defined in a template element and
that the above select
element resides within that template element, thus providing the necessary enclosure (as recommended in the "Creating Applications: Recommendations and Advice" document).