Creating Applications: Add Structure

During the design activity, it was necessary to consider the structure of the information being presented. In proper XSLForms templates, we make such structural information explicit by adding special attributes to the HTML code. Consider the hierarchy example presented in the previous activity:

Since XSLForms is all about the processing of form data as simple XML documents, it becomes important to imagine how we would represent the data described above as an XML document; something like this might be appropriate:

<?xml version="1.0"?>
<structure>
<item value="some value">
<subitem subvalue="some other value"/>
</item>
</structure>

Therefore, we must seek to add the following structural information to our HTML code:

What we must do is to find a way to describe how our template will map onto the form data and present it as a Web page for the purpose of user interaction.

Annotating the Template

Taking the HTML example from before, we add special annotations to the template to produce something like this:

<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:template="http://www.boddie.org.uk/ns/xmltools/template">
<head>
<title>Example</title>
</head>
<body template:element="structure">

<!-- Template text between the start and the interesting part. -->

<div template:element="item">
<p>
Some item: <input template:attribute="value" name="{template:field-name()}" type="text" value="{$this-value}" />
<input name="remove" type="submit" value="Remove" />
</p>
<p>
Itself containing more items:
</p>
<p template:element="subitem">
Sub-item: <input template:attribute="subvalue" name="{template:field-name()}" type="text" value="{$this-value}" />
<input name="remove2" type="submit" value="Remove" />
</p>
</div>

<!-- Template text between the interesting part and the end. -->

</body>
</html>

The following annotations have been added:

In addition, some of the attributes in the original HTML code have been changed:

Whereas the first set of annotations reproduce the desired structure, the latter modifications are really housekeeping measures to make sure that the final output contains the correct names and values for each of the form fields shown to the user.

Basic Template Annotation

The following special annotations can be used to describe XML document structures in templates:

template:element
This attribute should be added to an element in the template in order to mark that element and its contents as mapping onto or representing an element in the XML document version of the form. In the example, the div element is annotated with this attribute to indicate that it maps onto the item element in the XML document version of the form. It is possible to specify more than one name as the value for a template:element attribute by separating each name with a comma; for example:
<div template:element="parent,child">
<p>This is a child element in the XML document version of the form.</p>
</div>
The meaning of this is that the annotated element maps onto all child elements within all parent elements in the XML document version of the form. In other words, instead of having to create separate HTML elements in the template for each XML document element being represented, we can collapse the annotations into a single template:element attribute on a single HTML element.
template:attribute
This attribute should be added to an element in the template in order to mark that element and its contents as mapping onto  or representing an attribute in the XML document version of the form. The template:attribute annotation exposes various special values which are described below - such value insert dynamic content from the XML document version of the form into the final output generated from the template.
{$this-value}
This special value should be used in HTML attributes where the value of an attribute from the XML document version of the form is to be included or presented in the final output. In the example, the value and subvalue attributes are presented in the value attributes of the HTML input elements in this way.
{template:field-name()}
This special value should be used in HTML attributes where the name of an attribute from the XML document version of the form is to be included or presented in the final output.

The reference guide provides a complete list of special values for use in template annotations.

Whilst the above annotations permit the template to display the data in XML documents containing form data, the other aspects of the user interface - the addition and removal of items and subitems - are not yet modelled in the template. These things will be added to the template as selectors as part of the next activity in the development process.