This documentation introduces the XSLTools package and the XSLForms -framework for developing forms-based Web applications using Python, libxml2dom, -libxml2, libxslt and (optionally) WebStack.
+framework for developing forms-based Web applications using Python, libxml2dom, +libxml2, libxslt and (optionally) WebStack. +First of all, let us assume that the XSLTools distribution has been
unpacked and now sits in the XSLTools-0.1 directory.
Before we begin, we must make sure that the XSLTools package is
available
to Python. The easiest way to do this is to change into the XSLTools-0.1
directory and to run the setup.py
script provided with the version of Python you are going to be using
(possibly as a privileged user like root):
cd XSLTools-0.1+
python setup.py install
If you don't want to install XSLTools in this way, or if you can't
do so
because you don't have root privileges, you can just make
sure
that the XSLTools-0.1 directory sits on your
PYTHONPATH.
The API documentation for use in conjunction with this
guide can be found inside the apidocs
directory within the XSLTools-0.1 directory. Of course,
it is always possible to view the API documentation
-within Python by importing modules (such as XSLOutput)
+within Python by importing modules (such as XSLOutput)
and using Python's built-in help function.
In applications based on XSLForms, form data is processed as XML documents as shown in the following diagram:
+| + | Application + Starting with an initial XML document... |
+ XSLForms + A template is used together with the XML document to produce a Web page... |
+ Browser + The Web page contains a form which is filled out by users of the application and submitted back to the application... |
+
|---|---|---|---|
| XSLForms + The incoming form data is converted to an XML document... |
+ Application + The incoming XML document is processed, validated, and so on... |
+ XSLFormsA template is used together with the new XML document to produce a Web page... | +BrowserAn updated Web page is shown to the user. The page may contain a form which may be filled out and submitted... | +
The XSLForms framework therefore performs two main functions:
+The following steps briefly describe how to make a new application:
+
In the previous activity we annotated the template with +structural information, and these annotations should be sufficient in +presenting XML documents as Web pages for users to interact with. +However, in our design, we also wanted to be able to add and remove +list items from the example hierarchy:
+ +What we want to do is to have buttons beside each list item
+(and subitem) which remove only that particular item. In addition, we
+also want buttons which add items only to the particular list each
+button appears beneath.
+
+
+
+
Taking the HTML example from before, we add some additional 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={template:this-position()}" 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={template:this-position()}" type="submit" value="Remove" />
</p>
<p>
<input name="add2={template:this-position()} type="submit" value="Add subitem" />
</p>
</div>
<p>
<input name="add={template:this-position()} type="submit" value="Add item" />
</p>
<!-- Template text between the interesting part and the end. -->
</body>
</html>
Some of the attributes in the original HTML code have been changed:
+ + + +input element for the first Remove button (mapping to item elements in the XML document) has a modified name attribute, containing the special remove={template:this-position()} value.input element for the second Remove button (mapping to subitem elements in the XML document) has a modified name attribute, containing the special remove2={template:this-position()} value.What these amendments provide is a means for the XSLForms framework +to connect together the usage of a button in the Web form with an XML +document element.
+ +Remove button appears within the p element which is annotated as mapping onto the item
+element in the XML document. This means that the special value added
+above will, in the final output, refer to that specific list item from
+the XML document.Remove button appears within the p element which is annotated as mapping onto the subitem
+element in the XML document. This means that the special value added
+above will, in the final output, refer to that specific list (sub)item from
+the XML document.Some additional sections have been added to the original HTML code:
+ +subitem paragraph, containing an input element which employs the special add2={template:this-position()} value in the name attribute to represent an Add subitem button.item section, containing an input element which employs the special add={template:this-position()} value in the name attribute to represent an Add item button.What these amendments provide is also a means for the XSLForms framework to connect these buttons to parts of the XML document.
+ +Add subitem button appears outside the p element mapping onto the subitem element in the XML document. Instead, it appears within the p element mapping onto the item
+element in the XML document. This means that the special value added
+above will, in the final output, refer to a specific item from
+the XML document, and the consequence of adding a subitem will be the extension of that list of subitem elements within that item element.Add item button appears outside the p element mapping onto the item
+element in the XML document. Instead, it appears within the body element mapping onto the top-level structure
+element in the XML document. This means that the special value added
+above will, in the final output, refer to the top-level structure
+element in
+the XML document, and the consequence of adding an item will be the extension of the main list of item elements.Special values of the following form can be used to connect parts of +the template with elements in the XML document representation of a form:
+ + + +selector={template:this-position()}selector in this example),
+this special value produces a reference to an XML document element (or
+attribute) in the final output. The referenced element or attribute is
+defined by those template:element and template:attribute annotations on template elements which surround the template element within which this special value is used.The reference guide provides a complete list of special values for use in template annotations.
+ + + +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:
-In XSLForms applications form data is processed as XML documents.
+ + +Therefore, it becomes important to imagine how we would represent + +
+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"?>+be appropriate: + + +
<item value="some value">
<subitem subvalue="some other value"/>
</item>
<?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:
+ + +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">
<!-- 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. -->
</html>
<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:
+ + +template:element attributes were added to the HTML elements which will be replicated when presenting the final output.template:attribute attributes were added to the form input elements.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.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.
+ + +The following special annotations can be used to describe XML document structures in templates:
+ + +template:elementdiv 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{$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.
+ + +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.
+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. + + + + +