1.1 --- a/docs/selectors.html Wed Feb 28 19:49:11 2007 +0000
1.2 +++ b/docs/selectors.html Wed Feb 28 22:31:10 2007 +0000
1.3 @@ -10,7 +10,7 @@
1.4 resources, but which attempt to "select" other resources, dispatch each
1.5 request to those resources, and to cause various side-effects, mostly
1.6 on the attributes stored on the transaction object. These "selector"
1.7 -classes behave those in the <code>ResourceMap</code> module, but aspire to be more generally applicable.</p><h2>Introducing PathSelector</h2><p>In
1.8 +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
1.9 non-trivial applications, it is often desirable to know the path or URL
1.10 to a particular resource, especially the "root" resource under which
1.11 the application or one of its components may reside. The <code>PathSelector</code>
1.12 @@ -28,4 +28,37 @@
1.13 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>
1.14 object and, indeed, all resource objects visited after this side-effect
1.15 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>
1.16 -class provides additional information.</p></div></body></html>
1.17 \ No newline at end of file
1.18 +class provides additional information.</p></div><h2>Defining Encodings using EncodingSelector</h2><p>One
1.19 +frequently bothersome aspect of writing Web applications involves the
1.20 +processing and production of text in different encodings. Whilst the
1.21 +WebStack API lets applications explicitly state the character encoding
1.22 +for various operations, one often wants to be able to ignore such
1.23 +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>,
1.24 +an application-wide default encoding (or character set) will be
1.25 +defined; this will result in request information being processed
1.26 +according to the stated encoding and response information being
1.27 +produced according to that encoding (see below for more details of the
1.28 +latter activity).</p><div class="WebStack">
1.29 +<h3>WebStack API - The EncodingSelector Class</h3>
1.30 +
1.31 +<p>The <code>EncodingSelector</code>
1.32 +class (found in the
1.33 +<code>WebStack.Resources.Selectors</code> module) wraps resource
1.34 +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>
1.35 +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>
1.36 +method will only produce plain strings. This behaviour is justified by
1.37 +the observation that, if conversion from an encoding to Unicode were to
1.38 +take place, the resulting character values may be unsuitable
1.39 +substitutes for the original byte values in applications intending to
1.40 +make use of the raw incoming (possibly binary) data. A recipe for
1.41 +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
1.42 +a default encoding, responses will generally be written in that
1.43 +encoding, at least if textual data is written to the response stream as
1.44 +Unicode objects. However, the content type must typically be set either
1.45 +to match the encoding in use or to not specify an encoding. It may
1.46 +become necessary to find out what the response stream encoding is when
1.47 +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
1.48 +some activities, such as making a Unicode stream from the request
1.49 +stream, it is desirable to find out the encoding set by the selector.
1.50 +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>
1.51 +class provides additional information, along with the <a href="responses.html">"Responses and Presentation"</a> document.</p></div><p></p><br /></body></html>
1.52 \ No newline at end of file