1.1 --- a/docs/developing.html Tue Sep 06 22:03:41 2005 +0000
1.2 +++ b/docs/developing.html Tue Sep 06 22:04:08 2005 +0000
1.3 @@ -43,13 +43,14 @@
1.4
1.5
1.6
1.7 - <li><a href="parameters-headers.html">Request headers</a></li>
1.8 + <li><a href="parameters-headers.html">Request header parameters</a></li>
1.9
1.10 - <li><a href="parameters-body.html">Request bodies</a></li>
1.11 + <li><a href="parameters-body.html">Request body parameters</a></li>
1.12
1.13
1.14
1.15 - </ul>
1.16 + </ul><li><a href="headers.html">Request Headers</a></li>
1.17 +
1.18 <li><a href="responses.html">Responses and Presentation</a></li>
1.19 <li><a href="state.html">Cookies, Sessions, Users and Persistent Information</a></li>
1.20 <ul>
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/docs/headers.html Tue Sep 06 22:04:08 2005 +0000
2.3 @@ -0,0 +1,70 @@
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>Request Headers</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 +<body>
2.12 +<h1>Request Headers</h1>
2.13 +
2.14 +
2.15 +<p>Request headers are pieces of information that describe certain aspects of a request, such as:</p>
2.16 +<ul>
2.17 + <li>The location to which the request is being sent.</li>
2.18 + <li>The type of information in the request body.</li>
2.19 + <li>Preferences about which kinds of information the sender would like to receive in return.</li>
2.20 +</ul>
2.21 +<p>The location and related query information is conveniently accessible through <a href="paths.html">path</a> information and <a href="parameters-headers.html">request header parameter</a> information. Other types of header information are made available through other WebStack API methods.</p>
2.22 +<h2>Content Types</h2>
2.23 +<p>When a Web application sends some information in a response, it
2.24 +describes the content type of that information, and this is described
2.25 +in the "Responses and Presentation" document. However, it is also
2.26 +possible that information sent to the application is also described
2.27 +using a content type, and such details may be investigated using code
2.28 +similar to the following:</p>
2.29 +
2.30 +<pre>class MyResource:<br /> def respond(self, trans):<br /> content_type = trans.get_content_type() # returns a WebStack.Generic.ContentType object</pre>
2.31 +
2.32 +<p>Unfortunately, such information is not always provided by Web browsers.</p>
2.33 +<h2>Content Preferences</h2>
2.34 +<p>Sometimes, Web browsers describe the kinds of information that
2.35 +they are willing to receive, and WebStack provides various means to
2.36 +query such preferences:</p>
2.37 +
2.38 +<pre> languages = trans.get_content_languages() # returns a list of language codes<br /> charsets = trans.get_content_charsets() # returns a list of character set identifiers<br /></pre>
2.39 +<p>This information permits us to send content which matches the
2.40 +expectations of the user, or at least the expectations of the user's
2.41 +software.</p>
2.42 +<h2>Other Headers</h2>
2.43 +<p>Various other pieces of information may be attached to the request
2.44 +as headers, and such information can be accessed through the general
2.45 +header access methods as described below. Each header has a particular
2.46 +name which is associated with a corresponding value.</p>
2.47 +<div class="WebStack">
2.48 +<h3>WebStack API - Accessing Header Information</h3>
2.49 +
2.50 +<p>Transaction objects provide the following methods to access request header information:</p>
2.51 +<dl>
2.52 + <dt><code>get_headers</code></dt>
2.53 + <dd>This returns a
2.54 + dictionary mapping header names to single string values.<br />
2.55 +</dd>
2.56 + <dt><code>get_header_values</code></dt>
2.57 + <dd>Given a header name as parameter, this method returns a list of string values associated with that name.</dd><dt><code>get_content_type</code></dt>
2.58 + <dd>This returns a content type object (typically <code>WebStack.Generic.ContentType</code>) describing the incoming request body content.</dd>
2.59 + <dt><code>get_content_languages</code></dt>
2.60 + <dd>This returns a list of language identifiers, in descending order
2.61 +of preference, indicating in which languages the sender of the request
2.62 +would prefer to receive information.</dd>
2.63 + <dt><code>get_content_charsets</code></dt>
2.64 + <dd>This returns a list of character set identifiers, in descending
2.65 +order of preference, indicating in which character sets the sender of
2.66 +the request would prefer to receive information.</dd>
2.67 +
2.68 +</dl>
2.69 +<p>It should be noted that the <code>get_headers</code> and <code>get_header_values</code> methods
2.70 +present a slightly different view of the available header information,
2.71 +in that only a single header value is made available through the <code>get_headers</code> method for each header name, whereas <code>get_header_values</code> provides potentially many values for the same header name. </p>
2.72 +
2.73 +</div></body></html>
2.74 \ No newline at end of file
3.1 --- a/docs/parameters-body.html Tue Sep 06 22:03:41 2005 +0000
3.2 +++ b/docs/parameters-body.html Tue Sep 06 22:04:08 2005 +0000
3.3 @@ -1,24 +1,17 @@
3.4 -<?xml version="1.0" encoding="iso-8859-1"?>
3.5 -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
3.6 - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3.7 -<html xmlns="http://www.w3.org/1999/xhtml">
3.8 -<head>
3.9 - <title>Request Body Parameters</title>
3.10 - <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
3.11 - <link href="styles.css" rel="stylesheet" type="text/css" />
3.12 -</head>
3.13 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3.14 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
3.15 +
3.16 + <title>Request Body Parameters</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
3.17 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
3.18 +
3.19
3.20 <body>
3.21 <h1>Request Body Parameters</h1>
3.22
3.23 <p>Request parameters are typically added to the request body when forms are
3.24 -submitted by a browser which is instructed to use the <code>POST</code> <a
3.25 -href="methods.html">request method</a>. A Web form (in HTML) can be used to
3.26 +submitted by a browser which is instructed to use the <code>POST</code> <a href="methods.html">request method</a>. A Web form (in HTML) can be used to
3.27 achieve this; for example:</p>
3.28 -<pre><form method="POST" action="http://www.boddie.org.uk/application">
3.29 - <input name="param1" type="text" />
3.30 - <input name="param2" type="text" />
3.31 -</form></pre>
3.32 +<pre><form method="POST" action="http://www.boddie.org.uk/application"><br /> <input name="param1" type="text" /><br /> <input name="param2" type="text" /><br /></form></pre>
3.33
3.34 <p>As a consequence of this form being submitted, the following parameters
3.35 will become available in the application:</p>
3.36 @@ -54,9 +47,7 @@
3.37 <p>Some limitations exist with request body parameters:</p>
3.38 <ul>
3.39 <li>For the conversion of such parameters to Unicode to function correctly,
3.40 - care must be taken with character encodings - this is discussed in <a
3.41 - href="responses.html">"Responses and Presentation"</a> and also in <a
3.42 - href="encodings.html">"Character Encodings"</a>.</li>
3.43 + 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>.</li>
3.44 </ul>
3.45
3.46 <h2>File Uploads</h2>
3.47 @@ -66,5 +57,12 @@
3.48 applications. Unlike other parameters, those which carry file upload data
3.49 expose the contents of such uploaded files as plain Python string values
3.50 instead of Unicode objects.</p>
3.51 -</body>
3.52 -</html>
3.53 +<h3>Unsupported Environments and Framework Issues</h3>
3.54 +<ul>
3.55 + <li>Twisted does not provide file upload data as raw string values;
3.56 +instead, file upload data will be decoded and returned as Unicode from
3.57 +WebStack. This behaviour is due to the way Twisted processes the
3.58 +incoming request and may be fixed in a future release.</li>
3.59 +</ul>
3.60 +
3.61 +</body></html>
3.62 \ No newline at end of file
4.1 --- a/docs/parameters-headers.html Tue Sep 06 22:03:41 2005 +0000
4.2 +++ b/docs/parameters-headers.html Tue Sep 06 22:04:08 2005 +0000
4.3 @@ -3,10 +3,9 @@
4.4
4.5 <title>Request Header Parameters</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>Request Header Parameters</h1>
4.10
4.11 -<body>
4.12 -<h2>Request Header Parameters</h2>
4.13
4.14 <p>Header parameters are typically specified in the URL like this:</p>
4.15 <pre>http://www.boddie.org.uk/application?param1=value1&param2=value2</pre>
5.1 --- a/docs/parameters.html Tue Sep 06 22:03:41 2005 +0000
5.2 +++ b/docs/parameters.html Tue Sep 06 22:04:08 2005 +0000
5.3 @@ -1,19 +1,16 @@
5.4 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5.5 -<html xmlns="http://www.w3.org/1999/xhtml">
5.6 -<head>
5.7 - <title>Request Parameters and Uploads</title>
5.8 - <meta name="generator"
5.9 - content="amaya 8.1a, see http://www.w3.org/Amaya/" />
5.10 - <link href="styles.css" rel="stylesheet" type="text/css" />
5.11 -</head>
5.12 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
5.13 +
5.14 + <title>Request Parameters and Uploads</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
5.15 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
5.16 +
5.17 <body>
5.18 <h1>Request Parameters and Uploads</h1>
5.19 <p>Even though it is possible to expose different parts of an
5.20 application
5.21 using different <a href="paths.html">URLs and paths</a>, this usually
5.22 is only
5.23 -enough for applications which model some kind of <a
5.24 - href="paths-filesystem.html">filesystem</a> or repository.
5.25 +enough for applications which model some kind of <a href="paths-filesystem.html">filesystem</a> or repository.
5.26 Applications which
5.27 involve user input through forms, for example, need to be able to
5.28 receive
5.29 @@ -29,13 +26,11 @@
5.30 <li>The application reads the field values using the WebStack API.</li>
5.31 </ol>
5.32 <h2>Parameter Origins</h2>
5.33 -<p>Request parameters can originate from two sources:</p>
5.34 +<p>Request parameters exist in two forms:</p>
5.35 <ul>
5.36 - <li><a href="parameters-headers.html">Request headers</a> -
5.37 -parameters are found here when they are specified in the URL as a
5.38 + <li><a href="parameters-headers.html">Request header parameters</a> - parameters specified in the URL as a
5.39 "query string".</li>
5.40 - <li><a href="parameters-body.html">Request bodies</a> - parameters
5.41 -are found here when the POST <a href="methods.html">request method</a>
5.42 + <li><a href="parameters-body.html">Request body parameters</a> - parameters are found in the request body when the POST <a href="methods.html">request method</a>
5.43 is used.</li>
5.44 </ul>
5.45 <p>One useful application of parameters transferred in request bodies
5.46 @@ -57,9 +52,7 @@
5.47 <dd>This method returns a dictionary mapping field names to lists of
5.48 values for all known parameters. Each value will be a Unicode object.<br />
5.49 An optional <code>encoding</code> parameter may be used to assist the
5.50 -process of converting parameter values to Unicode objects - see <a
5.51 - href="parameters-body.html">"Request Body Parameters"</a> and <a
5.52 - href="encodings.html">"Character Encodings"</a> for more discussion of
5.53 +process of converting parameter values to Unicode objects - see <a href="parameters-body.html">"Request Body Parameters"</a> and <a href="encodings.html">"Character Encodings"</a> for more discussion of
5.54 this parameter.</dd>
5.55 <dt><code>get_query_string</code></dt>
5.56 <dd>This method returns the part of the URL which contains parameter
5.57 @@ -114,8 +107,6 @@
5.58 which describes the request body's contents.</dd>
5.59 </dl>
5.60 </div>
5.61 -<p>The purpose and behaviour of <code>PUT</code> <a
5.62 - href="methods.html">request methods</a> is described in the HTTP
5.63 +<p>The purpose and behaviour of <code>PUT</code> <a href="methods.html">request methods</a> is described in the HTTP
5.64 specification.</p>
5.65 -</body>
5.66 -</html>
5.67 +</body></html>
5.68 \ No newline at end of file
6.1 --- a/docs/sessions-usage.html Tue Sep 06 22:03:41 2005 +0000
6.2 +++ b/docs/sessions-usage.html Tue Sep 06 22:04:08 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>Using Sessions</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>Using Sessions</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>Using Sessions</h1>
6.20 <p>Unlike cookies, session information is always stored on the server
6.21 @@ -25,8 +23,7 @@
6.22 <div class="WebStack">
6.23 <h3>WebStack API - Using Sessions</h3>
6.24 <p>In WebStack, a session appears as a dictionary to applications and
6.25 -is acquired for a specific user through the <a
6.26 - href="../apidocs/public/WebStack.Generic.Transaction-class.html">transaction</a>
6.27 +is acquired for a specific user through the <a href="../apidocs/public/WebStack.Generic.Transaction-class.html">transaction</a>
6.28 object. The following methods are provided in the transaction for
6.29 accessing and maintenance of session information:</p>
6.30 <dl>
6.31 @@ -66,5 +63,12 @@
6.32 <pre> # In the respond method...<br /> trans.expire_session()</pre>
6.33 <p>Note that WebStack automatically knows which session is to be
6.34 expired since only one such session can exist for the identified user.</p>
6.35 -</body>
6.36 -</html>
6.37 +<h2>Session Limitations and Guidelines</h2>
6.38 +<ul>
6.39 + <li>Due to various limitations in the storage of session information,
6.40 +it is recommended that each item of data is converted to a string value
6.41 +when being set in the session, and that the key employed is also a
6.42 +string value. These limitations may be removed in a later release.</li>
6.43 +</ul>
6.44 +
6.45 +</body></html>
6.46 \ No newline at end of file