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