1.1 --- a/docs/responses.html Mon Apr 25 22:03:10 2005 +0000
1.2 +++ b/docs/responses.html Mon Apr 25 22:04:02 2005 +0000
1.3 @@ -1,84 +1,86 @@
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 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.8 <html xmlns="http://www.w3.org/1999/xhtml">
1.9 <head>
1.10 <title>Responses and Presentation</title>
1.11 - <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.12 + <meta name="generator"
1.13 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.14 <link href="styles.css" rel="stylesheet" type="text/css" />
1.15 </head>
1.16 -
1.17 <body>
1.18 <h1>Responses and Presentation</h1>
1.19 -
1.20 -<p>After performing some kind of processing on input information, an
1.21 -application will then want to produce some kind of response to indicate what
1.22 +<p>After performing some kind of
1.23 +processing on input information, an
1.24 +application will then want to produce some kind of response to indicate
1.25 +what
1.26 went on. Here are some examples of responses:</p>
1.27 <ul>
1.28 - <li>Returning the contents of a requested file.</li>
1.29 - <li>Showing a message telling the user that the requested operation
1.30 - succeeded or failed.</li>
1.31 - <li>Presenting a view onto the application with the results of the recent
1.32 - activity shown in a Web page.</li>
1.33 + <li>Returning the contents of a
1.34 +requested file.</li>
1.35 + <li>Showing a message telling
1.36 +the user that the requested operation succeeded or failed.</li>
1.37 + <li>Presenting a view onto the
1.38 +application with the results of the recent activity shown in a Web page.</li>
1.39 </ul>
1.40 -
1.41 <h2>Generating Responses</h2>
1.42 -
1.43 -<p>The procedure involved in generating a response usually involves the
1.44 +<p>The procedure involved in
1.45 +generating a response usually involves the
1.46 following steps:</p>
1.47 <ol>
1.48 - <li>Setting a response code to signal whether the application performed the
1.49 - requested operation successfully.</li>
1.50 - <li>Setting a content type and a <a>character encoding</a>.</li>
1.51 - <li>Producing content and sending it to the user.</li>
1.52 + <li>Setting a response code to
1.53 +signal whether the application performed the requested operation
1.54 +successfully.</li>
1.55 + <li>Setting a content type and a
1.56 + <a>character encoding</a>.</li>
1.57 + <li>Producing content and
1.58 +sending it to the user.</li>
1.59 </ol>
1.60 -
1.61 -<p>The kind of code involved may well resemble the following:</p>
1.62 -<pre>from WebStack.Generic import ContentType
1.63 -
1.64 -class MyResource:
1.65 - def respond(self, trans):
1.66 - [Perform the requested operations.]
1.67 -
1.68 - if [the operation was successful]:
1.69 - trans.set_response_code(200)
1.70 - trans.set_content_type(ContentType("text/html", encoding="utf-8"))
1.71 - out = trans.get_response_stream()
1.72 - out.write([some data either as a plain string suitably encoded or as Unicode])
1.73 - else:
1.74 - trans.set_response_code(500) # or some other code
1.75 - trans.set_content_type(ContentType("text/html", encoding="utf-8"))
1.76 - out = trans.get_response_stream()
1.77 - out.write([some other data either as a plain string suitably encoded or as Unicode])</pre>
1.78 -
1.79 -<p>As discussed in <a href="encodings.html">"Character Encodings"</a>, care
1.80 -must be taken generating the response so that it meets any expectations that
1.81 +<p>The kind of code involved may
1.82 +well resemble the following:</p>
1.83 +<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>
1.84 +<p>As discussed in <a href="encodings.html">"Character Encodings"</a>,
1.85 +care
1.86 +must be taken generating the response so that it meets any expectations
1.87 +that
1.88 browsers and other Web clients may have.</p>
1.89 -
1.90 <div class="WebStack">
1.91 -<h3>WebStack API - Response-Related Methods</h3>
1.92 -
1.93 -<p>Transaction objects have various methods that can be used in generating
1.94 +<h3>WebStack API -
1.95 +Response-Related Methods</h3>
1.96 +<p>Transaction objects have
1.97 +various methods that can be used in generating
1.98 responses:</p>
1.99 <dl>
1.100 <dt><code>set_response_code</code></dt>
1.101 - <dd>This accepts an integer value denoting the response condition as
1.102 - described in the HTTP specification. If this method is not used,
1.103 - WebStack sets a <code>200</code> status condition on the response,
1.104 - meaning that the request was processed successfully.</dd>
1.105 + <dd>This accepts an integer
1.106 +value denoting the response condition as described in the HTTP
1.107 +specification. If this method is not used, WebStack sets a <code>200</code>
1.108 +status condition on the response, meaning that the request was
1.109 +processed successfully.</dd>
1.110 <dt><code>set_content_type</code></dt>
1.111 - <dd>This accepts a content type object (typically
1.112 - <code>WebStack.Generic.ContentType</code>) which specifies both the
1.113 - media type and the character encoding (if relevant) of the data sent to
1.114 - the user. The media type describes the format of the data (eg.
1.115 - <code>text/html</code> - a Web page), whereas the character encoding
1.116 - describes how any character information on the page is encoded - see <a
1.117 - href="encodings.html">"Character Encodings"</a> for more
1.118 - information.</dd>
1.119 + <dd>This accepts a content type
1.120 +object (typically <code>WebStack.Generic.ContentType</code>)
1.121 +which specifies both the media type and the character encoding (if
1.122 +relevant) of the data sent to the user. The media type describes the
1.123 +format of the data (eg. <code>text/html</code>
1.124 +- a Web page), whereas the character encoding describes how any
1.125 +character information on the page is encoded - see <a
1.126 + href="encodings.html">"Character Encodings"</a>
1.127 +for more information.</dd>
1.128 <dt><code>get_response_stream</code></dt>
1.129 - <dd>This returns the output stream through which data may be sent to the
1.130 - user.</dd>
1.131 + <dd>This returns the output
1.132 +stream through which data may be sent to the user.</dd>
1.133 </dl>
1.134 </div>
1.135 +<h2>Integrating with Content Generators</h2>
1.136 +<p>Just as applications might need to integrate with other systems in
1.137 +order to fetch information or to perform operations on behalf of the
1.138 +user, the generation of response content can also be made a lot easier
1.139 +by using external libraries. In the above example code, the process of
1.140 +obtaining and formatting the actual data to be written out has been
1.141 +left unspecified, but for anything more complicated than "hello world"
1.142 +it is usually advisable to consider using templating systems which
1.143 +combine raw data and templates to produce formatted output that can be
1.144 +displayed as a Web page (amongst other things).</p>
1.145 +<p>See <a href="integrating.html">"Integration with Other Systems"</a>
1.146 +for more information on the principles of using such external libraries.</p>
1.147 </body>
1.148 </html>