XSLTools

Changeset

298:874ef1ca386a
2005-10-09 paulb raw files shortlog changelog graph [project @ 2005-10-09 21:31:06 by paulb] Added missing explanations to the resource documentation. Added a document about template design.
docs/XSLForms-resource.html (file) docs/template-design.html (file)
     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&nbsp;special class-level&nbsp;<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&nbsp;special
    1.11 +class-level&nbsp;<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&nbsp;a
    1.14  template filename&nbsp;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&nbsp;<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&nbsp;<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&nbsp;<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&nbsp;<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&nbsp;<code>get_result</code>
    1.27 @@ -141,7 +147,15 @@
    1.28  elements previously referred to by the selectors.</p><p>The&nbsp;<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&nbsp;<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&nbsp;<code>form</code> object. Given a selector which is associated with a&nbsp;<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&nbsp;<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&nbsp;<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>&lt;?xml version="1.0"?&gt;<br />&lt;html xmlns="http://www.w3.org/1999/xhtml"<br />      xmlns:template="http://www.boddie.org.uk/ns/xmltools/template"&gt;<br />&lt;head&gt;<br />  &lt;title&gt;Some title&lt;/title&gt;<br />&lt;/head&gt;<br />&lt;body template:element="structure"&gt;<br /><br />&lt;!-- The interesting part goes here... --&gt;<br /><br />&lt;/body&gt;<br />&lt;/html&gt;</pre><p>Since we will want to edit the data produced by such a template, an HTML&nbsp;<code>form</code> element is usually necessary within the&nbsp;<code>body</code> element:</p><pre>&lt;body template:element="structure"&gt;<br />&lt;form action="" method="POST"&gt;<br /><br />&lt;!-- The interesting part goes here... --&gt;<br /><br />&lt;/form&gt;<br />&lt;/body&gt;</pre><p>We usually define the&nbsp;<code>method</code> as&nbsp;<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>&lt;div template:element="hard-disks"&gt;<br />  &lt;input template:selector-field="add-hard-disk,hard-disk" type="submit" name="..." value="Add hard disk"/&gt;<br />  &lt;p template:element="hard-disk"&gt;<br />    ...<br />  &lt;/p&gt;<br />&lt;/div&gt;</pre><p>Here, the&nbsp;<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&nbsp;<code>template:init</code> attribute to the annotated template element:</p><pre>&lt;div template:element="hard-disks" template:init="yes"&gt;<br />  ...<br />&lt;/div&gt;</pre><p>See the <a href="reference.html">"Template Attribute Reference"</a> document for more information on the&nbsp;<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>&lt;input template:selector-field="add-hard-disk,hard-disk" type="submit" name="..." value="Add hard disk"/&gt;<br />&lt;p template:element="hard-disk"&gt;<br />  ...<br />&lt;/p&gt;</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&nbsp;<code>template:init</code> attribute on the annotated template element: if the&nbsp;<code>template:init</code> attribute is present, the value of that attribute will determine whether such elements (named in the&nbsp;<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&nbsp;<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&nbsp;<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&nbsp;<code>template:init</code> attribute to have the same effect:</p><pre>&lt;p template:element="hard-disk" template:init="no"&gt;<br />  ...<br />&lt;/p&gt;</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>&lt;input template:selector-field="add-hard-disk,hard-disk" type="submit" name="..." value="Add hard disk"/&gt;</pre><p>As described in the <a href="XSLForms-resource.html">"Using the XSLFormsResource API"</a> document, the above selector (with the name&nbsp;<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>&lt;input template:selector-field="remove-hard-disk" type="submit" name="..." value="Remove hard disk"/&gt;</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>&lt;element attribute="value"/&gt;</pre><p>If we are to permit this value to be edited, we might choose the following template representation:</p><pre>&lt;input template:attribute-field="attribute" name="..." value="..." type="text"/&gt;</pre><p>Note that&nbsp;<code>element</code> is not declared in the above example, although we could also add such an annotation to the&nbsp;<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>&lt;span template:attribute-area="attribute"&gt;some text to be replaced with the value&lt;/span&gt;</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>&lt;input template:attribute-field="attribute" name="..." value="..." type="hidden"/&gt;</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&nbsp;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