1.1 --- a/docs/parameters.html Mon Apr 11 17:53:52 2005 +0000
1.2 +++ b/docs/parameters.html Mon Apr 11 21:32:23 2005 +0000
1.3 @@ -38,6 +38,12 @@
1.4 used.</li>
1.5 </ul>
1.6
1.7 +<p>One useful application of parameters transferred in request bodies is the
1.8 +sending or uploading of file contents through such parameters - this is
1.9 +described in "Request Body Parameters". Another way of uploading content in
1.10 +conjunction with the <code>PUT</code> <a href="methods.html">request
1.11 +method</a> is mentioned below.</p>
1.12 +
1.13 <div class="WebStack">
1.14 <h3>WebStack API - Getting All Parameters</h3>
1.15
1.16 @@ -61,5 +67,40 @@
1.17 may be some parameters from the request headers which have the same names as
1.18 some other parameters from the request body. Consequently, confusion could
1.19 arise about the significance of various parameter values.</p>
1.20 +
1.21 +<h2>Using PUT Requests to Upload Files</h2>
1.22 +
1.23 +<p>When handling requests in your application, instead of treating request as
1.24 +containers of parameters and using the WebStack API methods to access those
1.25 +parameters, you can instead choose to read directly from the data sent by the
1.26 +user and interpret that data in your own way. In most situations, this is not
1.27 +really necessary - those methods will decode request parameters (for example,
1.28 +form fields) in a way which is fairly convenient - but when files are being
1.29 +sent, and when the <a href="methods.html">request method</a> is specified as
1.30 +<code>PUT</code>, it is necessary to obtain the input stream from the request
1.31 +and to read the file contents from that stream.</p>
1.32 +
1.33 +<div class="WebStack">
1.34 +<h3>WebStack API - Reading Directly from Requests</h3>
1.35 +
1.36 +<p>When the request does not contain standard form-encoded parameter
1.37 +information and instead contains the contents of an uploaded file, methods
1.38 +like <code>get_fields</code> and <code>get_fields_from_body</code> should be
1.39 +avoided and other methods in the transaction employed.</p>
1.40 +<dl>
1.41 + <dt><code>get_request_stream</code></dt>
1.42 + <dd>This returns the input stream associated with the request. Reading
1.43 + from this will result in the request body being obtained as a plain
1.44 + Python string.</dd>
1.45 + <dt><code>get_content_type</code></dt>
1.46 + <dd>This returns a content type object (typically
1.47 + <code>WebStack.Generic.ContentType</code>) which describes the request
1.48 + body's contents.</dd>
1.49 +</dl>
1.50 +</div>
1.51 +
1.52 +<p>The purpose and behaviour of <code>PUT</code> <a
1.53 +href="methods.html">request methods</a> is described in the HTTP
1.54 +specification.</p>
1.55 </body>
1.56 </html>
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/docs/responses.html Mon Apr 11 21:32:23 2005 +0000
2.3 @@ -0,0 +1,84 @@
2.4 +<?xml version="1.0" encoding="iso-8859-1"?>
2.5 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2.6 + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2.7 +<html xmlns="http://www.w3.org/1999/xhtml">
2.8 +<head>
2.9 + <title>Responses and Presentation</title>
2.10 + <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
2.11 + <link href="styles.css" rel="stylesheet" type="text/css" />
2.12 +</head>
2.13 +
2.14 +<body>
2.15 +<h1>Responses and Presentation</h1>
2.16 +
2.17 +<p>After performing some kind of processing on input information, an
2.18 +application will then want to produce some kind of response to indicate what
2.19 +went on. Here are some examples of responses:</p>
2.20 +<ul>
2.21 + <li>Returning the contents of a requested file.</li>
2.22 + <li>Showing a message telling the user that the requested operation
2.23 + succeeded or failed.</li>
2.24 + <li>Presenting a view onto the application with the results of the recent
2.25 + activity shown in a Web page.</li>
2.26 +</ul>
2.27 +
2.28 +<h2>Generating Responses</h2>
2.29 +
2.30 +<p>The procedure involved in generating a response usually involves the
2.31 +following steps:</p>
2.32 +<ol>
2.33 + <li>Setting a response code to signal whether the application performed the
2.34 + requested operation successfully.</li>
2.35 + <li>Setting a content type and a <a>character encoding</a>.</li>
2.36 + <li>Producing content and sending it to the user.</li>
2.37 +</ol>
2.38 +
2.39 +<p>The kind of code involved may well resemble the following:</p>
2.40 +<pre>from WebStack.Generic import ContentType
2.41 +
2.42 +class MyResource:
2.43 + def respond(self, trans):
2.44 + [Perform the requested operations.]
2.45 +
2.46 + if [the operation was successful]:
2.47 + trans.set_response_code(200)
2.48 + trans.set_content_type(ContentType("text/html", encoding="utf-8"))
2.49 + out = trans.get_response_stream()
2.50 + out.write([some data either as a plain string suitably encoded or as Unicode])
2.51 + else:
2.52 + trans.set_response_code(500) # or some other code
2.53 + trans.set_content_type(ContentType("text/html", encoding="utf-8"))
2.54 + out = trans.get_response_stream()
2.55 + out.write([some other data either as a plain string suitably encoded or as Unicode])</pre>
2.56 +
2.57 +<p>As discussed in <a href="encodings.html">"Character Encodings"</a>, care
2.58 +must be taken generating the response so that it meets any expectations that
2.59 +browsers and other Web clients may have.</p>
2.60 +
2.61 +<div class="WebStack">
2.62 +<h3>WebStack API - Response-Related Methods</h3>
2.63 +
2.64 +<p>Transaction objects have various methods that can be used in generating
2.65 +responses:</p>
2.66 +<dl>
2.67 + <dt><code>set_response_code</code></dt>
2.68 + <dd>This accepts an integer value denoting the response condition as
2.69 + described in the HTTP specification. If this method is not used,
2.70 + WebStack sets a <code>200</code> status condition on the response,
2.71 + meaning that the request was processed successfully.</dd>
2.72 + <dt><code>set_content_type</code></dt>
2.73 + <dd>This accepts a content type object (typically
2.74 + <code>WebStack.Generic.ContentType</code>) which specifies both the
2.75 + media type and the character encoding (if relevant) of the data sent to
2.76 + the user. The media type describes the format of the data (eg.
2.77 + <code>text/html</code> - a Web page), whereas the character encoding
2.78 + describes how any character information on the page is encoded - see <a
2.79 + href="encodings.html">"Character Encodings"</a> for more
2.80 + information.</dd>
2.81 + <dt><code>get_response_stream</code></dt>
2.82 + <dd>This returns the output stream through which data may be sent to the
2.83 + user.</dd>
2.84 +</dl>
2.85 +</div>
2.86 +</body>
2.87 +</html>
3.1 --- a/docs/styles.css Mon Apr 11 17:53:52 2005 +0000
3.2 +++ b/docs/styles.css Mon Apr 11 21:32:23 2005 +0000
3.3 @@ -34,6 +34,10 @@
3.4 PRE {
3.5 background-color: silver;
3.6 color: black;
3.7 +border-style: solid;
3.8 +border-color: black;
3.9 +border-width: 1pt;
3.10 +padding: 0.5em;
3.11 }
3.12
3.13 .WebStack {
3.14 @@ -41,8 +45,8 @@
3.15 border-style: solid;
3.16 border-color: black;
3.17 border-width: 1pt;
3.18 -padding-left: 12pt;
3.19 -padding-right: 12pt;
3.20 +padding-left: 0.5em;
3.21 +padding-right: 0.5em;
3.22 }
3.23
3.24 TH, TD, CAPTION {