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