1.1 --- a/docs/XSLForms-resource.html Sun Oct 09 00:50:07 2005 +0000
1.2 +++ b/docs/XSLForms-resource.html Sun Oct 09 21:31:06 2005 +0000
1.3 @@ -30,7 +30,10 @@
1.4 follows:</p><pre> # Continuing from above...<br /><br /> encoding = "utf-8"</pre><h3>Template Resources</h3><p>The
1.5 main purpose of XSLForms is to produce Web page output containing a
1.6 visual representation of a form. Therefore, we need to define templates
1.7 -(as described in the <a href="design.html">"Creating Applications: Design a Template"</a> document) to express the representation of each kind of form, along with any intermediate files that may be produced. A special class-level <code>template_resources</code> dictionary is used to hold such definitions.</p><p>To
1.8 +(as described in the <a href="design.html">"Creating Applications: Design a Template"</a>
1.9 +document) to express the representation of each kind of form, along
1.10 +with any intermediate files that may be produced. A special
1.11 +class-level <code>template_resources</code> dictionary is used to hold such definitions.</p><p>To
1.12 define a template resource, we first choose a name (which need not have
1.13 any special significance); we then associate with that name a
1.14 template filename and an output filename. Finally, we make an
1.15 @@ -129,7 +132,10 @@
1.16 provides convenience functions to add and remove elements.</p><h3>Obtaining Other Parameters</h3><p>Sometimes,
1.17 there is a need to obtain the "raw" request parameters submitted by the
1.18 Web client or browser which sent the form data in to the application.
1.19 -Such parameters could be obtained using the <code>trans</code> object, but it is also possible to use the following approach:</p><pre>parameters = form.get_parameters()<br />some_parameter = parameters.get("something") # which returns None if no such parameter exists; a list otherwise<br />another_parameter = parameters.get("another", [""])[0] # which will always return a string, empty if no such parameter was found</pre><h2>Performing Additional Processing</h2><p>To take advantage of the defined <code>transform_resources</code>, we can call a method on the resource itself to prepare such resources:</p><pre>filter_stylesheets = self.prepare_transform("filter")</pre><p>Then,
1.20 +Such parameters could be obtained using the <code>trans</code> object, but it is also possible to use the following approach:</p><pre>parameters = form.get_parameters()<br />some_parameter = parameters.get("something") # which returns None if no such parameter exists; a list otherwise<br />another_parameter = parameters.get("another", [""])[0] # which will always return a string, empty if no such parameter was found</pre><h2>Performing Additional Processing</h2><p>Additional
1.21 +processing of the form data can be performed in many different ways,
1.22 +limited only by the DOM-style API exposed by the data and the XSL
1.23 +transformation features available in the XSLForms toolkit.</p><h3>Transformations</h3><p>To take advantage of the defined <code>transform_resources</code>, we can call a method on the resource itself to prepare such resources:</p><pre>filter_stylesheets = self.prepare_transform("filter")</pre><p>Then,
1.24 with the result of this call (a list of stylesheet filenames), we can
1.25 then perform a transformation on a document, producing a new document
1.26 from the results:</p><pre>configuration_document = self.get_result(filter_stylesheets, configuration_document)</pre><p>This new document is different from the document supplied to the <code>get_result</code>
1.27 @@ -141,7 +147,15 @@
1.28 elements previously referred to by the selectors.</p><p>The <code>get_result</code>
1.29 method also supports stylesheet parameters, document references and
1.30 stylesheet expressions; these are described in the "Additional
1.31 -Stylesheet Parameters" section below.</p><h2>Document Initialisation</h2><p>The initialisation of a document, using information defined in the <code>init_resources</code>
1.32 +Stylesheet Parameters" section below.</p><h3>Using Selectors to Modify the Data</h3><p>As
1.33 +described above in "Obtain the Form Data Selectors", if the user of an
1.34 +application requested changes to the form data using a selector field
1.35 +(typically represented by a button or checkbox in a Web page), a list
1.36 +of selected elements will be available to the resource through the <code>form</code> object. Given a selector which is associated with a <code>remove</code>
1.37 +operation, we could use the DOM-style API exposed by the contents of
1.38 +the selectors to perform such an operation in the resource using our
1.39 +own code. However, the XSLForms toolkit provides some useful
1.40 +convenience functions to assist in the removal or addition of elements:</p><pre># After doing this:<br /># import XSLForms.Utils<br /><br /># Removing elements...<br /><br />removed_elements = selectors.get("remove") # this may return None<br />XSLForms.Utils.remove_elements(removed_elements) # this can handle None, realising that no elements are to be removed<br /><br /># Adding elements...<br /><br />places_to_add_elements = selectors.get("add")<br />XSLForms.Utils.add_elements(places_to_add_elements, "element")</pre><p>See the <code><a href="../apidocs/public/XSLForms.Utils-module.html">XSLForms.Utils</a></code><a href="../apidocs/public/XSLForms.Utils-module.html"></a> documentation for more information on these functions.<br /></p><h2>Document Initialisation</h2><p>The initialisation of a document, using information defined in the <code>init_resources</code>
1.41 attribute, is similar to the transformation of a document as described
1.42 above. First, we obtain a reference to an initialisation stylesheet:</p><pre>init_stylesheet = self.prepare_initialiser("configuration")</pre><p>Note
1.43 that only a single stylesheet is returned. With the result of the call,
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/docs/template-design.html Sun Oct 09 21:31:06 2005 +0000
2.3 @@ -0,0 +1,58 @@
2.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2.5 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
2.6 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
2.7 +
2.8 + <title>Template Design</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
2.9 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
2.10 +<body>
2.11 +<h1>Template Design</h1>
2.12 +<p>The template is a central concept in the XSLForms toolkit: each
2.13 +template defines the structure of the XML document information being
2.14 +processed by an application (or a resource within an application), and
2.15 +each template presents that document information in a form readable by
2.16 +an application's users.</p><h2>Defining a Structure</h2><p>The relationship between the defined structure and the template itself is described in the <a href="data.html">"Creating Applications: Design the Structure of the Form Data"</a>
2.17 +document. Typically, one will have in mind a particular structure to be
2.18 +presented and made editable by the template, and one will begin the
2.19 +template design process with this structure in mind, although the
2.20 +structure definition is likely to be modified by decisions made in the
2.21 +design process and when testing the user interface by using the
2.22 +application itself.</p><h2>Defining the Presentation</h2><p>Given a
2.23 +document structure, one has to think about the most suitable ways of
2.24 +representing the information in the user interface. The most common
2.25 +medium for presentation is HTML and its derivatives, and we consider
2.26 +here the different HTML elements available to present different
2.27 +"patterns" in a document structure.</p><h3>General Template Structure</h3><p>Templates based on HTML usually have the following general structure:</p><pre><?xml version="1.0"?><br /><html xmlns="http://www.w3.org/1999/xhtml"<br /> xmlns:template="http://www.boddie.org.uk/ns/xmltools/template"><br /><head><br /> <title>Some title</title><br /></head><br /><body template:element="structure"><br /><br /><!-- The interesting part goes here... --><br /><br /></body><br /></html></pre><p>Since we will want to edit the data produced by such a template, an HTML <code>form</code> element is usually necessary within the <code>body</code> element:</p><pre><body template:element="structure"><br /><form action="" method="POST"><br /><br /><!-- The interesting part goes here... --><br /><br /></form><br /></body></pre><p>We usually define the <code>method</code> as <code>POST</code> in order to minimise complications with handling the data in the XSLForms toolkit.</p><h3>Static Elements</h3><p>Static
2.28 +elements, as opposed to collection elements, are elements in the
2.29 +document structure which maintain some kind of organisation or grouping
2.30 +within a document, but whose presence cannot be edited by the user of
2.31 +an application. For example, in the <a href="XSLForms-resource.html">"Using the XSLFormsResource API"</a> document the following example is given:</p><pre><div template:element="hard-disks"><br /> <input template:selector-field="add-hard-disk,hard-disk" type="submit" name="..." value="Add hard disk"/><br /> <p template:element="hard-disk"><br /> ...<br /> </p><br /></div></pre><p>Here, the <code>hard-disks</code> element is present to group <code>hard-disk</code>
2.32 +elements together. We can insist that elements are treated as static
2.33 +elements in the document initialisation process by adding the <code>template:init</code> attribute to the annotated template element:</p><pre><div template:element="hard-disks" template:init="yes"><br /> ...<br /></div></pre><p>See the <a href="reference.html">"Template Attribute Reference"</a> document for more information on the <code>template:init</code> attribute.</p><h3>Collection Elements</h3><p>Collection
2.34 +elements are elements in the document structure which represent a
2.35 +collection of items or objects and whose presence may be edited by the
2.36 +user of an application. In the following example, <code>hard-disk</code> elements are collection elements:</p><pre><input template:selector-field="add-hard-disk,hard-disk" type="submit" name="..." value="Add hard disk"/><br /><p template:element="hard-disk"><br /> ...<br /></p></pre><p>Whether
2.37 +elements are treated as collection elements in the document
2.38 +initialisation process depends on the presence or absence of the <code>template:init</code> attribute on the annotated template element: if the <code>template:init</code> attribute is present, the value of that attribute will determine whether such elements (named in the <code>template:element</code>
2.39 +attribute) will be created automatically (and thus behave like static
2.40 +elements) or created dynamically (and thus behave like collection
2.41 +elements); if the <code>template:init</code> attribute is absent,
2.42 +the way such elements are treated will depend on other factors, notably
2.43 +the presence of selectors referring to such elements.</p><p>In the above example, the selector field (see below and in the <a href="reference.html">"Template Attribute Reference"</a> document for more details) mentions the document structure's <code>hard-disk</code>
2.44 +element; thus, the element is treated as a collection. If we did not
2.45 +have such a selector in the template, we could also have used a <code>template:init</code> attribute to have the same effect:</p><pre><p template:element="hard-disk" template:init="no"><br /> ...<br /></p></pre><p>Generally,
2.46 +collection elements do have selector fields providing operations on the
2.47 +collection, and so the extra annotation is not usually necessary.</p><h3>Selectors</h3><p>As described in the <a href="selectors.html">"Creating Applications: Add Selectors"</a>
2.48 +document, selectors provide a means to select elements in collections
2.49 +and to request that some operation be performed on those selected
2.50 +elements. Two common selector types are those concerning the addition
2.51 +and removal of elements.</p><p>In the collection elements example above, we saw the usage of a selector which could be used to add elements to a document:</p><pre><input template:selector-field="add-hard-disk,hard-disk" type="submit" name="..." value="Add hard disk"/></pre><p>As described in the <a href="XSLForms-resource.html">"Using the XSLFormsResource API"</a> document, the above selector (with the name <code>add-hard-disk</code>)
2.52 +could be obtained and the associated collection of elements used to
2.53 +insert new elements within the specified elements. Similarly, a
2.54 +selector which could be used to remove elements from a document could
2.55 +be specified as follows:</p><pre><input template:selector-field="remove-hard-disk" type="submit" name="..." value="Remove hard disk"/></pre><p>Again, such a selector could be obtained and its associated elements removed from the document.</p><h3>Simple Attribute Values</h3><p>A
2.56 +simple attribute value is defined to be a value, freely editable set in
2.57 +an attribute on some element in a document. For example:</p><pre><element attribute="value"/></pre><p>If we are to permit this value to be edited, we might choose the following template representation:</p><pre><input template:attribute-field="attribute" name="..." value="..." type="text"/></pre><p>Note that <code>element</code> is not declared in the above example, although we could also add such an annotation to the <code>input</code> element (as described in the <a href="reference.html">"Template Attribute Reference"</a> document).</p><h4>Read-only Values</h4><p>Where attribute values are only displayed, we can use non-form HTML elements to display them:</p><pre><span template:attribute-area="attribute">some text to be replaced with the value</span></pre><p>However, if such values are to be retained and submitted again by the user, we also need to include them as hidden elements:</p><pre><input template:attribute-field="attribute" name="..." value="..." type="hidden"/></pre><p>This
2.58 +keeps the contents of the document intact, but it should be noted that
2.59 +such values are only uneditable in the way they are presented to
2.60 +the user, and that a determined user could easily find a way to change
2.61 +such values and send them in to the application.</p></body></html>
2.62 \ No newline at end of file