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