1.1 --- a/docs/XSLForms-resource.html Fri Nov 21 01:43:03 2008 +0100
1.2 +++ b/docs/XSLForms-resource.html Fri Nov 21 01:43:30 2008 +0100
1.3 @@ -11,7 +11,7 @@
1.4 from this class, <code>XSLFormsResource</code>,
1.5 you can derive your own application-specific resources and use the
1.6 class's API to obtain, manipulate and present form data. Although the
1.7 -supplied <a href="../apidocs/index.html">API documentation</a> provides details of the class's API, specifically in the <code><a href="../apidocs/public/XSLForms.Resources.WebResources-module.html">XSLForms.Resources.WebResources</a></code><a href="../apidocs/public/XSLForms.Resources.WebResources-module.html"></a> module, this document attempts to explain how the API is used in practice.</p><h2>Resource Structure</h2><p>The structure of a Web resource derived from <code>XSLFormsResource</code> should look like this:</p><pre>class MyResource(XSLForms.Resources.WebResources.XSLFormsResource):<br /><br /> [Resource definitions]<br /><br /> def respond_to_form(self, trans, form):<br /> [Examine the form data, see if the user has added or removed anything.]<br /> [Perform additional processing and initialise the form data.]<br /> [Produce some kind of response to show the user the updated form data.]</pre><p>Since <code>XSLFormsResource</code> builds on WebStack's resource mechanisms, we do have the transaction object, <code>trans</code>, available. However, most of the information we need to access and manipulate is generally available through the <code>form</code> object.</p><h2>Defining Resources</h2><p>Classes derived from <code>XSLFormsResource</code>
1.8 +supplied <a href="../apidocs/index.html">API documentation</a> provides details of the class's API, specifically in the <code><a href="../apidocs/XSLForms.Resources.WebResources-module.html">XSLForms.Resources.WebResources</a></code><a href="../apidocs/XSLForms.Resources.WebResources-module.html"></a> module, this document attempts to explain how the API is used in practice.</p><h2>Resource Structure</h2><p>The structure of a Web resource derived from <code>XSLFormsResource</code> should look like this:</p><pre>class MyResource(XSLForms.Resources.WebResources.XSLFormsResource):<br /><br /> [Resource definitions]<br /><br /> def respond_to_form(self, trans, form):<br /> [Examine the form data, see if the user has added or removed anything.]<br /> [Perform additional processing and initialise the form data.]<br /> [Produce some kind of response to show the user the updated form data.]</pre><p>Since <code>XSLFormsResource</code> builds on WebStack's resource mechanisms, we do have the transaction object, <code>trans</code>, available. However, most of the information we need to access and manipulate is generally available through the <code>form</code> object.</p><h2>Defining Resources</h2><p>Classes derived from <code>XSLFormsResource</code>
1.9 support the concept of resources which are used to produce output,
1.10 support processing and to provide access to useful information. At the
1.11 class level it is essential to define at least some of these resources
1.12 @@ -109,7 +109,7 @@
1.13 use the identifier in the above example together with <code>config_template.xhtml</code>, we would have to ensure that the identifier appeared as a value of an <code>id</code>
1.14 node in that template document. Note that the choice of template
1.15 document is not defined here, but is instead made when handling an
1.16 -in-page update request.</p><h2>Examining the Form Data</h2><p>The form data is available through the <code>form</code> object which exposes the <code><a href="../apidocs/public/XSLForms.Fields.Form-class.html">XSLForms.Fields.Form</a></code> API. The most interesting operations are as follows:</p><h3>Obtain the Form Data Documents</h3><p>Since
1.17 +in-page update request.</p><h2>Examining the Form Data</h2><p>The form data is available through the <code>form</code> object which exposes the <code><a href="../apidocs/XSLForms.Fields.Form-class.html">XSLForms.Fields.Form</a></code> API. The most interesting operations are as follows:</p><h3>Obtain the Form Data Documents</h3><p>Since
1.18 XSLForms is an XML-based toolkit, the form data is available as XML
1.19 documents which can be accessed and manipulated using a DOM-style API.
1.20 Upon receiving submitted form data, XSLForms converts the data to such
1.21 @@ -155,7 +155,7 @@
1.22 operation, we could use the DOM-style API exposed by the contents of
1.23 the selectors to perform such an operation in the resource using our
1.24 own code. However, the XSLForms toolkit provides some useful
1.25 -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.26 +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/XSLForms.Utils-module.html">XSLForms.Utils</a></code><a href="../apidocs/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.27 attribute, is similar to the transformation of a document as described
1.28 above. First, we obtain a reference to an initialisation stylesheet:</p><pre>init_stylesheet = self.prepare_initialiser("configuration")</pre><p>Note
1.29 that only a single stylesheet is returned. With the result of the call,