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><meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 3 4 <title>Selectors - Components for Dispatching to Resources</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>Selectors - Components for Dispatching to Resources</h1> 8 <p>The <code>Selectors</code> module provides classes (although 9 currently only one class is supplied) which act as standard WebStack 10 resources, but which attempt to "select" other resources, dispatch each 11 request to those resources, and to cause various side-effects, mostly 12 on the attributes stored on the transaction object. These "selector" 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 14 non-trivial applications, it is often desirable to know the path or URL 15 to a particular resource, especially the "root" resource under which 16 the application or one of its components may reside. The <code>PathSelector</code> 17 class can be instantiated and be made to refer to a resource, recording 18 such path or URL details in an attribute for later inspection.</p><div class="WebStack"> 19 <h3>WebStack API - The PathSelector Class</h3> 20 21 <p>The <code>PathSelector</code> 22 class (found in the 23 <code>WebStack.Resources.Selectors</code> module) wraps resource 24 objects whose location (as indicated by a path or URL) should be 25 recorded as an attribute on the current transaction. The most common 26 use of the class is to record the "root" resource's location, 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> 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> 29 object and, indeed, all resource objects visited after this side-effect 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> 31 class provides additional information.</p></div><h2>Defining Encodings using EncodingSelector</h2><p>One 32 frequently bothersome aspect of writing Web applications involves the 33 processing and production of text in different encodings. Whilst the 34 WebStack API lets applications explicitly state the character encoding 35 for various operations, one often wants to be able to ignore such 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>, 37 an application-wide default encoding (or character set) will be 38 defined; this will result in request information being processed 39 according to the stated encoding and response information being 40 produced according to that encoding (see below for more details of the 41 latter activity).</p><div class="WebStack"> 42 <h3>WebStack API - The EncodingSelector Class</h3> 43 44 <p>The <code>EncodingSelector</code> 45 class (found in the 46 <code>WebStack.Resources.Selectors</code> module) wraps resource 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> 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> 49 method will only produce plain strings. This behaviour is justified by 50 the observation that, if conversion from an encoding to Unicode were to 51 take place, the resulting character values may be unsuitable 52 substitutes for the original byte values in applications intending to 53 make use of the raw incoming (possibly binary) data. A recipe for 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 55 a default encoding, responses will generally be written in that 56 encoding, at least if textual data is written to the response stream as 57 Unicode objects. However, the content type must typically be set either 58 to match the encoding in use or to not specify an encoding. It may 59 become necessary to find out what the response stream encoding is when 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 61 some activities, such as making a Unicode stream from the request 62 stream, it is desirable to find out the encoding set by the selector. 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> 64 class provides additional information, along with the <a href="responses.html">"Responses and Presentation"</a> document.</p></div><p></p><br /></body></html>