1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/responses.html Mon Apr 11 21:32:23 2005 +0000
1.3 @@ -0,0 +1,84 @@
1.4 +<?xml version="1.0" encoding="iso-8859-1"?>
1.5 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
1.6 + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.7 +<html xmlns="http://www.w3.org/1999/xhtml">
1.8 +<head>
1.9 + <title>Responses and Presentation</title>
1.10 + <meta name="generator" 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 +
1.14 +<body>
1.15 +<h1>Responses and Presentation</h1>
1.16 +
1.17 +<p>After performing some kind of processing on input information, an
1.18 +application will then want to produce some kind of response to indicate what
1.19 +went on. Here are some examples of responses:</p>
1.20 +<ul>
1.21 + <li>Returning the contents of a requested file.</li>
1.22 + <li>Showing a message telling the user that the requested operation
1.23 + succeeded or failed.</li>
1.24 + <li>Presenting a view onto the application with the results of the recent
1.25 + activity shown in a Web page.</li>
1.26 +</ul>
1.27 +
1.28 +<h2>Generating Responses</h2>
1.29 +
1.30 +<p>The procedure involved in generating a response usually involves the
1.31 +following steps:</p>
1.32 +<ol>
1.33 + <li>Setting a response code to signal whether the application performed the
1.34 + requested operation successfully.</li>
1.35 + <li>Setting a content type and a <a>character encoding</a>.</li>
1.36 + <li>Producing content and sending it to the user.</li>
1.37 +</ol>
1.38 +
1.39 +<p>The kind of code involved may well resemble the following:</p>
1.40 +<pre>from WebStack.Generic import ContentType
1.41 +
1.42 +class MyResource:
1.43 + def respond(self, trans):
1.44 + [Perform the requested operations.]
1.45 +
1.46 + if [the operation was successful]:
1.47 + trans.set_response_code(200)
1.48 + trans.set_content_type(ContentType("text/html", encoding="utf-8"))
1.49 + out = trans.get_response_stream()
1.50 + out.write([some data either as a plain string suitably encoded or as Unicode])
1.51 + else:
1.52 + trans.set_response_code(500) # or some other code
1.53 + trans.set_content_type(ContentType("text/html", encoding="utf-8"))
1.54 + out = trans.get_response_stream()
1.55 + out.write([some other data either as a plain string suitably encoded or as Unicode])</pre>
1.56 +
1.57 +<p>As discussed in <a href="encodings.html">"Character Encodings"</a>, care
1.58 +must be taken generating the response so that it meets any expectations that
1.59 +browsers and other Web clients may have.</p>
1.60 +
1.61 +<div class="WebStack">
1.62 +<h3>WebStack API - Response-Related Methods</h3>
1.63 +
1.64 +<p>Transaction objects have various methods that can be used in generating
1.65 +responses:</p>
1.66 +<dl>
1.67 + <dt><code>set_response_code</code></dt>
1.68 + <dd>This accepts an integer value denoting the response condition as
1.69 + described in the HTTP specification. If this method is not used,
1.70 + WebStack sets a <code>200</code> status condition on the response,
1.71 + meaning that the request was processed successfully.</dd>
1.72 + <dt><code>set_content_type</code></dt>
1.73 + <dd>This accepts a content type object (typically
1.74 + <code>WebStack.Generic.ContentType</code>) which specifies both the
1.75 + media type and the character encoding (if relevant) of the data sent to
1.76 + the user. The media type describes the format of the data (eg.
1.77 + <code>text/html</code> - a Web page), whereas the character encoding
1.78 + describes how any character information on the page is encoded - see <a
1.79 + href="encodings.html">"Character Encodings"</a> for more
1.80 + information.</dd>
1.81 + <dt><code>get_response_stream</code></dt>
1.82 + <dd>This returns the output stream through which data may be sent to the
1.83 + user.</dd>
1.84 +</dl>
1.85 +</div>
1.86 +</body>
1.87 +</html>