# HG changeset patch # User paulb # Date 1121776263 0 # Node ID 370ce9bb485a1c0a816ea4146f41e18d043cd5dc # Parent 5ab7f2a80fd145cc53ebda08884b6d425909e711 [project @ 2005-07-19 12:31:03 by paulb] Improved the structure annotation document. diff -r 5ab7f2a80fd1 -r 370ce9bb485a docs/structure.html --- a/docs/structure.html Tue Jul 19 00:20:03 2005 +0000 +++ b/docs/structure.html Tue Jul 19 12:31:03 2005 +0000 @@ -1,364 +1,87 @@
- - - - - - - - - - - - - - - - - - - - - - - - -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:
- - - - +Earlier, we defined the structure of the form +data, and during the template design +activity, it was +necessary to consider this structure information and how it should be +presented. +In XSLForms templates, we need to explicitly connect such information +about the structure of the data to the HTML elements representing it by +adding special attributes to the HTML code.
+Consider the interesting parts of the template side by side with +the structure information:
+<structure> <body>+
<item <div>
<p>
value="some value"> Some item: <input name="value" type="text" value="some value" />
<input name="remove" type="submit" value="Remove" />
</p>
<p>
Itself containing more items:
</p>
<subitem <p>
subvalue="some other value"/> Sub-item: <input name="subvalue" type="text" value="some other value" />
<input name="remove2" type="submit" value="Remove" />
</p>
<p>
<input name="add2" type="submit" value="Add subitem" />
</p>
</item> </div>
<p>
<input name="add" type="submit" value="Add item" />
</p>
</structure> </body>
To make such connections, we will annotate the HTML code using +special attributes and values.
item
.value
.subitem
.subvalue
.structure
.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.
-
-
-
-
-
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">
<form action="" method="POST">
<!-- Template text between the start and the interesting part. -->
<div template:element="item">
<p>
<span template:attribute="value">
Some item: <input name="{template:field-name()}" type="text" value="{$this-value}" />
</span>
<input name="remove" type="submit" value="Remove" />
</p>
<p>
Itself containing more items:
</p>
<p template:element="subitem">
<span template:attribute="subvalue">
Sub-item: <input name="{template:field-name()}" type="text" value="{$this-value}" />
</span>
<input name="remove2" type="submit" value="Remove" />
</p>
</div>
<!-- Template text between the interesting part and the end. -->
</form>
</body>
</html>
The following annotations have been added:
- - - - +Taking the template extract from above, we add special annotations +to produce something like this:
+<structure> <body template:element="structure">+
<item <div template:element="item">
<p>
value="some value"> 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>
<subitem <p template:element="subitem">
subvalue="some other value"/> Sub-item: <input template:attribute="subvalue" name="{template:field-name()}" type="text" value="{$this-value}" />
<input name="remove2" type="submit" value="Remove" />
</p>
<p>
<input name="add2" type="submit" value="Add subitem" />
</p>
</item> </div>
<p>
<input name="add" type="submit" value="Add item" />
</p>
</structure> </body>
+The following annotations have been added:
template:element
attributes were added to the HTML elements which will be replicated when presenting the final output.template:attribute
attributes were added to some new HTML span
elements.template:element
+attributes have been added to the corresponding HTML elements in the
+template.template:attribute
+attributes have been added to the corresponding HTML elements
+in the template.
In addition, some of the attributes in the original HTML code have been changed:
- - - - +In addition, some of the attributes in the original HTML code have +been changed:
input
elements' name
attributes have been redefined to use the special {template:field-name()}
value.input
elements' value
attributes have been redefined to use the special {$this-value}
value.input
elements' name
+attributes have been redefined to use the special {template:field-name()}
+value.input
elements' value
+attributes have been redefined to use the special {$this-value}
+value.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.
-Note also that a namespace declaration is required for the template
attributes, and it is usually best to put this declaration on the top-level html
element in the template.
The following special annotations can be used to describe XML document structures in templates:
- - - - -template:element
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>
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
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}
value
and subvalue
attributes are presented in the value
attributes of the HTML input
elements in this way.{template:field-name()}
The reference guide provides a complete list of special values for use in template annotations.
- - - - -The template in full should now look something like this:
+<?xml version="1.0"?>+
<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">
<form action="" method="POST">
<!-- 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>
<p>
<input name="add2" type="submit" value="Add subitem" />
</p>
</div>
<p>
<input name="add" type="submit" value="Add item" />
</p>
<!-- Template text between the interesting part and the end. -->
</form>
</body>
</html>
Note also that a namespace declaration is required for the template
+attributes, and it is usually best to put this declaration on the
+top-level html
element in the template, as shown in
+the above example code.
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.
- - - - - - - +yet fully modelled in the template. These things will be added to the +template as selectors as part of the +next activity in the development process.