1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/Web-resource.html Tue Jul 19 14:49:29 2005 +0000
1.3 @@ -0,0 +1,126 @@
1.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.5 +<html xmlns="http://www.w3.org/1999/xhtml">
1.6 +<head>
1.7 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
1.8 + <title>Creating Applications: Write a Web Resource</title>
1.9 + <meta name="generator"
1.10 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.11 + <link href="styles.css" rel="stylesheet" type="text/css" />
1.12 +</head>
1.13 +<body>
1.14 +<h1>Creating Applications: Write a Web Resource</h1>
1.15 +<p>With a completed template after the <a href="design.html">design</a>,
1.16 +<a href="structure.html">structure annotation</a> and <a
1.17 + href="selectors.html">selector annotation</a>, we may now write a Web
1.18 +resource which will expose our form as a Web application, allowing
1.19 +users to input information and to manipulate that information using
1.20 +their Web browser. Whilst XSLForms is just a normal Python package
1.21 +which can be used from many kinds of programs and environments, we
1.22 +shall concentrate on using the built-in <a
1.23 + href="http://www.boddie.org.uk/python/WebStack.html">WebStack</a>
1.24 +support to build a
1.25 +WebStack application around our form template.</p>
1.26 +<h2>XSLForms Meets WebStack </h2>
1.27 +<p>In the <a href="directory.html">directory structure</a> created
1.28 +earlier, we now want to edit the <code>__init__.py</code> file and
1.29 +add code which will do most of the work of the form-editing
1.30 +application. Here is the start of this code:</p>
1.31 +<pre>#!/usr/bin/env python<br /><br />"A very simple example application."<br /><br />import WebStack.Generic<br />import XSLForms.Resources<br />import XSLForms.Utils<br />import os<br /><br /># Resource classes.<br /><br />class VerySimpleResource(XSLForms.Resources.XSLFormsResource):<br /><br /> # To be continued.</pre>
1.32 +<p>The above import statements just include in our application
1.33 +everything that it is likely to need from WebStack, XSLForms and the
1.34 +standard library. Then, we define a class inheriting from a special
1.35 +XSLForms class which does some of the tedious Web application
1.36 +housekeeping that we would otherwise need to do ourselves.</p>
1.37 +<p>We may expand the above class definition as follows:</p>
1.38 +<pre>class VerySimpleResource(XSLForms.Resources.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.39 +<p>The class is started with some attribute definitions:</p>
1.40 +<ul>
1.41 + <li>The <code>resource_dir</code> attribute is used to locate
1.42 +the template, stylesheet and other non-Python resources. We calculate
1.43 +this attribute by taking the location of the Python package itself and
1.44 +finding the <code>Resources</code> subdirectory, just as described
1.45 +in the <a href="directory.html">directory structure</a> document.</li>
1.46 + <li>The <code>encoding</code> attribute is not strictly
1.47 +necessary, but it states which character encoding will be used in the
1.48 +Web pages generated by the template, and UTF-8 is a safe choice in most
1.49 +situations.</li>
1.50 + <li>The <code>template_resources</code> attribute is a
1.51 +dictionary mapping a name onto details about our template and the
1.52 +stylesheet that will actually produce the Web pages for each form being
1.53 +edited.<br />
1.54 + <ol>
1.55 + <li>For the key, we choose a name that can easily be remembered
1.56 +and associated with our template: <code>structure</code> (since
1.57 +the root element of the form data is always <code>structure</code>)</li>
1.58 + <li>Then, we specify the filename of our template in the <code>Resources</code>
1.59 +directory: <code>structure_template.xhtml</code> (if the suggested
1.60 +name was used)</li>
1.61 + <li>Finally, we choose a filename for the stylesheet. Since this
1.62 +is automatically produced from the template, we only need to choose a
1.63 +name which is not already in use by another file, and for clarity a
1.64 +name similar to that of the template is recommended: <code>structure_output.xsl</code></li>
1.65 + </ol>
1.66 + </li>
1.67 +</ul>
1.68 +<p>The class also has a method which resembles the typical <code>respond</code>
1.69 +method of normal <a
1.70 + href="http://www.boddie.org.uk/python/WebStack.html">WebStack</a>
1.71 +resources: the <code>respond_to_form</code> method is, in fact, a
1.72 +special version of that method providing ready-to-use information about
1.73 +the form (or forms) being edited.</p>
1.74 +<p>We may now add to the above method definition by considering what
1.75 +the resource needs to do when being sent a request by a user of the
1.76 +application.</p>
1.77 +<h3>Defining the Method</h3>
1.78 +<p>First of all, we need to inspect the <code>form</code> object
1.79 +to see if any form data is available. Since the data is provided
1.80 +throughout XSLForms as XML documents, we call the <code>get_documents</code>
1.81 +method on the <code>form</code> object:</p>
1.82 +<pre> documents = form.get_documents()</pre>
1.83 +<p>As a result of this method, we should now have a dictionary mapping
1.84 +form names to XML documents containing form data. However, it is not
1.85 +guaranteed that the form data for our chosen form, <code>structure</code>,
1.86 +even exists since a user may be visiting the resource for the first
1.87 +time.</p>
1.88 +<p>Therefore, we test to see if the <code>structure</code>
1.89 +document exists, creating a new document if it did not:</p>
1.90 +<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.91 +<p>Now we should have a document containing the data for the form being
1.92 +edited, regardless of whether any form was filled out and submitted or
1.93 +whether we have created a new one for that purpose.</p>
1.94 +<p>It may be the case that a user pressed a button in order to add or
1.95 +remove items or subitems from the form. We must respond to such things
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. In the <a href="selectors.html">selector annotation</a>
1.102 +process, we defined selectors for the addition and removal of items and
1.103 +subitems, and for convenience we pass the results for each selector to
1.104 +a special function to perform the appropriate operation for us:</p>
1.105 +<pre> XSLForms.Utils.remove_elements(selectors.get("remove2"))<br /> XSLForms.Utils.add_elements(selectors.get("add2"), "subitem")<br /> XSLForms.Utils.remove_elements(selectors.get("remove"))<br /> XSLForms.Utils.add_elements(selectors.get("add"), "item")<br /></pre>
1.106 +<p>Finally, we are ready to present the edited form data. In typical
1.107 +WebStack fashion, we emit the content type of the final output along
1.108 +with our chosen character encoding:</p>
1.109 +<pre> # Start the response.<br /><br /> trans.set_content_type(WebStack.Generic.ContentType("application/xhtml+xml", self.encoding))<br /></pre>
1.110 +<p>Then, we ensure that our template is ready to use by calling the
1.111 +superclass's <code>prepare_output</code> method with the name of
1.112 +the form:</p>
1.113 +<pre> # Ensure that an output stylesheet exists.<br /><br /> trans_xsl = self.prepare_output("structure")<br /></pre>
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 +stylesheets (although we only use a single stylesheet in this example)
1.118 +along with the form data itself:</p>
1.119 +<pre> # Complete the response.<br /><br /> self.send_output(trans, [trans_xsl], structure)</pre>
1.120 +<p>At this point, the user should receive their edited form and be able
1.121 +to make more modifications.</p>
1.122 +<h2>Further Enhancements</h2>
1.123 +<p>We should now have an application which can be deployed and tested
1.124 +using the usual WebStack techniques. However, more advanced templates
1.125 +can be designed, and we shall consider <a href="multiple.html">multiple-choice
1.126 +fields</a> in the next activity in the development <a
1.127 + href="overview.html">process</a>.</p>
1.128 +</body>
1.129 +</html>
2.1 --- a/docs/design.html Tue Jul 19 14:46:59 2005 +0000
2.2 +++ b/docs/design.html Tue Jul 19 14:49:29 2005 +0000
2.3 @@ -115,7 +115,8 @@
2.4 <pre><?xml version="1.0"?><br /><html xmlns="http://www.w3.org/1999/xhtml"><br /><head><br /> <title>Example</title><br /></head><br /><body><br /><form action="" method="POST"><br /><br /><!-- Template text between the start and the interesting part. --><br /><br /><div><br /> <p><br /> Some item: <input name="value" type="text" value="some value" /><br /> <input name="remove" type="submit" value="Remove" /><br /> </p><br /> <p><br /> Itself containing more items:<br /> </p><br /> <p><br /> Sub-item: <input name="subvalue" type="text" value="some other value" /><br /> <input name="remove2" type="submit" value="Remove" /><br /> </p><br /> <p><br /> <input name="add2" type="submit" value="Add subitem" /><br /> </p><br /></div><br /><p><br /> <input name="add" type="submit" value="Add item" /><br /></p><br /><br /><!-- Template text between the interesting part and the end. --><br /><br /></form><br /></body><br /></html></pre>
2.5 <p>Once you are happy with the
2.6 design of the page, save it to the <a href="directory.html">directory</a>
2.7 -created earlier, then proceed to <a href="structure.html">adding
2.8 +created earlier (perhaps choosing the name <code>structure_template.xhtml</code>),
2.9 +then proceed to <a href="structure.html">adding
2.10 structure information</a> in the next stage of the <a
2.11 href="overview.html">process</a>.</p>
2.12 </body>
3.1 --- a/docs/directory.html Tue Jul 19 14:46:59 2005 +0000
3.2 +++ b/docs/directory.html Tue Jul 19 14:49:29 2005 +0000
3.3 @@ -1,91 +1,60 @@
3.4 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3.5 <html xmlns="http://www.w3.org/1999/xhtml">
3.6 <head>
3.7 -
3.8 -
3.9 -
3.10 -
3.11 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
3.12 -
3.13 -
3.14 -
3.15 -
3.16 -
3.17 -
3.18 <title>Creating Applications: Create a Directory</title>
3.19 - <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
3.20 -
3.21 -
3.22 -
3.23 -
3.24 + <meta name="generator"
3.25 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
3.26 <link href="styles.css" rel="stylesheet" type="text/css" />
3.27 </head>
3.28 -
3.29 -
3.30 <body>
3.31 -
3.32 -
3.33 -<h1>Creating Applications: Create a Directory</h1>
3.34 -
3.35 -
3.36 -<p>The recommended directory structure of an XSLForms application is as
3.37 +<h1>Creating Applications: Create
3.38 +a Directory</h1>
3.39 +<p>The recommended directory
3.40 +structure of an XSLForms application is as
3.41 follows:</p>
3.42 -
3.43 -<table style="text-align: left; width: 80%;" align="center" border="0" cellpadding="5" cellspacing="0" width="60%">
3.44 -
3.45 +<table style="text-align: left; width: 80%;" align="center" border="0"
3.46 + cellpadding="5" cellspacing="0" width="60%">
3.47 <tbody>
3.48 -
3.49 <tr>
3.50 -
3.51 <td width="60%"></td>
3.52 -
3.53 - <th style="text-align: left;" colspan="2" width="40%">Example Directory Structure<br />
3.54 -
3.55 + <th style="text-align: left;" colspan="2" width="40%">Example
3.56 +Directory
3.57 +Structure<br />
3.58 </th>
3.59 -
3.60 -
3.61 </tr>
3.62 -
3.63 <tr>
3.64 -
3.65 - <th style="text-align: right;">A top-level directory corresponding to a Python package</th>
3.66 -
3.67 - <td style="background-color: rgb(204, 204, 255); border-top-style: solid; border-left-style: solid; border-right-style: solid; border-right-width: 1px; border-left-width: 1px; border-top-width: 1px;" align="undefined" valign="undefined"><span style="font-weight: bold;">VerySimple</span><br />
3.68 -__init__.py</td>
3.69 -
3.70 - <td align="undefined" valign="undefined"></td>
3.71 -
3.72 + <th style="text-align: right;">A
3.73 +top-level directory corresponding to a Python package</th>
3.74 + <td
3.75 + style="background-color: rgb(204, 204, 255); border-top-style: solid; border-left-style: solid; border-right-style: solid; border-right-width: 1px; border-left-width: 1px; border-top-width: 1px;"
3.76 + align="undefined" valign="undefined"><code><span
3.77 + style="font-weight: bold;">VerySimple</span><br />
3.78 +__init__.py</code></td>
3.79 + <td></td>
3.80 </tr>
3.81 -
3.82 -
3.83 <tr>
3.84 -
3.85 - <th style="text-align: right;">A subdirectory containing non-code resources for the
3.86 + <th style="text-align: right;">A subdirectory
3.87 +containing non-code resources for the
3.88 application</th>
3.89 -
3.90 - <td style="background-color: rgb(204, 204, 255); border-left-style: solid; border-right-style: solid; border-bottom-style: solid; border-left-width: 1px; border-right-width: 1px; border-bottom-width: 1px;" align="undefined" valign="undefined"><br />
3.91 -
3.92 + <td
3.93 + style="background-color: rgb(204, 204, 255); border-left-style: solid; border-right-style: solid; border-bottom-style: solid; border-left-width: 1px; border-right-width: 1px; border-bottom-width: 1px;"><br />
3.94 </td>
3.95 -
3.96 - <td><span class="subdirectory"><span style="font-weight: bold;">Resources</span><br />
3.97 -
3.98 -...</span></td>
3.99 -
3.100 + <td><span class="subdirectory"><code><span
3.101 + style="font-weight: bold;">Resources</span><br />
3.102 +...</code></span></td>
3.103 </tr>
3.104 -
3.105 -
3.106 </tbody>
3.107 </table>
3.108 -<p>For the above example, the directory structure would be created using UNIX-style commands as follows:</p>
3.109 -
3.110 -
3.111 +<p>For the above example, the
3.112 +directory structure would be created using UNIX-style commands
3.113 +as follows:</p>
3.114 <pre>mkdir VerySimple<br />mkdir VerySimple/Resources<br />touch VerySimple/__init__.py</pre>
3.115 -
3.116 -
3.117 -<p>It is in the <code>Resources</code> subdirectory that we will save
3.118 -our template files when <a href="design.html">designing</a> them as
3.119 -part of the next activity in the application development <a href="overview.html">process</a>.</p>
3.120 -
3.121 -
3.122 +<p>It is in the <code>Resources</code>
3.123 +subdirectory that we will save
3.124 +our template files when <a href="design.html">designing</a>
3.125 +them as
3.126 +part of the next activity in the application development <a
3.127 + href="overview.html">process</a>.</p>
3.128 </body>
3.129 </html>
4.1 --- a/docs/overview.html Tue Jul 19 14:46:59 2005 +0000
4.2 +++ b/docs/overview.html Tue Jul 19 14:49:29 2005 +0000
4.3 @@ -1,84 +1,35 @@
4.4 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4.5 <html xmlns="http://www.w3.org/1999/xhtml">
4.6 <head>
4.7 -
4.8 -
4.9 -
4.10 -
4.11 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
4.12 -
4.13 -
4.14 -
4.15 -
4.16 -
4.17 -
4.18 <title>Creating Applications: An Overview</title>
4.19 - <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
4.20 -
4.21 -
4.22 -
4.23 -
4.24 + <meta name="generator"
4.25 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
4.26 <link href="styles.css" rel="stylesheet" type="text/css" />
4.27 </head>
4.28 -
4.29 -
4.30 <body>
4.31 -
4.32 -
4.33 <h1>Creating Applications: An Overview</h1>
4.34 -
4.35 -
4.36 <p>The following steps briefly describe how to make a new application:<br />
4.37 -
4.38 -
4.39 </p>
4.40 -
4.41 -
4.42 <ol>
4.43 -
4.44 -
4.45 <li><a href="directory.html">Create a directory to hold your files</a></li>
4.46 <li><a href="data.html">Design the structure of the form data</a></li>
4.47 -
4.48 -
4.49 <li><a href="design.html">Design a template</a></li>
4.50 -
4.51 -
4.52 <li><a href="structure.html">Add structure to the template</a></li>
4.53 -
4.54 <li><a href="selectors.html">Add selectors to the template</a></li>
4.55 -
4.56 -
4.57 - <li><a href="catalogues.html">Prepare catalogues of multiple-choice
4.58 -values</a></li>
4.59 -
4.60 -
4.61 <li><a href="Web-resource.html">Write a Web resource to display the
4.62 form</a></li>
4.63 -
4.64 -
4.65 + <li><a href="multiple.html">Adding multiple-choice fields and values</a></li>
4.66 </ol>
4.67 -
4.68 -
4.69 <h2>Recommendations</h2>
4.70 -
4.71 -
4.72 <ol>
4.73 -
4.74 -
4.75 <li>Where multiple fields exist and can be added and removed, put
4.76 them inside a separate element so that the selectors can successfully
4.77 identify them. Otherwise, changing element orders can result in the
4.78 wrong element being selected.</li>
4.79 -
4.80 -
4.81 <li>Make sure that transformations on the input document produce all
4.82 the necessary elements for the output document so that the resulting
4.83 page gives the user the opportunity to specify data that is missing.</li>
4.84 -
4.85 -
4.86 </ol>
4.87 -
4.88 -
4.89 </body>
4.90 </html>
5.1 --- a/docs/selectors.html Tue Jul 19 14:46:59 2005 +0000
5.2 +++ b/docs/selectors.html Tue Jul 19 14:49:29 2005 +0000
5.3 @@ -34,7 +34,7 @@
5.4 style="font-weight: bold;">remove2={template:this-position()}</span>" type="submit" value="Remove" /><br /> </p><br /> <p><br /> <input name="<span
5.5 style="font-weight: bold;">add2={template:this-position()}</span>" type="submit" value="Add subitem" /><br /> </p><br /></div><br /><p><br /> <input name="<span
5.6 style="font-weight: bold;">add={template:this-position()}</span>" type="submit" value="Add item" /><br /></p><span
5.7 - style="font-weight: bold;"></span><br /><br /><!-- Template text between the interesting part and the end. --><br /><br /></form><br /></body><br /></html></pre>
5.8 + style="font-weight: bold;" /><br /><br /><!-- Template text between the interesting part and the end. --><br /><br /></form><br /></body><br /></html></pre>
5.9 <h3>The Remove Buttons</h3>
5.10 <p>Some of the attributes in the previous HTML code have been
5.11 changed:</p>
5.12 @@ -61,6 +61,9 @@
5.13 form data. This means that each button will refer to a
5.14 specific subitem in the form being edited.</li>
5.15 </ul>
5.16 +<p>We define the names of the selectors in the above cases to be <code>remove</code>
5.17 +and <code>remove2</code> respectively, since the special values
5.18 +begin with these identifiers.</p>
5.19 <h3>The Add Buttons</h3>
5.20 <p>Some other attributes have been changed in the previous HTML
5.21 code:</p>
5.22 @@ -95,10 +98,13 @@
5.23 the form being edited, and the consequence of adding an item will
5.24 be the extension of the main list of items in the form.</li>
5.25 </ul>
5.26 -<p>Whilst many forms consist only of text fields and action buttons,
5.27 -other types of data are very likely to also be used. <a
5.28 - href="multiple.html">Multiple-choice or enumerated value fields</a> in
5.29 -forms are covered in the next activity in the development <a
5.30 +<p>We define the names of the selectors in the above cases to be <code>add2</code>
5.31 +and <code>add</code> respectively, since the special values begin with
5.32 +these identifiers.</p>
5.33 +<p>We should now have a template that is sufficiently complete to be
5.34 +used in a real application, and the writing of the <a
5.35 + href="Web-resource.html">application code</a> itself will be
5.36 +investigated in the next activity in the development <a
5.37 href="overview.html">process</a>.</p>
5.38 </body>
5.39 </html>