1.1 --- a/docs/design.html Thu Aug 25 21:44:47 2005 +0000
1.2 +++ b/docs/design.html Thu Aug 25 21:45:47 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>Application Design Considerations</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>Application Design Considerations</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>Application Design Considerations</h1>
1.20 <p>When writing an application, we
1.21 @@ -26,22 +24,21 @@
1.22 transaction object effectively tells us what it is the user wants to
1.23 do; it does so through a number of different pieces of information
1.24 including the request method, headers, parameters, cookies and sessions.</p>
1.25 -<div class="WebStack">
1.26 -<h3>WebStack API - The Transaction Object</h3>
1.27 <p>The transaction object appears as the first parameter in a
1.28 resource's <code>respond</code> method:</p>
1.29 -<pre>class SomeResource:<br /> def respond(self, trans):<br /> [Here is where the code for the resource is written.]</pre>
1.30 -<p>For full information about transaction objects, see the API
1.31 -documentation for the <a
1.32 - href="../apidocs/public/WebStack.Generic.Transaction-class.html"><code>WebStack.Generic.Transaction</code></a>
1.33 -class.</p>
1.34 -</div>
1.35 +
1.36 +<pre>class MyResource:<br /> def respond(self, trans):<br /> [Here is where the code for the resource is written.]</pre>
1.37 +
1.38 <p>Within this activity, certain topics are of interest:</p>
1.39 <ul>
1.40 <li><a href="paths.html">URLs and Paths</a></li>
1.41 <li><a href="methods.html">Request Methods</a></li>
1.42 <li><a href="parameters.html">Request Parameters and Uploads</a></li>
1.43 </ul>
1.44 +<p>For full information about transaction objects, see the API
1.45 +documentation for the <a href="../apidocs/public/WebStack.Generic.Transaction-class.html"><code>WebStack.Generic.Transaction</code></a>
1.46 +class.</p>
1.47 +
1.48 <h2>Perform Actions</h2>
1.49 <p>Of all activities summarised above, this is the most vague because
1.50 the kinds of actions performed by applications will vary substantially
1.51 @@ -63,5 +60,4 @@
1.52 <li><a href="state.html">Cookies, Sessions, Users and Persistent
1.53 Information</a></li>
1.54 </ul>
1.55 -</body>
1.56 -</html>
1.57 +</body></html>
1.58 \ No newline at end of file
2.1 --- a/docs/developing.html Thu Aug 25 21:44:47 2005 +0000
2.2 +++ b/docs/developing.html Thu Aug 25 21:45:47 2005 +0000
2.3 @@ -5,7 +5,6 @@
2.4
2.5 <title>Developing a WebStack Application</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
2.6 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
2.7 -
2.8 <body>
2.9 <h1>Developing a WebStack Application</h1>
2.10 <p>Many different topics are involved in the development of WebStack
2.11 @@ -13,39 +12,66 @@
2.12 documentation:</p>
2.13 <ul>
2.14 <li><a href="resources.html">Applications and Resources</a></li>
2.15 - <ul>
2.16 - <li><a href="resource-creation.html">How Resources are Created</a></li>
2.17 - <li><a href="design.html">Application Design Considerations</a></li>
2.18 - <ul>
2.19 - <li><a href="paths.html">URLs and Paths</a></li>
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 +
2.24 +
2.25 + <li><a href="paths.html">URLs and Paths</a></li>
2.26 +<ul>
2.27 +
2.28 +
2.29 + <li><a href="path-info.html">Paths To and Within Applications</a></li>
2.30 +
2.31 + <li><a href="path-design.html">Path Design and Interpretation</a></li>
2.32 +
2.33 +
2.34 <ul>
2.35 - <li><a href="path-info.html">Paths To and Within Applications</a></li>
2.36 - <li><a href="path-design.html">Path Design and Interpretation</a></li>
2.37 - <ul>
2.38 +
2.39 <li><a href="paths-filesystem.html">Path as filesystem</a></li>
2.40 <li><a href="paths-services.html">Path as resource or service identifier</a></li>
2.41 <li><a href="paths-opaque.html">Path as opaque reference</a></li>
2.42 - </ul>
2.43 - <li><a href="path-info-support.html">Path Info Support in Server Environments</a></li>
2.44 - </ul>
2.45 - <li><a href="methods.html">Request Methods</a></li>
2.46 - <li><a href="parameters.html">Request Parameters and Uploads</a></li>
2.47 - <ul>
2.48 - <li><a href="parameters-headers.html">Request headers</a></li>
2.49 - <li><a href="parameters-body.html">Request bodies</a></li>
2.50 +
2.51 </ul>
2.52 - <li><a href="responses.html">Responses and Presentation</a></li>
2.53 - <li><a href="state.html">Cookies, Sessions, Users and Persistent Information</a></li>
2.54 - <ul>
2.55 - <li><a href="cookies.html">Cookies</a></li>
2.56 - <li><a href="sessions.html">Sessions and Persistent Information</a></li>
2.57 - <ul>
2.58 +
2.59 + <li><a href="path-info-support.html">Path Info Support in Server Environments</a></li>
2.60 +
2.61 +
2.62 + </ul><li><a href="methods.html">Request Methods</a></li>
2.63 + <li><a href="parameters.html">Request Parameters and Uploads</a></li>
2.64 + <ul>
2.65 +
2.66 +
2.67 +
2.68 + <li><a href="parameters-headers.html">Request headers</a></li>
2.69 +
2.70 + <li><a href="parameters-body.html">Request bodies</a></li>
2.71 +
2.72 +
2.73 +
2.74 + </ul>
2.75 + <li><a href="responses.html">Responses and Presentation</a></li>
2.76 + <li><a href="state.html">Cookies, Sessions, Users and Persistent Information</a></li>
2.77 + <ul>
2.78 +
2.79 +
2.80 + <li><a href="cookies.html">Cookies</a></li>
2.81 + <li><a href="sessions.html">Sessions and Persistent Information</a></li>
2.82 +<ul>
2.83 +
2.84 +
2.85 +
2.86 <li><a href="sessions-usage.html">Using Sessions</a></li>
2.87 +
2.88 <li><a href="sessions-servers.html">Server Environment Support for Sessions</a></li>
2.89 - </ul>
2.90 - <li><a href="users.html">Users and Authentication</a></li>
2.91 - </ul>
2.92 +
2.93 +
2.94 +
2.95 + </ul><li><a href="users.html">Users and Authentication</a></li>
2.96 +
2.97 +
2.98 </ul>
2.99 +
2.100 </ul>
2.101 </ul>
2.102 <p>The following topic is referenced in many locations and should
3.1 --- a/docs/paths.html Thu Aug 25 21:44:47 2005 +0000
3.2 +++ b/docs/paths.html Thu Aug 25 21:45:47 2005 +0000
3.3 @@ -3,7 +3,6 @@
3.4
3.5 <title>URLs and Paths</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
3.6 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
3.7 -
3.8 <body>
3.9 <h1>URLs and Paths</h1>
3.10 <p>The URL at which your application shall appear is arguably the first
3.11 @@ -54,13 +53,31 @@
3.12 <dd>This gets the entire path of a resource including parameter
3.13 information (as described in <a href="parameters.html">"Request
3.14 Parameters and Uploads"</a>).<br />
3.15 -An optional <code>encoding</code> 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>
3.16 +An optional <code>encoding</code> parameter may be used to assist the process of converting the path to a Unicode object - see below.</dd>
3.17 <dt><code>get_path_without_query</code></dt>
3.18 <dd>This gets the entire path of a resource but without any parameter
3.19 -information.</dd>
3.20 +information.<br />
3.21 +
3.22 +An optional <code>encoding</code> parameter may be used to assist the process of converting the path to a Unicode object - see below.</dd>
3.23 </dl>
3.24 </div>
3.25 +<p>To obtain the above path using the WebStack API, we can write the following code:</p>
3.26 +<pre>path = trans.get_path()</pre>
3.27 +<p>Really, however, we should explicitly state the character encoding of the path. Unfortunately, as noted in <a href="encodings.html">"Character Encodings"</a>,
3.28 +some guesswork is required, but if we have decided to use UTF-8 as the
3.29 +encoding of our output, it is reasonable to specify UTF-8 here as well:</p>
3.30 +<pre>path = trans.get_path("utf-8")<br />path = trans.get_path(self.encoding) # assuming a class/instance attribute defining such things centrally</pre>
3.31 +<p>In many applications such nuances are not particularly important, but consider the following URL:</p>
3.32 +<pre>http://www.boddie.org.uk/python/WebStack-%E6%F8%E5.html</pre>
3.33 +<p>Here, the URL includes non-ASCII characters which must be
3.34 +interpreted somehow. In this case, the "URL encoded" character values
3.35 +refer to ISO-8859-1 values and can be safely inspected as follows:</p>
3.36 +<pre>path = trans.get_path("iso-8859-1")</pre>
3.37 +<p>The above usage of UTF-8 will also work in this case, but only
3.38 +because WebStack will use ISO-8859-1 as a "safe" default for character
3.39 +values it does not understand.</p>
3.40 <h2>Query Strings</h2>
3.41 +
3.42 <p>Sometimes, a "query string" will be provided as part of a URL; for
3.43 example:</p>
3.44 <pre>http://www.boddie.org.uk/application?param1=value1</pre>
3.45 @@ -70,6 +87,40 @@
3.46 inspection
3.47 is discussed in <a href="parameters.html">"Request Parameters and
3.48 Uploads"</a>.</p>
3.49 +<div class="WebStack">
3.50 +<h3>WebStack API - Getting Query Strings</h3>
3.51 +<p>WebStack provides a method to get only the query string from the URL:</p>
3.52 +<dl><dt><code>get_query_string</code></dt><dd>This method returns the part of the URL which contains parameter
3.53 +information. Such information will be "URL encoded", meaning that
3.54 +certain characters will have the form <code>%xx</code> where <code>xx</code>
3.55 +is a two digit hexadecimal number referring to the byte value of the
3.56 +unencoded character - see below for discussion of this. </dd></dl>
3.57 +</div>
3.58 +<p>Note that unlike the path access methods, <code>get_query_string</code>
3.59 +does not accept an encoding as a parameter. Moreover, when retrieving a
3.60 +path including a query string, the encoding is not used to interpret
3.61 +"URL encoded" character values in the query string itself. Consider
3.62 +this example URL:</p>
3.63 +<pre>http://www.boddie.org.uk/application-%E6?var%F8=value%E5</pre>
3.64 +<p>Upon requesting the path and the query string, certain differences should be noticeable:</p>
3.65 +<pre>trans.get_path("iso-8859-1") # returns /application-æ?var%F8=value%E5<br />trans.get_path_without_query("iso-8859-1") # returns /application-æ<br />trans.get_query_string() # returns var%F8=value%E5</pre>
3.66 +<p>One reason for this seemingly arbitrary distinction in treatment is
3.67 +the way certain servers present path information to WebStack - often
3.68 +the "URL encoded" information has been replaced by raw character values
3.69 +which must then be converted to Unicode characters. In contrast, most
3.70 +servers do not perform the same automatic conversion on the query
3.71 +string.</p>
3.72 +<p>In fact, it may become impossible to properly interpret the query
3.73 +string if it is decoded prematurely; consider this example URL:</p>
3.74 +<pre>http://www.boddie.org.uk/application?a=%26b</pre>
3.75 +<p>If we were to just decode the query string and then extract the
3.76 +parameters/fields, the result would be two empty parameters with the
3.77 +names <code>a</code> and <code>b</code>, as opposed to the correct interpretation of the query string as describing a single parameter <code>a</code> with the value <code>&b</code>.</p>
3.78 +<h3>Conclusion</h3>
3.79 +<p>Regardless of all this, all inspection of path parameters should be done using the appropriate methods (see <a href="parameters.html">"Request Parameters and
3.80 +Uploads"</a>),
3.81 +and direct access to the query string should only occur in situations
3.82 +of a specialised nature such as the building of URLs for output.</p>
3.83 <h2>More About Paths</h2>
3.84 <ul>
3.85 <li><a href="path-info.html">Paths To and Within Applications</a></li>
4.1 --- a/docs/resources.html Thu Aug 25 21:44:47 2005 +0000
4.2 +++ b/docs/resources.html Thu Aug 25 21:45:47 2005 +0000
4.3 @@ -1,12 +1,10 @@
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 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
4.8 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
4.9 - <title>Applications and Resources</title>
4.10 - <meta name="generator"
4.11 - content="amaya 8.1a, see http://www.w3.org/Amaya/" />
4.12 - <link href="styles.css" rel="stylesheet" type="text/css" />
4.13 -</head>
4.14 +
4.15 + <title>Applications and Resources</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
4.16 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
4.17 +
4.18 <body>
4.19 <h1>Applications and Resources</h1>
4.20 At its simplest a WebStack application is just a single Python
4.21 @@ -71,11 +69,4 @@
4.22 <p>You should now be able to visit <code>http://localhost:8080</code>
4.23 in your
4.24 browser and see the message printed by your application:</p>
4.25 -<pre>Hello world.</pre>
4.26 -<h2>About Resources</h2>
4.27 -<ul>
4.28 - <li><a href="resource-creation.html">How Resources are Created</a></li>
4.29 - <li><a href="design.html">Application Design Considerations</a></li>
4.30 -</ul>
4.31 -</body>
4.32 -</html>
4.33 +<pre>Hello world.</pre></body></html>
4.34 \ No newline at end of file