WebStack

Annotated docs/responses.html

354:32f41c83f4ac
346:effeae83e027
2005-04-11 paulb file changeset files shortlog [project @ 2005-04-11 21:32:23 by paulb] Improved the stylesheet. Added file upload and response descriptions.
paulb@346 1 
<?xml version="1.0" encoding="iso-8859-1"?>
paulb@346 2 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
paulb@346 3 
       "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
paulb@346 4 
<html xmlns="http://www.w3.org/1999/xhtml">
paulb@346 5 
<head>
paulb@346 6 
  <title>Responses and Presentation</title>
paulb@346 7 
  <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
paulb@346 8 
  <link href="styles.css" rel="stylesheet" type="text/css" />
paulb@346 9 
</head>
paulb@346 10 
 
 paulb@346     11 
<body>
 
 paulb@346     12 
<h1>Responses and Presentation</h1>
 
 paulb@346     13 
 
 paulb@346     14 
<p>After performing some kind of processing on input information, an
 
 paulb@346     15 
application will then want to produce some kind of response to indicate what
 
 paulb@346     16 
went on. Here are some examples of responses:</p>
 
 paulb@346     17 
<ul>
 
 paulb@346     18 
  <li>Returning the contents of a requested file.</li>
 
 paulb@346     19 
  <li>Showing a message telling the user that the requested operation
 
 paulb@346     20 
    succeeded or failed.</li>
 
 paulb@346     21 
  <li>Presenting a view onto the application with the results of the recent
 
 paulb@346     22 
    activity shown in a Web page.</li>
 
 paulb@346     23 
</ul>
 
 paulb@346     24 
 
 paulb@346     25 
<h2>Generating Responses</h2>
 
 paulb@346     26 
 
 paulb@346     27 
<p>The procedure involved in generating a response usually involves the
 
 paulb@346     28 
following steps:</p>
 
 paulb@346     29 
<ol>
 
 paulb@346     30 
  <li>Setting a response code to signal whether the application performed the
 
 paulb@346     31 
    requested operation successfully.</li>
 
 paulb@346     32 
  <li>Setting a content type and a <a>character encoding</a>.</li>
 
 paulb@346     33 
  <li>Producing content and sending it to the user.</li>
 
 paulb@346     34 
</ol>
 
 paulb@346     35 
 
 paulb@346     36 
<p>The kind of code involved may well resemble the following:</p>
 
 paulb@346     37 
<pre>from WebStack.Generic import ContentType
 
 paulb@346     38 
 
 paulb@346     39 
class MyResource:
 
 paulb@346     40 
    def respond(self, trans):
 
 paulb@346     41 
        [Perform the requested operations.]
 
 paulb@346     42 
 
 paulb@346     43 
        if [the operation was successful]:
 
 paulb@346     44 
            trans.set_response_code(200)
 
 paulb@346     45 
            trans.set_content_type(ContentType("text/html", encoding="utf-8"))
 
 paulb@346     46 
            out = trans.get_response_stream()
 
 paulb@346     47 
            out.write([some data either as a plain string suitably encoded or as Unicode])
 
 paulb@346     48 
        else:
 
 paulb@346     49 
            trans.set_response_code(500) # or some other code
 
 paulb@346     50 
            trans.set_content_type(ContentType("text/html", encoding="utf-8"))
 
 paulb@346     51 
            out = trans.get_response_stream()
 
 paulb@346     52 
            out.write([some other data either as a plain string suitably encoded or as Unicode])</pre>
 
 paulb@346     53 
 
 paulb@346     54 
<p>As discussed in <a href="encodings.html">"Character Encodings"</a>, care
 
 paulb@346     55 
must be taken generating the response so that it meets any expectations that
 
 paulb@346     56 
browsers and other Web clients may have.</p>
 
 paulb@346     57 
 
 paulb@346     58 
<div class="WebStack">
 
 paulb@346     59 
<h3>WebStack API - Response-Related Methods</h3>
 
 paulb@346     60 
 
 paulb@346     61 
<p>Transaction objects have various methods that can be used in generating
 
 paulb@346     62 
responses:</p>
 
 paulb@346     63 
<dl>
 
 paulb@346     64 
  <dt><code>set_response_code</code></dt>
 
 paulb@346     65 
    <dd>This accepts an integer value denoting the response condition as
 
 paulb@346     66 
      described in the HTTP specification. If this method is not used,
 
 paulb@346     67 
      WebStack sets a <code>200</code> status condition on the response,
 
 paulb@346     68 
      meaning that the request was processed successfully.</dd>
 
 paulb@346     69 
  <dt><code>set_content_type</code></dt>
 
 paulb@346     70 
    <dd>This accepts a content type object (typically
 
 paulb@346     71 
      <code>WebStack.Generic.ContentType</code>) which specifies both the
 
 paulb@346     72 
      media type and the character encoding (if relevant) of the data sent to
 
 paulb@346     73 
      the user. The media type describes the format of the data (eg.
 
 paulb@346     74 
      <code>text/html</code> - a Web page), whereas the character encoding
 
 paulb@346     75 
      describes how any character information on the page is encoded - see <a
 
 paulb@346     76 
      href="encodings.html">"Character Encodings"</a> for more
 
 paulb@346     77 
    information.</dd>
 
 paulb@346     78 
  <dt><code>get_response_stream</code></dt>
 
 paulb@346     79 
    <dd>This returns the output stream through which data may be sent to the
 
 paulb@346     80 
      user.</dd>
 
 paulb@346     81 
</dl>
 
 paulb@346     82 
</div>
 
 paulb@346     83 
</body>
 
 paulb@346     84 
</html>