# Continuing from above...
encoding = "utf-8"
The
main purpose of XSLForms is to produce Web page output containing a
visual representation of a form. Therefore, we need to define templates
-(as described in the "Creating Applications: Design a Template" document) to express the representation of each kind of form, along with any intermediate files that may be produced. A special class-level template_resources dictionary is used to hold such definitions.
To
+(as described in the "Creating Applications: Design a Template"
+document) to express the representation of each kind of form, along
+with any intermediate files that may be produced. A special
+class-level template_resources dictionary is used to hold such definitions.
To define a template resource, we first choose a name (which need not have any special significance); we then associate with that name a template filename and an output filename. Finally, we make an @@ -129,7 +132,10 @@ provides convenience functions to add and remove elements.
Sometimes,
there is a need to obtain the "raw" request parameters submitted by the
Web client or browser which sent the form data in to the application.
-Such parameters could be obtained using the trans object, but it is also possible to use the following approach:
parameters = form.get_parameters()
some_parameter = parameters.get("something") # which returns None if no such parameter exists; a list otherwise
another_parameter = parameters.get("another", [""])[0] # which will always return a string, empty if no such parameter was found
To take advantage of the defined transform_resources, we can call a method on the resource itself to prepare such resources:
filter_stylesheets = self.prepare_transform("filter")Then,
+Such parameters could be obtained using the trans object, but it is also possible to use the following approach:
parameters = form.get_parameters()
some_parameter = parameters.get("something") # which returns None if no such parameter exists; a list otherwise
another_parameter = parameters.get("another", [""])[0] # which will always return a string, empty if no such parameter was found
Additional +processing of the form data can be performed in many different ways, +limited only by the DOM-style API exposed by the data and the XSL +transformation features available in the XSLForms toolkit.
To take advantage of the defined transform_resources, we can call a method on the resource itself to prepare such resources:
filter_stylesheets = self.prepare_transform("filter")Then, with the result of this call (a list of stylesheet filenames), we can then perform a transformation on a document, producing a new document from the results:
configuration_document = self.get_result(filter_stylesheets, configuration_document)
This new document is different from the document supplied to the get_result
@@ -141,7 +147,15 @@
elements previously referred to by the selectors.
The get_result
method also supports stylesheet parameters, document references and
stylesheet expressions; these are described in the "Additional
-Stylesheet Parameters" section below.
The initialisation of a document, using information defined in the init_resources
+Stylesheet Parameters" section below.
As
+described above in "Obtain the Form Data Selectors", if the user of an
+application requested changes to the form data using a selector field
+(typically represented by a button or checkbox in a Web page), a list
+of selected elements will be available to the resource through the form object. Given a selector which is associated with a remove
+operation, we could use the DOM-style API exposed by the contents of
+the selectors to perform such an operation in the resource using our
+own code. However, the XSLForms toolkit provides some useful
+convenience functions to assist in the removal or addition of elements:
# After doing this:
# import XSLForms.Utils
# Removing elements...
removed_elements = selectors.get("remove") # this may return None
XSLForms.Utils.remove_elements(removed_elements) # this can handle None, realising that no elements are to be removed
# Adding elements...
places_to_add_elements = selectors.get("add")
XSLForms.Utils.add_elements(places_to_add_elements, "element")
See the XSLForms.Utils documentation for more information on these functions.
The initialisation of a document, using information defined in the init_resources
attribute, is similar to the transformation of a document as described
above. First, we obtain a reference to an initialisation stylesheet:
init_stylesheet = self.prepare_initialiser("configuration")Note that only a single stylesheet is returned. With the result of the call, diff -r ec832ec2315f -r 874ef1ca386a docs/template-design.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/template-design.html Sun Oct 09 21:31:06 2005 +0000 @@ -0,0 +1,58 @@ + +
+ + +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 +here the different HTML elements available to present different +"patterns" in a document structure.
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 +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 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:
<input template:selector-field="add-hard-disk,hard-disk" type="submit" name="..." value="Add hard disk"/>
<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.
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.
As described in the "Creating Applications: Add Selectors" +document, 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"/>
As described in the "Using the XSLFormsResource API" document, the above selector (with the name add-hard-disk)
+could be obtained and the associated collection of elements used to
+insert new elements within the specified elements. 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"/>
Again, such a selector could be obtained and its associated elements removed from the document.
A +simple attribute value is defined to be a value, freely editable set in +an attribute on some element in a document. For example:
<element attribute="value"/>
If we are to permit this value to be edited, we might choose the following template representation:
<input template:attribute-field="attribute" name="..." value="..." type="text"/>
Note that element is not declared in the above example, although we could also add such an annotation to the input element (as described 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>
However, if such values are to be retained and submitted again by the user, we also 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.
\ No newline at end of file