1 <?xml version="1.0" encoding="iso-8859-1"?> 2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3 <html xmlns="http://www.w3.org/1999/xhtml"><head> 4 <title>Responses and Presentation</title> 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 <h2>Unicode and the Response Stream</h2><p>Although an encoding may be specified or be set as a default by the <code>EncodingSelector</code> (see <a href="selectors.html">"Selectors - Components for Dispatching to Resources"</a>), 37 it should be noted that the encoding of textual information will only 38 take place if Unicode objects are written to the stream. Where binary 39 information or information which should not be changed is being 40 written, this must be supplied as plain strings to the transaction 41 object's <code>write</code> method.</p><p>As discussed in <a href="encodings.html">"Character Encodings"</a>, 42 care 43 must be taken generating the response so that it meets any expectations 44 that 45 browsers and other Web clients may have.</p> 46 <div class="WebStack"> 47 <h3>WebStack API - 48 Response-Related Methods</h3> 49 <p>Transaction objects have 50 various methods that can be used in generating 51 responses:</p> 52 <dl> 53 <dt><code>set_response_code</code></dt> 54 <dd>This accepts an integer 55 value denoting the response condition as described in the HTTP 56 specification. If this method is not used, WebStack sets a <code>200</code> 57 status condition on the response, meaning that the request was 58 processed successfully.</dd> 59 <dt><code>set_content_type</code></dt> 60 <dd>This accepts a content type 61 object (typically <code>WebStack.Generic.ContentType</code>) 62 which specifies both the media type and the character encoding (if 63 relevant) of the data sent to the user. The media type describes the 64 format of the data (eg. <code>text/html</code> 65 - a Web page), whereas the character encoding describes how any 66 character information on the page is encoded - see <a href="encodings.html">"Character Encodings"</a> 67 for more information.</dd><dt><code>set_header_value</code></dt><dd>This 68 accepts a header name and a corresponding value. Response headers 69 convey information to the user (and their software) which is comparable 70 to that found in <a href="headers.html">request headers</a> sent in to 71 the Web application; for example, the content type information is 72 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> 73 <dt><code>get_response_stream</code></dt> 74 <dd>This returns the output 75 stream through which data may be sent to the user.</dd> 76 </dl> 77 </div> 78 <h2>Ending the Response Explicitly</h2> 79 <p>Although it is possible to produce some output and then to let 80 the <code>respond</code> function complete normally, sometimes it 81 is appropriate to terminate the response and to hand control straight 82 back to the server environment; in other words, to decide that no more 83 activity will be performed within the application and to send the 84 response immediately. Whilst just using a <code>return</code> 85 statement might be adequate in many applications...</p> 86 <pre> # In the respond method...<br /> if some_condition:<br /> [Produce a response.]<br /> return<br /> [Produce a different response.]</pre> 87 <p>...sometimes a resource's <code>respond</code> method is being 88 called from another resource, and it may be the case that this other 89 resource may produce additional output if control is returned to it.</p> 90 <p>To provide a definitive end of response signal, a special exception 91 is available:</p> 92 <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> 93 <p>This exception, when raised, ensures that the response is sent 94 exactly as the resource intended upon raising the exception. Note that 95 although <code>WebStack.Generic.EndOfResponse</code> is an exception, 96 it will not cause an error condition or change the response code in any 97 way.</p><h2>Sending the User Elsewhere</h2><p>Instead 98 of generating any real response, it is also possible to direct an 99 application's user to another resource or application. This is done by 100 performing a "redirect" by sending a special response header to the 101 client, as described in the <a href="redirection.html">"Redirection"</a> document.</p><h2>Integrating with Content Generators</h2> 102 <p>Just as applications might need to integrate with other systems in 103 order to fetch information or to perform operations on behalf of the 104 user, the generation of response content can also be made a lot easier 105 by using external libraries. In the above example code, the process of 106 obtaining and formatting the actual data to be written out has been 107 left unspecified, but for anything more complicated than "hello world" 108 it is usually advisable to consider using templating systems which 109 combine raw data and templates to produce formatted output that can be 110 displayed as a Web page (amongst other things).</p> 111 <p>See <a href="integrating.html">"Integration with Other Systems"</a> 112 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> 113 for a distribution of utilities, including a Web forms framework called 114 XSLForms, which can be of use in generating content for Web 115 applications.</p> 116 </body></html>