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,