1.1 --- a/docs/anatomy.html Wed Aug 24 18:50:32 2005 +0000
1.2 +++ b/docs/anatomy.html Wed Aug 24 21:33:04 2005 +0000
1.3 @@ -1,12 +1,10 @@
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 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
1.8 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
1.9 - <title>Anatomy of a WebStack Application</title>
1.10 - <meta name="generator"
1.11 - content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.12 - <link href="styles.css" rel="stylesheet" type="text/css" />
1.13 -</head>
1.14 +
1.15 + <title>Anatomy of a WebStack Application</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.16 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
1.17 +
1.18 <body>
1.19 <h1>Anatomy
1.20 of a WebStack
1.21 @@ -17,9 +15,7 @@
1.22 which it must respond by writing out messages to send back -
1.23 specifically HTTP responses. When using WebStack, we think of the
1.24 situation in terms of the following components:</p>
1.25 -<table
1.26 - style="text-align: left; margin-left: auto; margin-right: auto; width: 80%;"
1.27 - class="layers" border="0" cellpadding="5" cellspacing="0">
1.28 +<table style="text-align: left; margin-left: auto; margin-right: auto; width: 80%;" class="layers" border="0" cellpadding="5" cellspacing="0">
1.29 <tbody>
1.30 <tr>
1.31 <td width="40%"></td>
1.32 @@ -30,30 +26,26 @@
1.33 to look</th>
1.34 </tr>
1.35 <tr>
1.36 - <th
1.37 - style="text-align: center; vertical-align: middle; background-color: rgb(193, 255, 102); border-top-style: solid; border-left-style: solid; border-right-style: solid; border-top-width: 1px; border-left-width: 1px; border-right-width: 1px;">Application
1.38 + <th style="text-align: center; vertical-align: middle; background-color: rgb(193, 255, 102); border-top-style: solid; border-left-style: solid; border-right-style: solid; border-top-width: 1px; border-left-width: 1px; border-right-width: 1px;">Application
1.39 </th>
1.40 <td style="text-align: center;"><span class="explanation">This
1.41 defines what the user sees. </span></td>
1.42 <td align="center" valign="undefined">Most new code will be
1.43 written in the application.</td>
1.44 <td align="center" valign="undefined">Applications are
1.45 -described in <a href="resources.html">"Applications and Resources"</a>.</td>
1.46 +described in <a href="developing.html">"Developing a WebStack Application"</a>.</td>
1.47 </tr>
1.48 <tr>
1.49 - <th
1.50 - style="border-width: 1px; text-align: center; vertical-align: middle; background-color: rgb(102, 203, 255); border-left-style: solid; border-right-style: solid; border-top-style: solid;">Adapter
1.51 + <th style="border-width: 1px; text-align: center; vertical-align: middle; background-color: rgb(102, 203, 255); border-left-style: solid; border-right-style: solid; border-top-style: solid;">Adapter
1.52 </th>
1.53 <td style="text-align: center;"><span class="explanation">This
1.54 "glues" the application to the environment.</span></td>
1.55 <td align="center" valign="undefined">Mostly copying an existing
1.56 adapter or writing a short module.</td>
1.57 - <td align="center" valign="undefined">Adapters are explained in <a
1.58 - href="deploying.html">"Deploying a WebStack Application"</a>. </td>
1.59 + <td align="center" valign="undefined">Adapters are explained in <a href="deploying.html">"Deploying a WebStack Application"</a>. </td>
1.60 </tr>
1.61 <tr>
1.62 - <th
1.63 - style="border-style: solid; border-width: 1px; text-align: center; vertical-align: middle; background-color: rgb(192, 192, 192);">Server
1.64 + <th style="border-style: solid; border-width: 1px; text-align: center; vertical-align: middle; background-color: rgb(192, 192, 192);">Server
1.65 environment </th>
1.66 <td align="center" valign="undefined"><span class="explanation">This
1.67 is where the application runs.</span></td>
1.68 @@ -66,5 +58,4 @@
1.69 </tr>
1.70 </tbody>
1.71 </table>
1.72 -</body>
1.73 -</html>
1.74 +</body></html>
1.75 \ No newline at end of file
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/docs/developing.html Wed Aug 24 21:33:04 2005 +0000
2.3 @@ -0,0 +1,57 @@
2.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2.5 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
2.6 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
2.7 +
2.8 +
2.9 + <title>Developing a WebStack Application</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
2.10 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
2.11 +
2.12 +<body>
2.13 +<h1>Developing a WebStack Application</h1>
2.14 +<p>Many different topics are involved in the development of WebStack
2.15 +applications; below is a map of each of the topics covered in this
2.16 +documentation:</p>
2.17 +<ul>
2.18 + <li><a href="resources.html">Applications and Resources</a></li>
2.19 + <ul>
2.20 + <li><a href="resource-creation.html">How Resources are Created</a></li>
2.21 + <li><a href="design.html">Application Design Considerations</a></li>
2.22 + <ul>
2.23 + <li><a href="paths.html">URLs and Paths</a></li>
2.24 + <ul>
2.25 + <li><a href="path-info.html">Paths To and Within Applications</a></li>
2.26 + <li><a href="path-design.html">Path Design and Interpretation</a></li>
2.27 + <ul>
2.28 + <li><a href="paths-filesystem.html">Path as filesystem</a></li>
2.29 + <li><a href="paths-services.html">Path as resource or service identifier</a></li>
2.30 + <li><a href="paths-opaque.html">Path as opaque reference</a></li>
2.31 + </ul>
2.32 + <li><a href="path-info-support.html">Path Info Support in Server Environments</a></li>
2.33 + </ul>
2.34 + <li><a href="methods.html">Request Methods</a></li>
2.35 + <li><a href="parameters.html">Request Parameters and Uploads</a></li>
2.36 + <ul>
2.37 + <li><a href="parameters-headers.html">Request headers</a></li>
2.38 + <li><a href="parameters-body.html">Request bodies</a></li>
2.39 + </ul>
2.40 + <li><a href="responses.html">Responses and Presentation</a></li>
2.41 + <li><a href="state.html">Cookies, Sessions, Users and Persistent Information</a></li>
2.42 + <ul>
2.43 + <li><a href="cookies.html">Cookies</a></li>
2.44 + <li><a href="sessions.html">Sessions and Persistent Information</a></li>
2.45 + <ul>
2.46 + <li><a href="sessions-usage.html">Using Sessions</a></li>
2.47 + <li><a href="sessions-servers.html">Server Environment Support for Sessions</a></li>
2.48 + </ul>
2.49 + <li><a href="users.html">Users and Authentication</a></li>
2.50 + </ul>
2.51 + </ul>
2.52 + </ul>
2.53 +</ul>
2.54 +<p>The following topic is referenced in many locations and should
2.55 +be reviewed when encountering problems with input and output text:</p>
2.56 +<ul>
2.57 +<li><a href="encodings.html">Character Encodings</a></li>
2.58 +</ul>
2.59 +<p></p>
2.60 +</body></html>
2.61 \ No newline at end of file
3.1 --- a/docs/encodings.html Wed Aug 24 18:50:32 2005 +0000
3.2 +++ b/docs/encodings.html Wed Aug 24 21:33:04 2005 +0000
3.3 @@ -1,18 +1,16 @@
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 - <title>Character Encodings</title>
3.8 - <meta name="generator"
3.9 - content="amaya 8.1a, see http://www.w3.org/Amaya/" />
3.10 - <link href="styles.css" rel="stylesheet" type="text/css" />
3.11 -</head>
3.12 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
3.13 +
3.14 + <title>Character Encodings</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
3.15 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
3.16 +
3.17 <body>
3.18 <h1>Character Encodings</h1>
3.19 <p>When writing applications with WebStack, you should try and use
3.20 Python's Unicode objects as much as possible. However, there are a
3.21 number of places where plain Python strings can be involved:</p>
3.22 <ul>
3.23 - <li><a href="parameters.html">Inspecting request parameters</a></li>
3.24 + <li><a href="parameters-headers.html">Inspecting query strings</a></li>
3.25 <li><a href="responses.html">Sending output in a response</a></li>
3.26 <li><a href="parameters.html">Receiving uploaded content</a></li>
3.27 <li><a href="state.html">Accessing cookie information</a></li>
3.28 @@ -49,8 +47,7 @@
3.29 <li>Convert textual content to Unicode as soon as possible (see below
3.30 for choosing encodings).</li>
3.31 <li>If you must include hard-coded messages in your application code,
3.32 -make sure to specify the encoding using the <a
3.33 - href="http://www.python.org/peps/pep-0263.html">standard declaration</a>
3.34 +make sure to specify the encoding using the <a href="http://www.python.org/peps/pep-0263.html">standard declaration</a>
3.35 at the top of your source file.</li>
3.36 <li>Remember that the standard library <code>codecs</code>
3.37 module contains useful functions to access streams as if Unicode
3.38 @@ -76,16 +73,13 @@
3.39 Here is an outline of code which does this:</p>
3.40 <pre>from WebStack.Generic import ContentType<br /><br />class MyResource:<br /><br /> encoding = "utf-8" # We decide on "utf-8" as our chosen<br /> # encoding.<br /> def respond(self, trans):<br /> [Do various things.]<br /><br /> fields = trans.get_fields_from_body(encoding=self.encoding) # Explicitly use the encoding.<br /><br /> [Do other things with the Unicode values from the fields.]<br /><br /> trans.set_content_type(ContentType("text/html", self.encoding)) # The output Web page uses the encoding.<br /><br /> [Produce the response, making sure that self.encoding is used to convert Unicode to raw strings.]</pre>
3.41 <h3>Tell Encodings to Other Components</h3>
3.42 -<p>When using other components to generate content (see <a
3.43 - href="integrating.html">"Integrating with Other Systems"</a>), it may
3.44 +<p>When using other components to generate content (see <a href="integrating.html">"Integrating with Other Systems"</a>), it may
3.45 be the case that such components will just write the generated content
3.46 straight to a normal stream (rather than one wrapped by a <code>codecs</code>
3.47 module function). In such cases, it is likely that for textual content
3.48 such as XML or related formats (XHTML, SVG, HTML) you will need to
3.49 instruct the component to use your chosen encoding; for example:</p>
3.50 <pre> # In the respond method, xml_document is an xml.dom.minidom.Document object...<br /> xml_document.toxml(self.encoding)</pre>
3.51 -<p>This will then generate the appropriate characters in the output <span
3.52 - style="font-style: italic;">and</span> specify the correct encoding
3.53 +<p>This will then generate the appropriate characters in the output <span style="font-style: italic;">and</span> specify the correct encoding
3.54 for the XML document.</p>
3.55 -</body>
3.56 -</html>
3.57 +</body></html>
3.58 \ No newline at end of file
4.1 --- a/docs/index.html Wed Aug 24 18:50:32 2005 +0000
4.2 +++ b/docs/index.html Wed Aug 24 21:33:04 2005 +0000
4.3 @@ -3,7 +3,6 @@
4.4
4.5 <title>Creating Web Applications with WebStack</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
4.6 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
4.7 -
4.8 <body>
4.9 <h1>Creating Web Applications with WebStack</h1>
4.10 <p>This introductory guide describes the process of making a Web
4.11 @@ -34,7 +33,8 @@
4.12 and using Python's built-in <code>help</code> function.</p>
4.13 <h2>About WebStack Applications</h2>
4.14 <ul>
4.15 - <li><a href="anatomy.html">Anatomy of a WebStack Application</a></li>
4.16 + <li><a href="anatomy.html">Anatomy of a WebStack Application</a></li><li><a href="developing.html">Developing a WebStack Application</a></li>
4.17 +
4.18 <li><a href="securing.html">Securing a WebStack Application</a></li>
4.19 <li><a href="deploying.html">Deploying a WebStack Application</a></li>
4.20 <li><a href="integrating.html">Integrating with Other Systems</a></li>
5.1 --- a/docs/parameters-headers.html Wed Aug 24 18:50:32 2005 +0000
5.2 +++ b/docs/parameters-headers.html Wed Aug 24 21:33:04 2005 +0000
5.3 @@ -1,12 +1,9 @@
5.4 -<?xml version="1.0" encoding="iso-8859-1"?>
5.5 -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
5.6 - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5.7 -<html xmlns="http://www.w3.org/1999/xhtml">
5.8 -<head>
5.9 - <title>Request Header Parameters</title>
5.10 - <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
5.11 - <link href="styles.css" rel="stylesheet" type="text/css" />
5.12 -</head>
5.13 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5.14 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
5.15 +
5.16 + <title>Request Header Parameters</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
5.17 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
5.18 +
5.19
5.20 <body>
5.21 <h2>Request Header Parameters</h2>
5.22 @@ -27,13 +24,9 @@
5.23
5.24 <p>Parameters encoded in this way can be written into hyperlinks and may be
5.25 used to remember things as users navigate their way around an application.
5.26 -Alternatively, a Web form (in HTML) written to use the <code>GET</code> <a
5.27 -href="methods.html">request method</a> may be used to achieve the same
5.28 +Alternatively, a Web form (in HTML) written to use the <code>GET</code> <a href="methods.html">request method</a> may be used to achieve the same
5.29 effect:</p>
5.30 -<pre><form method="GET" action="http://www.boddie.org.uk/application">
5.31 - <input name="param1" type="text" />
5.32 - <input name="param2" type="text" />
5.33 -</form></pre>
5.34 +<pre><form method="GET" action="http://www.boddie.org.uk/application"><br /> <input name="param1" type="text" /><br /> <input name="param2" type="text" /><br /></form></pre>
5.35
5.36 <div class="WebStack">
5.37 <h3>WebStack API - Accessing Header Parameters</h3>
5.38 @@ -46,7 +39,10 @@
5.39 <dt><code>get_fields_from_path</code></dt>
5.40 <dd>This returns the request parameters (fields) from the request headers
5.41 (as defined in the path or URL). The fields are provided in a
5.42 - dictionary mapping field names to lists of values</dd>
5.43 + dictionary mapping field names to lists of values<br />
5.44 +An optional <code>encoding</code> parameter may be used to assist
5.45 +the process of converting parameter values to Unicode objects - see
5.46 +below for a discussion of the issues with this parameter.</dd>
5.47 <dt><code>get_query_string</code></dt>
5.48 <dd>This returns the query string - ie. the part of the path or URL which
5.49 contains the parameters. Typically, it is easier to use the above
5.50 @@ -60,8 +56,10 @@
5.51 should remain hidden will appear in the URL and probably be shown in
5.52 browsers and other user interfaces.</li>
5.53 <li>There isn't widespread agreement about how non-ASCII characters should
5.54 - be encoded in URLs. Therefore, care must be taken to encode and decode
5.55 - values transferred in request headers.</li>
5.56 + be encoded in URLs. WebStack attempts to handle the ambiguity, but does require some assistance...</li><li>For
5.57 +the conversion of such parameters to Unicode to function correctly,
5.58 +care must be taken with character encodings - this is discussed in <a href="responses.html">"Responses and Presentation"</a> and also in <a href="encodings.html">"Character Encodings"</a>.<br />
5.59 + </li>
5.60 +
5.61 </ul>
5.62 -</body>
5.63 -</html>
5.64 +</body></html>
5.65 \ No newline at end of file
6.1 --- a/docs/path-info.html Wed Aug 24 18:50:32 2005 +0000
6.2 +++ b/docs/path-info.html Wed Aug 24 21:33:04 2005 +0000
6.3 @@ -1,12 +1,10 @@
6.4 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
6.5 -<html xmlns="http://www.w3.org/1999/xhtml">
6.6 -<head>
6.7 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
6.8 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
6.9 - <title>Paths To and Within Applications</title>
6.10 - <meta name="generator"
6.11 - content="amaya 8.1a, see http://www.w3.org/Amaya/" />
6.12 - <link href="styles.css" rel="stylesheet" type="text/css" />
6.13 -</head>
6.14 +
6.15 + <title>Paths To and Within Applications</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
6.16 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
6.17 +
6.18 <body>
6.19 <h1>Paths To and
6.20 Within Applications</h1>
6.21 @@ -48,14 +46,15 @@
6.22 <dt><code>get_path_info</code></dt>
6.23 <dd>This gets the path of a
6.24 resource within an application. The path should always contain a
6.25 -leading <code>/</code> character at the very least.</dd>
6.26 +leading <code>/</code> character at the very least.<br />
6.27 +An optional encoding parameter may be used to assist the process of converting the path to a Unicode object - see <a href="encodings.html">"Character Encodings"</a> for more information.</dd>
6.28 <dt><code>get_virtual_path_info</code></dt>
6.29 <dd>This gets the path of a
6.30 resource within a part of an application
6.31 - the application itself decides the scope of the path and can set the
6.32 "virtual path info" using the <code>set_virtual_path_info</code>
6.33 -method. The path should always contain a leading <code>/</code>
6.34 -character at the very least.</dd>
6.35 +method. The path should either contain a leading <code>/</code>
6.36 +character optionally followed by other characters, or an empty string.</dd>
6.37 </dl>
6.38 </div>
6.39 <h2>Choosing the Right Path Value</h2>
6.40 @@ -67,8 +66,7 @@
6.41 it may be difficult to use that to provide references or links to those
6.42 resources. Here is a summary of how you might use the different path
6.43 values:</p>
6.44 -<table style="text-align: left; width: 80%;" align="center" border="1"
6.45 - cellpadding="5" cellspacing="0" width="80%">
6.46 +<table style="text-align: left; width: 80%;" align="center" border="1" cellpadding="5" cellspacing="0" width="80%">
6.47 <tbody>
6.48 <tr>
6.49 <th style="text-align: center;">Type of information</th>
6.50 @@ -136,9 +134,8 @@
6.51 <dl>
6.52 <dt><code>set_virtual_path_info</code></dt>
6.53 <dd>This sets the virtual path, affecting subsequent calls to the <code>get_virtual_path_info</code>
6.54 -method. The path should always contain a leading <code>/</code>
6.55 -character at the very least.</dd>
6.56 +method. The path should either contain a leading <code>/</code>
6.57 +character optionally followed by other characters, or an empty string.</dd>
6.58 </dl>
6.59 </div>
6.60 -</body>
6.61 -</html>
6.62 +</body></html>
6.63 \ No newline at end of file
7.1 --- a/docs/paths.html Wed Aug 24 18:50:32 2005 +0000
7.2 +++ b/docs/paths.html Wed Aug 24 21:33:04 2005 +0000
7.3 @@ -1,11 +1,9 @@
7.4 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
7.5 -<html xmlns="http://www.w3.org/1999/xhtml">
7.6 -<head>
7.7 - <title>URLs and Paths</title>
7.8 - <meta name="generator"
7.9 - content="amaya 8.1a, see http://www.w3.org/Amaya/" />
7.10 - <link href="styles.css" rel="stylesheet" type="text/css" />
7.11 -</head>
7.12 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
7.13 +
7.14 + <title>URLs and Paths</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
7.15 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
7.16 +
7.17 <body>
7.18 <h1>URLs and Paths</h1>
7.19 <p>The URL at which your application shall appear is arguably the first
7.20 @@ -55,7 +53,8 @@
7.21 <dt><code>get_path</code></dt>
7.22 <dd>This gets the entire path of a resource including parameter
7.23 information (as described in <a href="parameters.html">"Request
7.24 -Parameters and Uploads"</a>).</dd>
7.25 +Parameters and Uploads"</a>).<br />
7.26 +An optional encoding parameter may be used to assist the process of converting the path to a Unicode object - see <a href="encodings.html">"Character Encodings"</a> for more information.</dd>
7.27 <dt><code>get_path_without_query</code></dt>
7.28 <dd>This gets the entire path of a resource but without any parameter
7.29 information.</dd>
7.30 @@ -78,5 +77,4 @@
7.31 <li><a href="path-info-support.html">Path Info Support in Server
7.32 Environments</a></li>
7.33 </ul>
7.34 -</body>
7.35 -</html>
7.36 +</body></html>
7.37 \ No newline at end of file