WebStack

Annotated docs/responses.html

629:e0d4c80ffc97
509:d384955273f3
486:e325db7e56b7
2005-11-17 paulb file changeset files shortlog [project @ 2005-11-17 19:21:34 by paulb] Added links to the redirection document, a brief explanation of redirection, and a link to XSLTools.
paulb@354 1 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
paulb@486 2 
<html xmlns="http://www.w3.org/1999/xhtml"><head>
paulb@486 3
paulb@486 4 
  <title>Responses and Presentation</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
paulb@486 5 
  <link href="styles.css" rel="stylesheet" type="text/css" /></head>
paulb@346 6 
<body>
paulb@346 7 
<h1>Responses and Presentation</h1>
paulb@354 8 
<p>After performing some kind of
paulb@354 9 
processing on input information, an
paulb@354 10 
application will then want to produce some kind of response to indicate
paulb@354 11 
what
paulb@346 12 
went on. Here are some examples of responses:</p>
paulb@346 13 
<ul>
paulb@354 14 
  <li>Returning the contents of a
paulb@354 15 
requested file.</li>
paulb@354 16 
  <li>Showing a message telling
paulb@354 17 
the user that the requested operation succeeded or failed.</li>
paulb@354 18 
  <li>Presenting a view onto the
paulb@354 19 
application with the results of the recent activity shown in a Web page.</li>
paulb@346 20 
</ul>
paulb@346 21 
<h2>Generating Responses</h2>
paulb@354 22 
<p>The procedure involved in
paulb@354 23 
generating a response usually involves the
paulb@346 24 
following steps:</p>
paulb@346 25 
<ol>
paulb@354 26 
  <li>Setting a response code to
paulb@354 27 
signal whether the application performed the requested operation
paulb@354 28 
successfully.</li>
paulb@486 29 
  <li>Setting a content type and a <a>character encoding</a>.</li><li>Possibly setting some response headers.</li>
paulb@354 30 
  <li>Producing content and
paulb@354 31 
sending it to the user.</li>
paulb@346 32 
</ol>
paulb@354 33 
<p>The kind of code involved may
paulb@354 34 
well resemble the following:</p>
paulb@354 35 
<pre>from WebStack.Generic import ContentType<br /><br />class MyResource:<br />    def respond(self, trans):<br />        [Perform the requested operations.]<br /><br />        if [the operation was successful]:<br />            trans.set_response_code(200)<br />            trans.set_content_type(ContentType("text/html", encoding="utf-8"))<br />            out = trans.get_response_stream()<br />            out.write([some data either as a plain string suitably encoded or as Unicode])<br />        else:<br />            trans.set_response_code(500) # or some other code<br />            trans.set_content_type(ContentType("text/html", encoding="utf-8"))<br />            out = trans.get_response_stream()<br />            out.write([some other data either as a plain string suitably encoded or as Unicode])</pre>
paulb@354 36 
<p>As discussed in <a href="encodings.html">"Character Encodings"</a>,
paulb@354 37 
care
paulb@354 38 
must be taken generating the response so that it meets any expectations
paulb@354 39 
that
paulb@346 40 
browsers and other Web clients may have.</p>
paulb@346 41 
<div class="WebStack">
paulb@354 42 
<h3>WebStack API -
paulb@354 43 
Response-Related Methods</h3>
paulb@354 44 
<p>Transaction objects have
paulb@354 45 
various methods that can be used in generating
paulb@346 46 
responses:</p>
paulb@346 47 
<dl>
paulb@346 48 
  <dt><code>set_response_code</code></dt>
paulb@354 49 
  <dd>This accepts an integer
paulb@354 50 
value denoting the response condition as described in the HTTP
paulb@354 51 
specification. If this method is not used, WebStack sets a <code>200</code>
paulb@354 52 
status condition on the response, meaning that the request was
paulb@354 53 
processed successfully.</dd>
paulb@346 54 
  <dt><code>set_content_type</code></dt>
paulb@354 55 
  <dd>This accepts a content type
paulb@354 56 
object (typically <code>WebStack.Generic.ContentType</code>)
paulb@354 57 
which specifies both the media type and the character encoding (if
paulb@354 58 
relevant) of the data sent to the user. The media type describes the
paulb@354 59 
format of the data (eg. <code>text/html</code>
paulb@354 60 
- a Web page), whereas the character encoding describes how any
paulb@486 61 
character information on the page is encoded - see <a href="encodings.html">"Character Encodings"</a>
paulb@486 62 
for more information.</dd><dt><code>set_header_value</code></dt><dd>This
paulb@486 63 
accepts a header name and a corresponding value. Response headers
paulb@486 64 
convey information to the user (and their software) which is comparable
paulb@486 65 
to that found in <a href="headers.html">request headers</a> sent in to
paulb@486 66 
the Web application; for example, the content type information is
paulb@486 67 
transmitted using response headers (using the&nbsp;<code>Content-Type</code> header name), although the above&nbsp;<code>set_content_type</code> method is a more convenient means of preparing such information.</dd>
paulb@346 68 
  <dt><code>get_response_stream</code></dt>
paulb@354 69 
  <dd>This returns the output
paulb@354 70 
stream through which data may be sent to the user.</dd>
paulb@346 71 
</dl>
paulb@346 72 
</div>
paulb@364 73 
<h2>Ending the Response Explicitly</h2>
paulb@364 74 
<p>Although it is possible to produce some output and then to let
paulb@364 75 
the&nbsp;<code>respond</code> function complete normally, sometimes it
paulb@364 76 
is appropriate to terminate the response and to hand control straight
paulb@364 77 
back to the server environment; in other words, to decide that no more
paulb@364 78 
activity will be performed within the application and to send the
paulb@364 79 
response immediately. Whilst just using a&nbsp;<code>return</code>
paulb@364 80 
statement might be adequate in many applications...</p>
paulb@364 81 
<pre>        # In the respond method...<br />        if some_condition:<br />            [Produce a response.]<br />            return<br />        [Produce a different response.]</pre>
paulb@364 82 
<p>...sometimes a resource's&nbsp;<code>respond</code> method is being
paulb@364 83 
called from another resource, and it may be the case that this other
paulb@364 84 
resource may produce additional output if control is returned to it.</p>
paulb@364 85 
<p>To provide a definitive end of response signal, a special exception
paulb@364 86 
is available:</p>
paulb@364 87 
<pre>from WebStack.Generic import EndOfResponse<br /><br />[The usual declarations for the resource and the respond method...]<br /><br />        # In the respond method (possibly called by another resource)...<br />        if some_condition:<br />            [Produce a response.]<br />            raise EndOfResponse</pre>
paulb@364 88 
<p>This exception, when raised, ensures that the response is sent
paulb@364 89 
exactly as the resource intended upon raising the exception. Note that
paulb@364 90 
although <code>WebStack.Generic.EndOfResponse</code> is an exception,
paulb@364 91 
it will not cause an error condition or change the response code in any
paulb@509 92 
way.</p><h2>Sending the User Elsewhere</h2><p>Instead
paulb@509 93 
of generating any real response, it is also possible to direct an
paulb@509 94 
application's user to another resource or application. This is done by
paulb@509 95 
performing a "redirect" by sending a special response header to the
paulb@509 96 
client, as described in the <a href="redirection.html">"Redirection"</a> document.</p><h2>Integrating with Content Generators</h2>
paulb@354 97 
<p>Just as applications might need to integrate with other systems in
paulb@354 98 
order to fetch information or to perform operations on behalf of the
paulb@354 99 
user, the generation of response content can also be made a lot easier
paulb@354 100 
by using external libraries. In the above example code, the process of
paulb@354 101 
obtaining and formatting the actual data to be written out has been
paulb@354 102 
left unspecified, but for anything more complicated than "hello world"
paulb@354 103 
it is usually advisable to consider using templating systems which
paulb@354 104 
combine raw data and templates to produce formatted output that can be
paulb@354 105 
displayed as a Web page (amongst other things).</p>
paulb@354 106 
<p>See&nbsp;<a href="integrating.html">"Integration with Other Systems"</a>
paulb@509 107 
for more information on the principles of using such external libraries. See also <a href="http://www.boddie.org.uk/python/XSLTools.html">XSLTools</a>
paulb@509 108 
for a distribution of utilities, including a Web forms framework called
paulb@509 109 
XSLForms, which can be of use in generating content for Web
paulb@509 110 
applications.</p>
paulb@486 111 
</body></html>