| paulb@354 | 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| paulb@346 | 2 | <html xmlns="http://www.w3.org/1999/xhtml"> |
| paulb@346 | 3 | <head> |
| paulb@346 | 4 | <title>Responses and Presentation</title> |
| paulb@354 | 5 | <meta name="generator" |
| paulb@354 | 6 | content="amaya 8.1a, see http://www.w3.org/Amaya/" /> |
| paulb@346 | 7 | <link href="styles.css" rel="stylesheet" type="text/css" /> |
| paulb@346 | 8 | </head> |
| paulb@346 | 9 | <body> |
| paulb@346 | 10 | <h1>Responses and Presentation</h1> |
| paulb@354 | 11 | <p>After performing some kind of |
| paulb@354 | 12 | processing on input information, an |
| paulb@354 | 13 | application will then want to produce some kind of response to indicate |
| paulb@354 | 14 | what |
| paulb@346 | 15 | went on. Here are some examples of responses:</p> |
| paulb@346 | 16 | <ul> |
| paulb@354 | 17 | <li>Returning the contents of a |
| paulb@354 | 18 | requested file.</li> |
| paulb@354 | 19 | <li>Showing a message telling |
| paulb@354 | 20 | the user that the requested operation succeeded or failed.</li> |
| paulb@354 | 21 | <li>Presenting a view onto the |
| paulb@354 | 22 | application with the results of the recent activity shown in a Web page.</li> |
| paulb@346 | 23 | </ul> |
| paulb@346 | 24 | <h2>Generating Responses</h2> |
| paulb@354 | 25 | <p>The procedure involved in |
| paulb@354 | 26 | generating a response usually involves the |
| paulb@346 | 27 | following steps:</p> |
| paulb@346 | 28 | <ol> |
| paulb@354 | 29 | <li>Setting a response code to |
| paulb@354 | 30 | signal whether the application performed the requested operation |
| paulb@354 | 31 | successfully.</li> |
| paulb@354 | 32 | <li>Setting a content type and a |
| paulb@354 | 33 | <a>character encoding</a>.</li> |
| paulb@354 | 34 | <li>Producing content and |
| paulb@354 | 35 | sending it to the user.</li> |
| paulb@346 | 36 | </ol> |
| paulb@354 | 37 | <p>The kind of code involved may |
| paulb@354 | 38 | well resemble the following:</p> |
| paulb@354 | 39 | <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 | 40 | <p>As discussed in <a href="encodings.html">"Character Encodings"</a>, |
| paulb@354 | 41 | care |
| paulb@354 | 42 | must be taken generating the response so that it meets any expectations |
| paulb@354 | 43 | that |
| paulb@346 | 44 | browsers and other Web clients may have.</p> |
| paulb@346 | 45 | <div class="WebStack"> |
| paulb@354 | 46 | <h3>WebStack API - |
| paulb@354 | 47 | Response-Related Methods</h3> |
| paulb@354 | 48 | <p>Transaction objects have |
| paulb@354 | 49 | various methods that can be used in generating |
| paulb@346 | 50 | responses:</p> |
| paulb@346 | 51 | <dl> |
| paulb@346 | 52 | <dt><code>set_response_code</code></dt> |
| paulb@354 | 53 | <dd>This accepts an integer |
| paulb@354 | 54 | value denoting the response condition as described in the HTTP |
| paulb@354 | 55 | specification. If this method is not used, WebStack sets a <code>200</code> |
| paulb@354 | 56 | status condition on the response, meaning that the request was |
| paulb@354 | 57 | processed successfully.</dd> |
| paulb@346 | 58 | <dt><code>set_content_type</code></dt> |
| paulb@354 | 59 | <dd>This accepts a content type |
| paulb@354 | 60 | object (typically <code>WebStack.Generic.ContentType</code>) |
| paulb@354 | 61 | which specifies both the media type and the character encoding (if |
| paulb@354 | 62 | relevant) of the data sent to the user. The media type describes the |
| paulb@354 | 63 | format of the data (eg. <code>text/html</code> |
| paulb@354 | 64 | - a Web page), whereas the character encoding describes how any |
| paulb@354 | 65 | character information on the page is encoded - see <a |
| paulb@354 | 66 | href="encodings.html">"Character Encodings"</a> |
| paulb@354 | 67 | for more 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@354 | 73 | <h2>Integrating with Content Generators</h2> |
| paulb@354 | 74 | <p>Just as applications might need to integrate with other systems in |
| paulb@354 | 75 | order to fetch information or to perform operations on behalf of the |
| paulb@354 | 76 | user, the generation of response content can also be made a lot easier |
| paulb@354 | 77 | by using external libraries. In the above example code, the process of |
| paulb@354 | 78 | obtaining and formatting the actual data to be written out has been |
| paulb@354 | 79 | left unspecified, but for anything more complicated than "hello world" |
| paulb@354 | 80 | it is usually advisable to consider using templating systems which |
| paulb@354 | 81 | combine raw data and templates to produce formatted output that can be |
| paulb@354 | 82 | displayed as a Web page (amongst other things).</p> |
| paulb@354 | 83 | <p>See <a href="integrating.html">"Integration with Other Systems"</a> |
| paulb@354 | 84 | for more information on the principles of using such external libraries.</p> |
| paulb@346 | 85 | </body> |
| paulb@346 | 86 | </html> |
