1.1 --- a/docs/Web-resource.html Sat Sep 08 16:53:18 2007 +0000
1.2 +++ b/docs/Web-resource.html Sat Sep 08 16:53:34 2007 +0000
1.3 @@ -1,8 +1,8 @@
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>Creating Applications: Write a Web Resource</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.10 + <title>Creating Applications: Write a Web Resource</title>
1.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
1.12 <body>
1.13 <h1>Creating Applications: Write a Web Resource</h1>
1.14 @@ -17,7 +17,7 @@
1.15 WebStack application around our form template.</p>
1.16 <h2>XSLForms Meets WebStack </h2>
1.17 <p>In the <a href="directory.html">directory structure</a> created
1.18 -earlier, we now want to edit the <code>__init__.py</code> file and
1.19 +earlier, we now want to edit the <code>__init__.py</code> file and
1.20 add code which will do most of the work of the form-editing
1.21 application. Here is the start of this code:</p>
1.22 <pre>#!/usr/bin/env python<br /><br />"A very simple example application."<br /><br />import WebStack.Generic<br />import XSLForms.Resources.WebResources<br />import XSLForms.Utils<br />import os<br /><br /># Resource classes.<br /><br />class VerySimpleResource(XSLForms.Resources.WebResources.XSLFormsResource):<br /><br /> # To be continued.</pre>
1.23 @@ -30,51 +30,51 @@
1.24 <pre>class VerySimpleResource(XSLForms.Resources.WebResources.XSLFormsResource):<br /><br /> "A very simple resource providing a hierarchy of editable fields."<br /><br /> resource_dir = os.path.join(os.path.split(__file__)[0], "Resources")<br /> encoding = "utf-8"<br /> template_resources = {<br /> "structure" : ("structure_template.xhtml", "structure_output.xsl")<br /> }<br /><br /> def respond_to_form(self, trans, form):<br /><br /> """<br /> Respond to a request having the given transaction 'trans' and the given<br /> 'form' information.<br /> """<br /><br /> # To be continued.</pre>
1.25 <p>The class is started with some attribute definitions:</p>
1.26 <ul>
1.27 - <li>The <code>resource_dir</code> attribute is used to locate
1.28 + <li>The <code>resource_dir</code> attribute is used to locate
1.29 the template, stylesheet and other non-Python resources. We calculate
1.30 this attribute by taking the location of the Python package itself and
1.31 -finding the <code>Resources</code> subdirectory, just as described
1.32 +finding the <code>Resources</code> subdirectory, just as described
1.33 in the <a href="directory.html">directory structure</a> document.</li>
1.34 - <li>The <code>encoding</code> attribute is not strictly
1.35 + <li>The <code>encoding</code> attribute is not strictly
1.36 necessary, but it states which character encoding will be used in the
1.37 Web pages generated by the template, and UTF-8 is a safe choice in most
1.38 situations.</li>
1.39 - <li>The <code>template_resources</code> attribute is a
1.40 + <li>The <code>template_resources</code> attribute is a
1.41 dictionary mapping a name onto details about our template and the
1.42 stylesheet that will actually produce the Web pages for each form being
1.43 edited.<br />
1.44 <ol>
1.45 <li>For the key, we choose a name that can easily be remembered
1.46 -and associated with our template: <code>structure</code> (since
1.47 -the root element of the form data is always <code>structure</code>)</li>
1.48 - <li>Then, we specify the filename of our template in the <code>Resources</code>
1.49 -directory: <code>structure_template.xhtml</code> (if the suggested
1.50 +and associated with our template: <code>structure</code> (since
1.51 +the root element of the form data is always <code>structure</code>)</li>
1.52 + <li>Then, we specify the filename of our template in the <code>Resources</code>
1.53 +directory: <code>structure_template.xhtml</code> (if the suggested
1.54 name was used)</li>
1.55 <li>Finally, we choose a filename for the stylesheet. Since this
1.56 is automatically produced from the template, we only need to choose a
1.57 name which is not already in use by another file, and for clarity a
1.58 -name similar to that of the template is recommended: <code>structure_output.xsl</code></li>
1.59 +name similar to that of the template is recommended: <code>structure_output.xsl</code></li>
1.60 </ol></li></ul>
1.61 -<p>The class also has a method which resembles the typical <code>respond</code>
1.62 +<p>The class also has a method which resembles the typical <code>respond</code>
1.63 method of normal <a href="http://www.boddie.org.uk/python/WebStack.html">WebStack</a>
1.64 -resources: the <code>respond_to_form</code> method is, in fact, a
1.65 +resources: the <code>respond_to_form</code> method is, in fact, a
1.66 special version of that method providing ready-to-use information about
1.67 the form (or forms) being edited.</p>
1.68 <p>We may now add to the above method definition by considering what
1.69 the resource needs to do when being sent a request by a user of the
1.70 application.</p>
1.71 <h3>Defining the Method</h3>
1.72 -<p>First of all, we need to inspect the <code>form</code> object
1.73 +<p>First of all, we need to inspect the <code>form</code> object
1.74 to see if any form data is available. Since the data is provided
1.75 -throughout XSLForms as XML documents, we call the <code>get_documents</code>
1.76 -method on the <code>form</code> object:</p>
1.77 +throughout XSLForms as XML documents, we call the <code>get_documents</code>
1.78 +method on the <code>form</code> object:</p>
1.79 <pre> documents = form.get_documents()</pre>
1.80 <p>As a result of this method, we should now have a dictionary mapping
1.81 form names to XML documents containing form data. However, it is not
1.82 -guaranteed that the form data for our chosen form, <code>structure</code>,
1.83 +guaranteed that the form data for our chosen form, <code>structure</code>,
1.84 even exists since a user may be visiting the resource for the first
1.85 time.</p>
1.86 -<p>Therefore, we test to see if the <code>structure</code>
1.87 +<p>Therefore, we test to see if the <code>structure</code>
1.88 document exists, creating a new document if it did not:</p>
1.89 <pre> # Ensure the presence of a document.<br /><br /> if documents.has_key("structure"):<br /> structure = documents["structure"]<br /> else:<br /> structure = form.new_instance("structure")<br /></pre>
1.90 <p>Now we should have a document containing the data for the form being
1.91 @@ -82,11 +82,11 @@
1.92 whether we have created a new one for that purpose.</p>
1.93 <p>It may be the case that a user pressed a button in order to add or
1.94 remove items or subitems from the form. We must respond to such things
1.95 -by examining the selector information to see which parts of the <code>structure</code>
1.96 +by examining the selector information to see which parts of the <code>structure</code>
1.97 document are affected:</p>
1.98 <pre> # Add and remove elements according to the selectors found.<br /><br /> selectors = form.get_selectors()<br /></pre>
1.99 <p>The result of <code>get_selectors</code> is a dictionary mapping
1.100 -selector names to lists of nodes affected by each particular
1.101 +selector names to lists of nodes affected by each particular
1.102 selector. In the <a href="selectors.html">selector annotation</a>
1.103 process, we defined selectors for the addition and removal of items and
1.104 subitems, and for convenience we pass the results for each selector to
1.105 @@ -97,12 +97,12 @@
1.106 with our chosen character encoding:</p>
1.107 <pre> # Start the response.<br /><br /> trans.set_content_type(WebStack.Generic.ContentType("application/xhtml+xml", self.encoding))<br /></pre>
1.108 <p>Then, we ensure that our template is ready to use by calling the
1.109 -superclass's <code>prepare_output</code> method with the name of
1.110 +superclass's <code>prepare_output</code> method with the name of
1.111 the form:</p>
1.112 <pre> # Ensure that an output stylesheet exists.<br /><br /> trans_xsl = self.prepare_output("structure")<br /></pre>
1.113 -<p>This prepares the stylesheet whose file is named in the <code>template_resources</code>
1.114 +<p>This prepares the stylesheet whose file is named in the <code>template_resources</code>
1.115 attribute entry, and this stylesheet is then sent to the
1.116 -superclass's <code>send_output</code> method as part of a list of
1.117 +superclass's <code>send_output</code> method as part of a list of
1.118 stylesheets (although we only use a single stylesheet in this example)
1.119 along with the form data itself:</p>
1.120 <pre> # Complete the response.<br /><br /> self.send_output(trans, [trans_xsl], structure)</pre>
1.121 @@ -117,19 +117,19 @@
1.122 <p>To actually deploy the application, we could choose one of many
1.123 server environments supported by WebStack. For clarity, we choose here
1.124 to write the following separate program which we can save under the
1.125 -name <code>VerySimpleApp.py</code> (for example):</p>
1.126 +name <code>VerySimpleApp.py</code> (for example):</p>
1.127 <pre>#!/usr/bin/env python<br /><br />from WebStack.Adapters.BaseHTTPRequestHandler import deploy<br />import VerySimple<br /><br /># Get a simple Web site.<br /><br />resource = VerySimple.get_site()<br /><br /># Special magic incantation.<br /><br />print "Serving..."<br />deploy(resource, handle_errors=0)</pre>
1.128 <p>Ensuring that the example application's package (which we
1.129 -called <code>VerySimple</code> in the directory structure
1.130 +called <code>VerySimple</code> in the directory structure
1.131 document), WebStack, libxml2dom and XSLForms are available to the above
1.132 program, we may now run this program:</p>
1.133 <pre>python VerySimpleApp.py</pre>
1.134 -<p>It should then be possible to visit the URL <code>http://localhost:8080/</code>
1.135 +<p>It should then be possible to visit the URL <code>http://localhost:8080/</code>
1.136 and edit the form in your Web browser.<br />
1.137 </p>
1.138 <h2>Further Enhancements</h2>
1.139 <p>We should now have an application which can be deployed and tested
1.140 using the usual WebStack techniques. However, more advanced templates
1.141 can be designed, and we shall consider <a href="multiple.html">multiple-choice
1.142 -fields</a> in the next activity in the development <a href="overview.html">process</a>.</p>
1.143 +fields</a> in the next activity in the development <a href="overview.html">process</a>.</p>
1.144 </body></html>