1.1 --- a/docs/XSLForms-resource.html Sat Sep 08 16:53:18 2007 +0000
1.2 +++ b/docs/XSLForms-resource.html Sat Sep 08 16:53:34 2007 +0000
1.3 @@ -1,17 +1,17 @@
1.4 +<?xml version="1.0" encoding="iso-8859-1"?>
1.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.6 <html xmlns="http://www.w3.org/1999/xhtml"><head>
1.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
1.8 -
1.9 - <title>Using the XSLFormsResource API</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.10 + <title>Using the XSLFormsResource API</title>
1.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
1.12 <body>
1.13 <h1>Using the XSLFormsResource API</h1>
1.14 -<p>The XSLForms toolkit provides a special WebStack resource class (described in the <a href="Web-resource.html">"Creating Applications: Write a Web Resource"</a>
1.15 -document), and
1.16 -from this class, <code>XSLFormsResource</code>,
1.17 +<p>The XSLForms toolkit provides a special WebStack resource class (described in the <a href="Web-resource.html">"Creating Applications: Write a Web Resource"</a>
1.18 +document), and
1.19 +from this class, <code>XSLFormsResource</code>,
1.20 you can derive your own application-specific resources and use the
1.21 class's API to obtain, manipulate and present form data. Although the
1.22 -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.23 +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.24 support the concept of resources which are used to produce output,
1.25 support processing and to provide access to useful information. At the
1.26 class level it is essential to define at least some of these resources
1.27 @@ -22,8 +22,8 @@
1.28 a Directory"</a> document). Consequently, it is the convention that all resource classes define such information as follows:</p><pre>class ConfiguratorResource(XSLForms.Resources.WebResources.XSLFormsResource):<br /><br /> resource_dir = os.path.join(os.path.split(__file__)[0], "Resources")</pre><p>All
1.29 filenames, defined in the various resource sections (as described
1.30 below) must be stated without leading path information - in other
1.31 -words, as "leafnames" rather than "pathnames". Thus, an example of
1.32 -an incorrect filename would be <code>/home/paulb/templates/my_template.xhtml</code>, whereas an example of a correct filename would be just <code>my_template.xhtml</code> when correcting the incorrect example.<br /></p><h3>Character Encoding</h3><p>It
1.33 +words, as "leafnames" rather than "pathnames". Thus, an example of
1.34 +an incorrect filename would be <code>/home/paulb/templates/my_template.xhtml</code>, whereas an example of a correct filename would be just <code>my_template.xhtml</code> when correcting the incorrect example.<br /></p><h3>Character Encoding</h3><p>It
1.35 is also the convention to define the character encoding of the output
1.36 produced by an application and the way ambiguous or
1.37 insufficiently-specified input should be interpreted; this is done as
1.38 @@ -32,13 +32,13 @@
1.39 visual representation of a form. Therefore, we need to define templates
1.40 (as described in the <a href="design.html">"Creating Applications: Design a Template"</a>
1.41 document) to express the representation of each kind of form, along
1.42 -with any intermediate files that may be produced. A special
1.43 -class-level <code>template_resources</code> dictionary is used to hold such definitions.</p><p>To
1.44 +with any intermediate files that may be produced. A special
1.45 +class-level <code>template_resources</code> dictionary is used to hold such definitions.</p><p>To
1.46 define a template resource, we first choose a name (which need not have
1.47 -any special significance); we then associate with that name a
1.48 -template filename and an output filename. Finally, we make an
1.49 +any special significance); we then associate with that name a
1.50 +template filename and an output filename. Finally, we make an
1.51 entry for the name and its associated details in the special
1.52 -class-level <code>template_resources</code> dictionary as follows:</p><pre> # Continuing from above...<br /><br /> template_resources = {<br /> "configuration" : ("config_template.xhtml", "config_output.xsl"),<br /> # More entries go here...<br /> }</pre><p>The purpose
1.53 +class-level <code>template_resources</code> dictionary as follows:</p><pre> # Continuing from above...<br /><br /> template_resources = {<br /> "configuration" : ("config_template.xhtml", "config_output.xsl"),<br /> # More entries go here...<br /> }</pre><p>The purpose
1.54 of the output filename is to define where the intermediate
1.55 output-producing stylesheet is to be written, since the template itself
1.56 is not actually used to produce output, but knowing where the
1.57 @@ -60,20 +60,20 @@
1.58 the input filename provides firm information about the location of the
1.59 stylesheet which actually performs the initialisation process.</p><h3>Document Resources</h3><p>Since
1.60 it is the XSLForms convention to access files using a simple name, any
1.61 -other document resources should be defined in the <code>document_resources</code>
1.62 +other document resources should be defined in the <code>document_resources</code>
1.63 dictionary at the class level. Such document resources may be used in
1.64 the initialisation process or in other transformations (as described
1.65 below), and are defined as entries mapping names to filenames such as
1.66 in the following example:</p><pre> # Continuing from above...<br /><br /> document_resources = {<br /> "accessories" : "config_accessories.xml",<br /> "base-system" : "config_base_system.xml",<br /> # More entries go here...<br /> }</pre><p>There is no particular limitation on the types of files which can be referenced in the <code>document_resources</code>
1.67 dictionary, nor any insistence in the XSLForms toolkit to define such
1.68 files as resources - the dictionary is merely a convenience for
1.69 -accessing files in the resources directory.</p><h3>Transform Resources</h3><p>It is sometimes the case that initialisation of a document
1.70 +accessing files in the resources directory.</p><h3>Transform Resources</h3><p>It is sometimes the case that initialisation of a document
1.71 is not sufficient and that additional processing needs to be done.
1.72 Whilst various techniques exist for the processing of XML-based
1.73 information, since XSLForms is part of a wider toolkit based on XSL
1.74 transformations, it seems reasonable to provide certain facilities for
1.75 the usage of such transformations. Thus, stylesheet processing
1.76 -pipelines may be defined at the class level in the <code>transform_resources</code> dictionary.</p><p>Entries in the <code>transform_resources</code>
1.77 +pipelines may be defined at the class level in the <code>transform_resources</code> dictionary.</p><p>Entries in the <code>transform_resources</code>
1.78 dictionary map simple names (which need not have any special
1.79 significance) to collections of stylesheet filenames as in the
1.80 following example:</p><pre> # Continuing from above...<br /><br /> transform_resources = {<br /> "filter" : ["filter.xsl"],<br /> # More entries go here...<br /> }</pre><p>Where
1.81 @@ -91,7 +91,7 @@
1.82 part of the Web page to generate as output. Consequently, the
1.83 application has to have some kind of record of the different kinds of
1.84 updates and the corresponding parts of the whole page template to use,
1.85 -and this information is recorded in the class-level <code>in_page_resources</code> dictionary.</p><p>The form of an entry in the <code>in_page_resources</code>
1.86 +and this information is recorded in the class-level <code>in_page_resources</code> dictionary.</p><p>The form of an entry in the <code>in_page_resources</code>
1.87 dictionary is that of a mapping from a name identifying the kind of
1.88 update to the details of the part of the template to be employed in
1.89 producing the final output for the update: an intermediate filename
1.90 @@ -100,16 +100,16 @@
1.91 template. Here is an example of an in-page resource definition:</p><pre> # Continuing from above...<br /><br /> in_page_resources = {<br /> "cpu" : ("config_output_cpu.xsl", "cpu-node"),<br /> # More entries go here...<br /> }</pre><h4>Update Names</h4><p>It
1.92 is important to note that, unlike other resources, the name identifying
1.93 the kind of update is significant: consider an application available at
1.94 -the following location:</p><pre>http://localhost/configurator/</pre><p>An in-page update called <code>cpu</code> would be accessed through the following location:</p><pre>http://localhost/configurator/cpu</pre><p>Thus,
1.95 +the following location:</p><pre>http://localhost/configurator/</pre><p>An in-page update called <code>cpu</code> would be accessed through the following location:</p><pre>http://localhost/configurator/cpu</pre><p>Thus,
1.96 the availability of such an update "service" depends on the proper
1.97 configuration of the Web application to let such updates be handled by
1.98 the resource.</p><h4>Update Nodes</h4><p>The node identifier mentioned
1.99 in an in-page update resource definition must be a valid node
1.100 identifier in the whole page template document. Thus, if we wished to
1.101 -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.102 +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.103 node in that template document. Note that the choice of template
1.104 document is not defined here, but is instead made when handling an
1.105 -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.106 +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.107 XSLForms is an XML-based toolkit, the form data is available as XML
1.108 documents which can be accessed and manipulated using a DOM-style API.
1.109 Upon receiving submitted form data, XSLForms converts the data to such
1.110 @@ -122,46 +122,46 @@
1.111 it is likely that we will want to work with such a document regardless
1.112 of whether one existed before - we must after all prepare such a
1.113 document in the first place in order to show it to the user and have it
1.114 -submitted back to us - we really want to create it if it does not exist:</p><pre>if documents.has_key("items"):<br /> items = documents["items"]<br />else:<br /> items = form.new_document("items")</pre><p>The resulting <code>items</code> object is a genuine DOM-style document containing the form data.</p><h3>Obtain the Form Data Selectors</h3><p>As described in the <a href="selectors.html">"Creating Applications: Add Selectors"</a>
1.115 +submitted back to us - we really want to create it if it does not exist:</p><pre>if documents.has_key("items"):<br /> items = documents["items"]<br />else:<br /> items = form.new_document("items")</pre><p>The resulting <code>items</code> object is a genuine DOM-style document containing the form data.</p><h3>Obtain the Form Data Selectors</h3><p>As described in the <a href="selectors.html">"Creating Applications: Add Selectors"</a>
1.116 document, XSLForms templates may define selectors - special form fields
1.117 which select parts of the form data documents and make those parts
1.118 available to applications; such selector information can be obtained as
1.119 -follows:</p><pre>selectors = form.get_selectors()</pre><p>If a selector was defined with the name <code>remove</code>, then any selected elements that are associated with this selector may be obtained as follows:</p><pre>removed_elements = selectors.get("remove") # which will return None if no such selector was defined</pre><p>Since
1.120 +follows:</p><pre>selectors = form.get_selectors()</pre><p>If a selector was defined with the name <code>remove</code>, then any selected elements that are associated with this selector may be obtained as follows:</p><pre>removed_elements = selectors.get("remove") # which will return None if no such selector was defined</pre><p>Since
1.121 the collection contains DOM-style elements, various XML libraries and
1.122 tools may be used to manipulate the data. However, XSLForms also
1.123 provides convenience functions to add and remove elements.</p><h3>Obtaining Other Parameters</h3><p>Sometimes,
1.124 there is a need to obtain the "raw" request parameters submitted by the
1.125 Web client or browser which sent the form data in to the application.
1.126 -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.127 +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.128 processing of the form data can be performed in many different ways,
1.129 limited only by the DOM-style API exposed by the data and the XSL
1.130 -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.131 +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.132 with the result of this call (a list of stylesheet filenames), we can
1.133 then perform a transformation on a document, producing a new document
1.134 -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.135 +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.136 method. It should therefore be noted that any references to elements in
1.137 the old document will not affect the new document; thus selectors
1.138 -previously obtained from the <code>form</code> object will not refer to elements in the new document. However, by setting the new document in the <code>form</code> object, new selectors may be obtained referring to elements in the new document:</p><pre>form.set_document("configuration", configuration_document)<br />selectors = form.get_selectors()</pre><p>Care
1.139 +previously obtained from the <code>form</code> object will not refer to elements in the new document. However, by setting the new document in the <code>form</code> object, new selectors may be obtained referring to elements in the new document:</p><pre>form.set_document("configuration", configuration_document)<br />selectors = form.get_selectors()</pre><p>Care
1.140 must be taken doing this, however, since the selectors may now not
1.141 refer to valid elements - the transformation may have removed or moved
1.142 -elements previously referred to by the selectors.</p><p>The <code>get_result</code>
1.143 +elements previously referred to by the selectors.</p><p>The <code>get_result</code>
1.144 method also supports stylesheet parameters, document references and
1.145 stylesheet expressions; these are described in the "Additional
1.146 Stylesheet Parameters" section below.</p><h3>Using Selectors to Modify the Data</h3><p>As
1.147 described above in "Obtain the Form Data Selectors", if the user of an
1.148 application requested changes to the form data using a selector field
1.149 (typically represented by a button or checkbox in a Web page), a list
1.150 -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.151 +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.152 operation, we could use the DOM-style API exposed by the contents of
1.153 the selectors to perform such an operation in the resource using our
1.154 own code. However, the XSLForms toolkit provides some useful
1.155 -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.156 +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.157 attribute, is similar to the transformation of a document as described
1.158 above. First, we obtain a reference to an initialisation stylesheet:</p><pre>init_stylesheet = self.prepare_initialiser("configuration")</pre><p>Note
1.159 that only a single stylesheet is returned. With the result of the call,
1.160 we then perform a transformation similar to the above activity,
1.161 although we have to supply the returned stylesheet in a list to be
1.162 -compatible with the <code>get_result</code> method:</p><pre>configuration_document = self.get_result([init_stylesheet], configuration_document)</pre><p>In practice, the above call will probably not suffice: if <a href="multiple.html">multiple-choice fields</a>
1.163 +compatible with the <code>get_result</code> method:</p><pre>configuration_document = self.get_result([init_stylesheet], configuration_document)</pre><p>In practice, the above call will probably not suffice: if <a href="multiple.html">multiple-choice fields</a>
1.164 are used in the template, there will be a need to initialise such
1.165 elements using references to other documents containing the values of
1.166 such fields; for example:</p><pre>configuration_document = self.get_result([init_stylesheet], configuration_document,<br /> references={<br /> "cpu" : self.prepare_document("cpu")<br /> })</pre><p>The
1.167 @@ -170,27 +170,27 @@
1.168 the examples supplied with XSLTools, the content type is generally
1.169 defined as that of XHTML, meaning that the resulting output should be
1.170 accessible to most modern Web browsers. When writing resources based
1.171 -on <code>XSLFormsResource</code>, we can just use the WebStack API to set the content type:</p><pre>trans.set_content_type(WebStack.Generic.ContentType("application/xhtml+xml", self.encoding))</pre><p>Note that the <code>encoding</code> attribute is used here to make the character encoding clear to the user's Web browser or client.</p><h3>Defining an Output Stylesheet</h3><p>In most cases, the output stylesheet can be chosen by selecting a template name and invoking a method on the resource:</p><pre>output_stylesheet = self.prepare_output("configuration")</pre><p>However,
1.172 +on <code>XSLFormsResource</code>, we can just use the WebStack API to set the content type:</p><pre>trans.set_content_type(WebStack.Generic.ContentType("application/xhtml+xml", self.encoding))</pre><p>Note that the <code>encoding</code> attribute is used here to make the character encoding clear to the user's Web browser or client.</p><h3>Defining an Output Stylesheet</h3><p>In most cases, the output stylesheet can be chosen by selecting a template name and invoking a method on the resource:</p><pre>output_stylesheet = self.prepare_output("configuration")</pre><p>However,
1.173 where in-page updates are handled, we may need to check to see if we
1.174 should be sending a fragment of the whole page instead. First, we must
1.175 -check to see if an in-page update is being requested:</p><pre>in_page_resource = self.get_in_page_resource(trans)</pre><p>The
1.176 +check to see if an in-page update is being requested:</p><pre>in_page_resource = self.get_in_page_resource(trans)</pre><p>The
1.177 result of calling the above method should be a string identifying an
1.178 "in-page resource" - that is, a kind of in-page update related to part
1.179 -of the whole page - if such a "resource" is actually being
1.180 +of the whole page - if such a "resource" is actually being
1.181 requested. We can thus check to see if such a request is taking place:</p><pre>if in_page_resource in self.in_page_resources.keys():<br /> [Handle the in-page update request]</pre><p>If
1.182 so, instead of getting a stylesheet which produces output for the whole
1.183 page, we get a "fragment" which produces output only for the part of
1.184 the page being updated:</p><pre> # Continued from above...<br /><br /> output_stylesheet = self.prepare_fragment("configuration", in_page_resource)<br /> stylesheet_parameters = self.prepare_parameters(parameters) # from form.get_parameters()</pre><p>An
1.185 additional step when handling in-page updates is the usage of
1.186 stylesheet parameters to send in some required information about the
1.187 -location of the update in the page. The <code>prepare_parameters</code>
1.188 +location of the update in the page. The <code>prepare_parameters</code>
1.189 method on the resource is used to discover this information and return
1.190 it as a dictionary to be passed to the final output generation activity.</p><h3>Sending the Output to the User</h3><p>Given
1.191 an output stylesheet reference and possibly some parameters, the output
1.192 is sent to the user with a single call to a method on the resource
1.193 -object:</p><pre>self.send_output(trans, [output_stylesheet], configuration_document, stylesheet_parameters)</pre><p>This method should, using the <code>encoding</code>
1.194 +object:</p><pre>self.send_output(trans, [output_stylesheet], configuration_document, stylesheet_parameters)</pre><p>This method should, using the <code>encoding</code>
1.195 attribute on the resource class, ensure that the generated output is
1.196 -correct and consistent for the user's Web browser or client.</p><h2>Additional Stylesheet Parameters</h2><p>In addition to a collection of stylesheets and a document to process, the <code>get_result</code> and <code>send_output</code> methods can accept a number of possible sources of information:</p><ul><li>Stylesheet parameters</li><li>Document references</li><li>Stylesheet expressions</li></ul><p>Generally,
1.197 +correct and consistent for the user's Web browser or client.</p><h2>Additional Stylesheet Parameters</h2><p>In addition to a collection of stylesheets and a document to process, the <code>get_result</code> and <code>send_output</code> methods can accept a number of possible sources of information:</p><ul><li>Stylesheet parameters</li><li>Document references</li><li>Stylesheet expressions</li></ul><p>Generally,
1.198 stylesheet parameters are used to configure the output in some way,
1.199 whilst document references and stylesheet expressions typically offer a
1.200 means of accessing additional information that is to be merged in or
1.201 @@ -199,7 +199,7 @@
1.202 consider the list of values given in the <a href="multiple.html">"Creating Applications: Adding Multiple-Choice Fields and Values"</a> document:</p><pre><?xml version="1.0"?><br /><type><br /> <type-enum value="(Not selected)"/><br /> <type-enum value="Important"/><br /> <type-enum value="Not important"/><br /> <type-enum value="Personal"/><br /></type></pre><p>Such
1.203 information needs to reside somewhere and then be referenced in order
1.204 to be included in the processing operation being performed, which would
1.205 -either be a document initialisation or just a normal transformation.</p><h3>Document References</h3><p>To refer to an externally-defined information, we define the document resource as described above:</p><pre> # At class attribute level...<br /><br /> document_resources = {<br /> "types" : "types.xml",<br /> # Other documents...<br /> }</pre><p>Then, we access the resource, getting a reference to the document:</p><pre>types_xml = self.prepare_document("types")</pre><p>To bring this document into the processing operation, we add an entry to a dictionary passed as the <code>references</code> parameter to <code>get_result</code> (or <code>send_output</code>, if appropriate). In the above example, the information is referenced as follows in the template document:</p><pre> <select template:multiple-choice-field="type,value" name="..."><br /> <option template:multiple-choice-value="type-enum,value,selected" value="..." /><br /> </select></pre><p>Therefore, we take the element name, <code>type</code>, from the field and use it to refer to the external document in the dictionary of references:</p><pre>structure = self.get_result([structure_xsl], structure, references={"type" : types_xml})</pre><p>This should result in the stylesheet incorporating the information from the types document into the transformation.</p><h3>Stylesheet Expressions</h3><p>In
1.206 +either be a document initialisation or just a normal transformation.</p><h3>Document References</h3><p>To refer to an externally-defined information, we define the document resource as described above:</p><pre> # At class attribute level...<br /><br /> document_resources = {<br /> "types" : "types.xml",<br /> # Other documents...<br /> }</pre><p>Then, we access the resource, getting a reference to the document:</p><pre>types_xml = self.prepare_document("types")</pre><p>To bring this document into the processing operation, we add an entry to a dictionary passed as the <code>references</code> parameter to <code>get_result</code> (or <code>send_output</code>, if appropriate). In the above example, the information is referenced as follows in the template document:</p><pre> <select template:multiple-choice-field="type,value" name="..."><br /> <option template:multiple-choice-value="type-enum,value,selected" value="..." /><br /> </select></pre><p>Therefore, we take the element name, <code>type</code>, from the field and use it to refer to the external document in the dictionary of references:</p><pre>structure = self.get_result([structure_xsl], structure, references={"type" : types_xml})</pre><p>This should result in the stylesheet incorporating the information from the types document into the transformation.</p><h3>Stylesheet Expressions</h3><p>In
1.207 more advanced cases, referencing external documents does not provide
1.208 enough flexibility when introducing additional information into a
1.209 transformation. An alternative approach involves copying data into the