1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 2 <html xmlns="http://www.w3.org/1999/xhtml"><head> 3 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 4 5 <title>Using the XSLFormsResource API</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 6 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 7 <body> 8 <h1>Using the XSLFormsResource API</h1> 9 <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> 10 document), and 11 from this class, <code>XSLFormsResource</code>, 12 you can derive your own application-specific resources and use the 13 class's API to obtain, manipulate and present form data. Although the 14 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-module.html">XSLForms.Resources</a></code><a href="../apidocs/public/XSLForms.Resources-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.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> 15 support the concept of resources which are used to produce output, 16 support processing and to provide access to useful information. At the 17 class level it is essential to define at least some of these resources 18 in order to make a working application.</p><h3>The Resource Directory</h3><p>Since 19 XSLForms relies on template files residing in the filesystem, along 20 with other files, we need to define where such files can be found (as 21 described in the <a href="directory.html">"Creating Applications: Create 22 a Directory"</a> document). Consequently, it is the convention that all resource classes define such information as follows:</p><pre>class ConfiguratorResource(XSLForms.Resources.XSLFormsResource):<br /><br /> resource_dir = os.path.join(os.path.split(__file__)[0], "Resources")</pre><p>All 23 filenames, defined in the various resource sections (as described 24 below) must be stated without leading path information - in other 25 words, as "leafnames" rather than "pathnames". Thus, an example of 26 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 27 is also the convention to define the character encoding of the output 28 produced by an application and the way ambiguous or 29 insufficiently-specified input should be interpreted; this is done as 30 follows:</p><pre> # Continuing from above...<br /><br /> encoding = "utf-8"</pre><h3>Template Resources</h3><p>The 31 main purpose of XSLForms is to produce Web page output containing a 32 visual representation of a form. Therefore, we need to define templates 33 (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 34 define a template resource, we first choose a name (which need not have 35 any special significance); we then associate with that name a 36 template filename and an output filename. Finally, we make an 37 entry for the name and its associated details in the special 38 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 39 of the output filename is to define where the intermediate 40 output-producing stylesheet is to be written, since the template itself 41 is not actually used to produce output, but knowing where the 42 intermediate stylesheet can be found is sometimes useful when debugging 43 templates and is thus defined explicitly to avoid confusion.</p><h3>Initialisation Resources</h3><p>The 44 XSLForms toolkit also support the initialisation of form data 45 documents. This document initialisation is useful when preparing a 46 document for output since some parts of a template may not be produced 47 unless certain elements are present in the form data document. For 48 example, a template may contain something like this:</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>In the above example, if no <code>hard-disks</code> element exists, the selector will not be displayed and there will be no way of adding <code>hard-disk</code> elements. With document initialisation, certain measures can be taken to ensure that the <code>hard-disks</code> element is added before output is generated.</p><p>At the class level, the <code>init_resources</code> 49 dictionary is used to hold definitions mapping initialiser names (which 50 need not have any special significance) to the initialiser details: the 51 filename of the template which defines the structure of the form data, 52 and an intermediate filename similar to the output filename described 53 in the context of template resources above. An example of this is as 54 follows:</p><pre> # Continuing from above...<br /><br /> init_resources = {<br /> "configuration" : ("config_template.xhtml", "config_input.xsl"),<br /> # More entries go here...<br /> }</pre><p>Note 55 that initialiser and template resources may (and should) share the same 56 template filename. As with the output filename for template resources, 57 the input filename provides firm information about the location of the 58 stylesheet which actually performs the initialisation process.</p><h3>Document Resources</h3><p>Since 59 it is the XSLForms convention to access files using a simple name, any 60 other document resources should be defined in the <code>document_resources</code> 61 dictionary at the class level. Such document resources may be used in 62 the initialisation process or in other transformations (as described 63 below), and are defined as entries mapping names to filenames such as 64 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> 65 dictionary, nor any insistence in the XSLForms toolkit to define such 66 files as resources - the dictionary is merely a convenience for 67 accessing files in the resources directory.</p><h3>Transform Resources</h3><p>It is sometimes the case that initialisation of a document 68 is not sufficient and that additional processing needs to be done. 69 Whilst various techniques exist for the processing of XML-based 70 information, since XSLForms is part of a wider toolkit based on XSL 71 transformations, it seems reasonable to provide certain facilities for 72 the usage of such transformations. Thus, stylesheet processing 73 pipelines may be defined at the class level in the <code>transform_resources</code> dictionary.</p><p>Entries in the <code>transform_resources</code> 74 dictionary map simple names (which need not have any special 75 significance) to collections of stylesheet filenames as in the 76 following example:</p><pre> # Continuing from above...<br /><br /> transform_resources = {<br /> "filter" : ["filter.xsl"],<br /> # More entries go here...<br /> }</pre><p>Where 77 more than one stylesheet filename is specified, the stylesheets are 78 applied from first to last in the transformation. Additional 79 information, such as stylesheet parameters and referenced documents, 80 are mentioned when the transformation is acquired and invoked, as 81 described below.</p><h3>In-Page Update Resources</h3><p>In certain 82 applications, a technique referred to within XSLForms as "in-page 83 updates" is employed to provide updates of details within a Web page 84 without refreshing the entire page itself (and this is described in the 85 <a href="in-page-updates.html">"Creating Applications: In-Page Updates"</a> 86 document). When such updates are requested, applications have to 87 identify the kind of update requested and then to select the correct 88 part of the Web page to generate as output. Consequently, the 89 application has to have some kind of record of the different kinds of 90 updates and the corresponding parts of the whole page template to use, 91 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> 92 dictionary is that of a mapping from a name identifying the kind of 93 update to the details of the part of the template to be employed in 94 producing the final output for the update: an intermediate filename 95 (distinct from that associated with the whole page template), and a 96 node identifier used to isolate the pertinent part of the whole page 97 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 98 is important to note that, unlike other resources, the name identifying 99 the kind of update is significant: consider an application available at 100 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, 101 the availability of such an update "service" depends on the proper 102 configuration of the Web application to let such updates be handled by 103 the resource.</p><h4>Update Nodes</h4><p>The node identifier mentioned 104 in an in-page update resource definition must be a valid node 105 identifier in the whole page template document. Thus, if we wished to 106 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> 107 node in that template document. Note that the choice of template 108 document is not defined here, but is instead made when handling an 109 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 110 XSLForms is an XML-based toolkit, the form data is available as XML 111 documents which can be accessed and manipulated using a DOM-style API. 112 Upon receiving submitted form data, XSLForms converts the data to such 113 documents and then makes it available through the <code>form</code> 114 object by associating certain document names with the actual documents 115 themselves in a dictionary; this dictionary can be obtained as follows:</p><pre>documents = form.get_documents()</pre><p>Imagine that a template document has been written with <code>items</code> as the root (or topmost) element; such a document will consequently be made available via the <code>form</code> object's documents dictionary using the name <code>items</code>, and can be accessed as follows:</p><pre>items = documents["items"]</pre><p>However, 116 it may be the case that no form data has been submitted. To avoid 117 causing an exception, we should really test for the presence of such a 118 document first:</p><pre>if documents.has_key("items"):<br /> items = documents["items"]</pre><p>Since 119 it is likely that we will want to work with such a document regardless 120 of whether one existed before - we must after all prepare such a 121 document in the first place in order to show it to the user and have it 122 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> 123 document, XSLForms templates may define selectors - special form fields 124 which select parts of the form data documents and make those parts 125 available to applications; such selector information can be obtained as 126 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 127 the collection contains DOM-style elements, various XML libraries and 128 tools may be used to manipulate the data. However, XSLForms also 129 provides convenience functions to add and remove elements.</p><h3>Obtaining Other Parameters</h3><p>Sometimes, 130 there is a need to obtain the "raw" request parameters submitted by the 131 Web client or browser which sent the form data in to the application. 132 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, 133 with the result of this call (a list of stylesheet filenames), we can 134 then perform a transformation on a document, producing a new document 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> 136 method. It should therefore be noted that any references to elements in 137 the old document will not affect the new document; thus selectors 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 139 must be taken doing this, however, since the selectors may now not 140 refer to valid elements - the transformation may have removed or moved 141 elements previously referred to by the selectors.</p><p>The <code>get_result</code> 142 method also supports stylesheet parameters, document references and 143 stylesheet expressions; these are described in the "Additional 144 Stylesheet Parameters" section below.</p><h2>Document Initialisation</h2><p>The initialisation of a document, using information defined in the <code>init_resources</code> 145 attribute, is similar to the transformation of a document as described 146 above. First, we obtain a reference to an initialisation stylesheet:</p><pre>init_stylesheet = self.prepare_initialiser("configuration")</pre><p>Note 147 that only a single stylesheet is returned. With the result of the call, 148 we then perform a transformation similar to the above activity, 149 although we have to supply the returned stylesheet in a list to be 150 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> 151 are used in the template, there will be a need to initialise such 152 elements using references to other documents containing the values of 153 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 154 use of document references and other stylesheet parameter information 155 is described in the "Additional Stylesheet Parameters" section below.</p><h2>Preparing Responses</h2><p>The process of preparing a response involves three main steps:</p><ol><li>Setting a content type.</li><li>Defining an output stylesheet and parameter information.</li><li>Sending the output to the user.</li></ol><h3>Setting a Content Type</h3><p>In 156 the examples supplied with XSLTools, the content type is generally 157 defined as that of XHTML, meaning that the resulting output should be 158 accessible to most modern Web browsers. When writing resources based 159 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, 160 where in-page updates are handled, we may need to check to see if we 161 should be sending a fragment of the whole page instead. First, we must 162 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 163 result of calling the above method should be a string identifying an 164 "in-page resource" - that is, a kind of in-page update related to part 165 of the whole page - if such a "resource" is actually being 166 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 167 so, instead of getting a stylesheet which produces output for the whole 168 page, we get a "fragment" which produces output only for the part of 169 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 170 additional step when handling in-page updates is the usage of 171 stylesheet parameters to send in some required information about the 172 location of the update in the page. The <code>prepare_parameters</code> 173 method on the resource is used to discover this information and return 174 it as a dictionary to be passed to the final output generation activity.</p><h3>Sending the Output to the User</h3><p>Given 175 an output stylesheet reference and possibly some parameters, the output 176 is sent to the user with a single call to a method on the resource 177 object:</p><pre>self.send_output(trans, [output_stylesheet], configuration_document, stylesheet_parameters)</pre><p>This method should, using the <code>encoding</code> 178 attribute on the resource class, ensure that the generated output is 179 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, 180 stylesheet parameters are used to configure the output in some way, 181 whilst document references and stylesheet expressions typically offer a 182 means of accessing additional information that is to be merged in or 183 included in the processed document. The most common need to introduce 184 additional information arises from the use of multiple-choice elements; 185 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 186 information needs to reside somewhere and then be referenced in order 187 to be included in the processing operation being performed, which would 188 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 189 more advanced cases, referencing external documents does not provide 190 enough flexibility when introducing additional information into a 191 transformation. An alternative approach involves copying data into the 192 document to be processed and then to supply references to the data in 193 its new location within the document.</p></body></html>