paulb@654 | 1 | <?xml version="1.0" encoding="iso-8859-1"?> |
paulb@601 | 2 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
paulb@601 | 3 | <html xmlns="http://www.w3.org/1999/xhtml"><head><meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> |
paulb@654 | 4 | <title>Selectors - Components for Dispatching to Resources</title> |
paulb@601 | 5 | <link href="styles.css" rel="stylesheet" type="text/css" /></head> |
paulb@601 | 6 | <body> |
paulb@601 | 7 | <h1>Selectors - Components for Dispatching to Resources</h1> |
paulb@601 | 8 | <p>The <code>Selectors</code> module provides classes (although |
paulb@601 | 9 | currently only one class is supplied) which act as standard WebStack |
paulb@601 | 10 | resources, but which attempt to "select" other resources, dispatch each |
paulb@601 | 11 | request to those resources, and to cause various side-effects, mostly |
paulb@601 | 12 | on the attributes stored on the transaction object. These "selector" |
paulb@654 | 13 | classes behave those in the <code>ResourceMap</code> module, but aspire to be more generally applicable.</p><h2>Selecting Path Roots with PathSelector</h2><p>In |
paulb@601 | 14 | non-trivial applications, it is often desirable to know the path or URL |
paulb@601 | 15 | to a particular resource, especially the "root" resource under which |
paulb@601 | 16 | the application or one of its components may reside. The <code>PathSelector</code> |
paulb@601 | 17 | class can be instantiated and be made to refer to a resource, recording |
paulb@601 | 18 | such path or URL details in an attribute for later inspection.</p><div class="WebStack"> |
paulb@601 | 19 | <h3>WebStack API - The PathSelector Class</h3> |
paulb@601 | 20 | |
paulb@601 | 21 | <p>The <code>PathSelector</code> |
paulb@601 | 22 | class (found in the |
paulb@654 | 23 | <code>WebStack.Resources.Selectors</code> module) wraps resource |
paulb@601 | 24 | objects whose location (as indicated by a path or URL) should be |
paulb@601 | 25 | recorded as an attribute on the current transaction. The most common |
paulb@601 | 26 | use of the class is to record the "root" resource's location, |
paulb@601 | 27 | and this would be done as follows:</p><pre>def get_site_map():<br /> return PathSelector(MyResource())</pre><p>Here, the <code>get_site_map</code> |
paulb@654 | 28 | function (as described in the <a href="deploying.html">"Deploying a WebStack Application"</a> document) would provide a <code>PathSelector</code> object instead of an instance of the <code>MyResource</code> class. However, the side-effect of combining these two resources would be the availability of an attribute named <code>root</code> on the transaction object. Thus, the "root" <code>MyResource</code> |
paulb@601 | 29 | object and, indeed, all resource objects visited after this side-effect |
paulb@601 | 30 | has occurred will have access to the "root" path or URL information.</p><h4>Further Reading</h4><p>The <a href="../apidocs/public/WebStack.Resources.Selectors.PathSelector-class.html">API documentation</a> for the <code>PathSelector</code> |
paulb@629 | 31 | class provides additional information.</p></div><h2>Defining Encodings using EncodingSelector</h2><p>One |
paulb@629 | 32 | frequently bothersome aspect of writing Web applications involves the |
paulb@629 | 33 | processing and production of text in different encodings. Whilst the |
paulb@629 | 34 | WebStack API lets applications explicitly state the character encoding |
paulb@629 | 35 | for various operations, one often wants to be able to ignore such |
paulb@654 | 36 | details since they start to clutter up application code. The <code>EncodingSelector</code> class offers a basic solution which is compatible with the mechanisms in transaction objects: by wrapping WebStack resources with instances of <code>EncodingSelector</code>, |
paulb@629 | 37 | an application-wide default encoding (or character set) will be |
paulb@654 | 38 | defined; this will result in request information being processed |
paulb@629 | 39 | according to the stated encoding and response information being |
paulb@629 | 40 | produced according to that encoding (see below for more details of the |
paulb@629 | 41 | latter activity).</p><div class="WebStack"> |
paulb@629 | 42 | <h3>WebStack API - The EncodingSelector Class</h3> |
paulb@629 | 43 | |
paulb@629 | 44 | <p>The <code>EncodingSelector</code> |
paulb@629 | 45 | class (found in the |
paulb@654 | 46 | <code>WebStack.Resources.Selectors</code> module) wraps resource |
paulb@654 | 47 | objects whilst changing the default encoding of the current transaction object. The class can be applied like this:</p><pre>def get_site_map():<br /> return EncodingSelector(MyResource(), "utf-8")</pre><p>Here, the <code>get_site_map</code> |
paulb@654 | 48 | function (as described in the <a href="deploying.html">"Deploying a WebStack Application"</a> document) would provide a <code>EncodingSelector</code> object instead of an instance of the <code>MyResource</code> class. However, the <code>EncodingSelector</code> will forward requests on to <code>MyResource</code> (since it "selects" that resource), whilst setting the default encoding to be <code>"utf-8"</code>.</p><h4>Request Streams and Encodings</h4><p>Although a default encoding affects the processing of request parameters, direct access to the request stream using the <code>get_request_stream</code> |
paulb@629 | 49 | method will only produce plain strings. This behaviour is justified by |
paulb@629 | 50 | the observation that, if conversion from an encoding to Unicode were to |
paulb@629 | 51 | take place, the resulting character values may be unsuitable |
paulb@629 | 52 | substitutes for the original byte values in applications intending to |
paulb@629 | 53 | make use of the raw incoming (possibly binary) data. A recipe for |
paulb@654 | 54 | making a Unicode stream is provided in the <a href="encodings.html">"Character Encodings"</a> document.</p><h4>Response Encodings and Content Types</h4><p>Although <code>EncodingSelector</code> sets |
paulb@654 | 55 | a default encoding, responses will generally be written in that |
paulb@629 | 56 | encoding, at least if textual data is written to the response stream as |
paulb@629 | 57 | Unicode objects. However, the content type must typically be set either |
paulb@629 | 58 | to match the encoding in use or to not specify an encoding. It may |
paulb@629 | 59 | become necessary to find out what the response stream encoding is when |
paulb@654 | 60 | creating a <code>ContentType</code> object. For this and other purposes, the <code>get_response_stream_encoding</code> method is available on the transaction object<code></code>:</p><pre>from WebStack.Generic import ContentType<br /><br />def respond(self, trans):<br /><br /> # Some code...<br /><br /> trans.set_content_type(ContentType("text/html", trans.get_response_stream_encoding()))<br /> out = trans.get_response_stream()<br /> out.write(some_unicode_object)</pre><p>However, it is completely acceptable to omit the encoding information where a default encoding has been set:</p><pre> trans.set_content_type(ContentType("text/html")) # no encoding/charset specified<br /></pre><h4>Reading the Default Directly</h4><p>For |
paulb@629 | 61 | some activities, such as making a Unicode stream from the request |
paulb@629 | 62 | stream, it is desirable to find out the encoding set by the selector. |
paulb@654 | 63 | This information is made available on transaction objects as the <code>default_charset</code> attribute.</p><h4>Further Reading</h4><p>The <a href="../apidocs/public/WebStack.Resources.Selectors.EncodingSelector-class.html">API documentation</a> for the <code>EncodingSelector</code> |
paulb@654 | 64 | class provides additional information, along with the <a href="responses.html">"Responses and Presentation"</a> document.</p></div><p></p><br /></body></html> |