1.1 --- a/docs/deploying.html Sat Jan 06 20:30:37 2007 +0000
1.2 +++ b/docs/deploying.html Sun Jan 07 00:27:04 2007 +0000
1.3 @@ -1,11 +1,9 @@
1.4 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.5 -<html xmlns="http://www.w3.org/1999/xhtml">
1.6 -<head>
1.7 - <title>Deploying a WebStack Application</title>
1.8 - <meta name="generator"
1.9 - content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.10 - <link href="styles.css" rel="stylesheet" type="text/css" />
1.11 -</head>
1.12 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
1.13 +
1.14 + <title>Deploying a WebStack Application</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.15 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
1.16 +
1.17 <body>
1.18 <h1>Deploying a WebStack Application</h1>
1.19 <p>The process of deploying a WebStack application should be as
1.20 @@ -17,8 +15,7 @@
1.21 <h2>The Adapter Code</h2>
1.22 <p>What adapter or "glue" code does is to set up your applications main
1.23 resource object and to hook that object up with the underlying server
1.24 -environment. For the <code>MyApplication</code> <a
1.25 - href="resources.html">example</a>, together with a simple environment,
1.26 +environment. For the <code>MyApplication</code> <a href="resources.html">example</a>, together with a simple environment,
1.27 looks something like
1.28 this:</p>
1.29 <pre>from WebStack.Adapters.BaseHTTPRequestHandler import deploy # import the support for the server environment<br />from MyApplication import MyResource # import the main resource class<br />print "Serving..."<br />deploy(MyResource()) # connect a resource object to the server environment</pre>
1.30 @@ -26,20 +23,28 @@
1.31 Python standard library, you can just run this code, making sure that
1.32 the <code>MyApplication</code> module or package is on your <code>PYTHONPATH</code>.
1.33 Then, you can visit <code>http://localhost:8080</code> in your
1.34 -browser and see the result.</p>
1.35 +browser and see the result.</p><h3>Root Resources and Site Maps</h3><p>The
1.36 +above example suggested the direct deployment of a specific resource,
1.37 +and this was quickly achieved by instantiating the resource within the
1.38 +call to the <code>deploy</code> function. However, it may be more
1.39 +desirable to have an application provide a function within the module
1.40 +or package containing the resources which causes their initialisation
1.41 +in a more sophisticated fashion and which returns a resource object
1.42 +ready for use. Let us suppose that the <code>MyApplication</code> module provides a function for this purpose:</p><pre>from WebStack.Adapters.BaseHTTPRequestHandler import deploy # import the support for the server environment<br />from MyApplication import get_site_map # import the function indicating the "root" resource<br />print "Serving..."<br />deploy(get_site_map()) # connect a resource object to the server environment</pre><p>Whilst
1.43 +this appears to be trading one name for another, the intent is really
1.44 +to provide a layer of abstraction which hides the details of resource
1.45 +classes from the deployment code, even if the <code>get_site_map</code> function is only as simple as the following:</p><pre>def get_site_map():<br /> return MyResource()</pre><p>Of course, this function may be made more complicated as the need arises.</p>
1.46 <h3>More Demanding Adapter Code</h3>
1.47 <p>Unfortunately, not all server environments can be connected up with
1.48 applications this easily. Some environments require special classes and
1.49 functions to be defined in the adapter code in order for
1.50 applications to
1.51 be properly integrated into those environments. A summary of the
1.52 -requirements of each environment can be found in <a
1.53 - href="writing-adapters.html">"Writing Adapters"</a>.</p>
1.54 +requirements of each environment can be found in <a href="writing-adapters.html">"Writing Adapters"</a>.</p>
1.55 <h2>The Deployment Process</h2>
1.56 <ul>
1.57 <li><a href="writing-adapters.html">Writing Adapters</a></li>
1.58 <li><a href="pythonpath.html">Getting PYTHONPATH Right</a></li>
1.59 <li><a href="deploying-applications.html">Deploying an Application</a></li>
1.60 </ul>
1.61 -</body>
1.62 -</html>
1.63 +</body></html>
1.64 \ No newline at end of file
2.1 --- a/docs/developing.html Sat Jan 06 20:30:37 2007 +0000
2.2 +++ b/docs/developing.html Sun Jan 07 00:27:04 2007 +0000
2.3 @@ -82,4 +82,4 @@
2.4 provides a number of potentially useful modules either providing
2.5 resource classes for direct use in applications, or providing other
2.6 kinds of classes and functions which may be used to perform particular
2.7 -activities.</p><p>The following resources are provided for direct use in applications:</p><ul><li><a href="login-redirect.html">LoginRedirect and Login Modules</a></li><li><a href="resource-map.html">ResourceMap - Simple Mappings from Names to Resources</a></li><li><a href="directory-resource.html">DirectoryResource - Serving Static Content</a></li><li><a href="file-resource.html">FileResource - Serving Individual Files</a></li></ul><p>WebStack also provides modules which provide session-like access to different kinds of repositories:</p><ul><li><a href="directory-repository.html">DirectoryRepository - Simple Access to Files in a Directory</a></li></ul></body></html>
2.8 \ No newline at end of file
2.9 +activities.</p><p>The following resources are provided for direct use in applications:</p><ul><li><a href="login-redirect.html">LoginRedirect and Login Modules</a></li><li><a href="resource-map.html">ResourceMap - Simple Mappings from Names to Resources</a></li><li><a href="directory-resource.html">DirectoryResource - Serving Static Content</a></li><li><a href="file-resource.html">FileResource - Serving Individual Files</a></li><li><a href="selectors.html">Selectors - Components for Dispatching to Resources</a></li></ul><p>WebStack also provides modules which provide session-like access to different kinds of repositories:</p><ul><li><a href="directory-repository.html">DirectoryRepository - Simple Access to Files in a Directory</a></li></ul></body></html>
2.10 \ No newline at end of file
3.1 --- a/docs/resource-map.html Sat Jan 06 20:30:37 2007 +0000
3.2 +++ b/docs/resource-map.html Sun Jan 07 00:27:04 2007 +0000
3.3 @@ -3,7 +3,6 @@
3.4
3.5 <title>ResourceMap - Simple Mappings from Names to Resources</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
3.6 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
3.7 -
3.8 <body>
3.9 <h1>ResourceMap - Simple Mappings from Names to Resources</h1>
3.10 <p>The <code>ResourceMap</code> module provides classes (although
3.11 @@ -27,13 +26,4 @@
3.12 path:</p><pre>/2005/article.html</pre><p>Here, the name <code>2005</code> would match, leaving the following information unprocessed:</p><pre>/article.html</pre><p>Here, the name <code>article.html</code> would match. However, let us consider the following original virtual "path info" instead:</p><pre>/documents/news/2005/</pre><p>After processing the leading components, we may instead end up with this:</p><pre>/</pre><p>Here, only an empty string as the name will specifically match the above.</p><h4>Further Reading</h4><p>The <a href="../apidocs/public/WebStack.Resources.ResourceMap.MapResource-class.html">API documentation</a> for the <code>MapResource</code>
3.13 class provides more detail on the subject of name matching, including
3.14 the special "catch all" name and a discussion of the pass-through
3.15 -parameter.</p><h4>Initialisation</h4><p><code>MapResource</code> objects are initialised with the following parameters:</p><dl><dt><code>mapping</code></dt><dd>A dictionary or dictionary-like object mapping names to resource objects. See above and the <a href="../apidocs/public/WebStack.Resources.ResourceMap.MapResource-class.html">API documentation</a> for a description of names.</dd><dt><code>pass_through</code></dt><dd>Indicates
3.16 -whether a component should be removed from the virtual "path info" if
3.17 -no specific match was made with any of the names, but if the "catch
3.18 -all" name selected a resource. By default, this parameter is set to a
3.19 -false value.</dd><dt><code>directory_redirects</code></dt><dd>Indicates whether a trailing <code>/</code> character should be added to paths which do not end with such a character, causing a <a href="redirection.html">redirect</a> if such a character has to be added.</dd><dt><code>urlencoding</code></dt><dd>When
3.20 -specified, this parameter forces a particular interpretation of "URL
3.21 -encoded" character values in the path. Otherwise, the default encoding
3.22 -is employed to interpret such values. (See <a href="paths.html">"URLs and Paths"</a> for an explanation of "URL encoded" values.)</dd></dl>
3.23 -
3.24 -</div></body></html>
3.25 \ No newline at end of file
3.26 +parameter.</p></div></body></html>
3.27 \ No newline at end of file
4.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
4.2 +++ b/docs/selectors.html Sun Jan 07 00:27:04 2007 +0000
4.3 @@ -0,0 +1,31 @@
4.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4.5 +<html xmlns="http://www.w3.org/1999/xhtml"><head><meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
4.6 +
4.7 + <title>Selectors - Components for Dispatching to Resources</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
4.8 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
4.9 +<body>
4.10 +<h1>Selectors - Components for Dispatching to Resources</h1>
4.11 +<p>The <code>Selectors</code> module provides classes (although
4.12 +currently only one class is supplied) which act as standard WebStack
4.13 +resources, but which attempt to "select" other resources, dispatch each
4.14 +request to those resources, and to cause various side-effects, mostly
4.15 +on the attributes stored on the transaction object. These "selector"
4.16 +classes behave those in the <code>ResourceMap</code> module, but aspire to be more generally applicable.</p><h2>Introducing PathSelector</h2><p>In
4.17 +non-trivial applications, it is often desirable to know the path or URL
4.18 +to a particular resource, especially the "root" resource under which
4.19 +the application or one of its components may reside. The <code>PathSelector</code>
4.20 +class can be instantiated and be made to refer to a resource, recording
4.21 +such path or URL details in an attribute for later inspection.</p><div class="WebStack">
4.22 +<h3>WebStack API - The PathSelector Class</h3>
4.23 +
4.24 +<p>The <code>PathSelector</code>
4.25 +class (found in the
4.26 +<code>WebStack.Resources.Selectors</code> module) wraps resource
4.27 +objects whose location (as indicated by a path or URL) should be
4.28 +recorded as an attribute on the current transaction. The most common
4.29 +use of the class is to record the "root" resource's location,
4.30 +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>
4.31 +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>
4.32 +object and, indeed, all resource objects visited after this side-effect
4.33 +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>
4.34 +class provides additional information.</p></div></body></html>
4.35 \ No newline at end of file