# HG changeset patch # User paulb # Date 1168129624 0 # Node ID c392bca946825fa51a6177ab2418b5e25c23836f # Parent fc930c1b31536bae2fdcfec07c22c93094439c5c [project @ 2007-01-07 00:27:04 by paulb] Removed redundant API documentation. Added notes about site maps. Added selector documentation. diff -r fc930c1b3153 -r c392bca94682 docs/deploying.html --- a/docs/deploying.html Sat Jan 06 20:30:37 2007 +0000 +++ b/docs/deploying.html Sun Jan 07 00:27:04 2007 +0000 @@ -1,11 +1,9 @@ - - - Deploying a WebStack Application - - - + + + Deploying a WebStack Application + +

Deploying a WebStack Application

The process of deploying a WebStack application should be as @@ -17,8 +15,7 @@

The Adapter Code

What adapter or "glue" code does is to set up your applications main resource object and to hook that object up with the underlying server -environment. For the MyApplication example, together with a simple environment, +environment. For the MyApplication example, together with a simple environment, looks something like this:

from WebStack.Adapters.BaseHTTPRequestHandler import deploy    # import the support for the server environment
from MyApplication import MyResource                           # import the main resource class
print "Serving..."
deploy(MyResource())                                           # connect a resource object to the server environment
@@ -26,20 +23,28 @@ Python standard library, you can just run this code, making sure that the MyApplication module or package is on your PYTHONPATH. Then, you can visit http://localhost:8080 in your -browser and see the result.

+browser and see the result.

Root Resources and Site Maps

The +above example suggested the direct deployment of a specific resource, +and this was quickly achieved by instantiating the resource within the +call to the deploy function. However, it may be more +desirable to have an application provide a function within the module +or package containing the resources which causes their initialisation +in a more sophisticated fashion and which returns a resource object +ready for use. Let us suppose that the MyApplication module provides a function for this purpose:

from WebStack.Adapters.BaseHTTPRequestHandler import deploy    # import the support for the server environment
from MyApplication import get_site_map                         # import the function indicating the "root" resource
print "Serving..."
deploy(get_site_map())                                         # connect a resource object to the server environment

Whilst +this appears to be trading one name for another, the intent is really +to provide a layer of abstraction which hides the details of resource +classes from the deployment code, even if the get_site_map function is only as simple as the following:

def get_site_map():
    return MyResource()

Of course, this function may be made more complicated as the need arises.

More Demanding Adapter Code

Unfortunately, not all server environments can be connected up with applications this easily. Some environments require special classes and functions to be defined in the adapter code in order for applications to be properly integrated into those environments. A summary of the -requirements of each environment can be found in "Writing Adapters".

+requirements of each environment can be found in "Writing Adapters".

The Deployment Process

- - + \ No newline at end of file diff -r fc930c1b3153 -r c392bca94682 docs/developing.html --- a/docs/developing.html Sat Jan 06 20:30:37 2007 +0000 +++ b/docs/developing.html Sun Jan 07 00:27:04 2007 +0000 @@ -82,4 +82,4 @@ provides a number of potentially useful modules either providing resource classes for direct use in applications, or providing other kinds of classes and functions which may be used to perform particular -activities.

The following resources are provided for direct use in applications:

WebStack also provides modules which provide session-like access to different kinds of repositories:

\ No newline at end of file +activities.

The following resources are provided for direct use in applications:

WebStack also provides modules which provide session-like access to different kinds of repositories:

\ No newline at end of file diff -r fc930c1b3153 -r c392bca94682 docs/resource-map.html --- a/docs/resource-map.html Sat Jan 06 20:30:37 2007 +0000 +++ b/docs/resource-map.html Sun Jan 07 00:27:04 2007 +0000 @@ -3,7 +3,6 @@ ResourceMap - Simple Mappings from Names to Resources -

ResourceMap - Simple Mappings from Names to Resources

The ResourceMap module provides classes (although @@ -27,13 +26,4 @@ path:

/2005/article.html

Here, the name 2005 would match, leaving the following information unprocessed:

/article.html

Here, the name article.html would match. However, let us consider the following original virtual "path info" instead:

/documents/news/2005/

After processing the leading components, we may instead end up with this:

/

Here, only an empty string as the name will specifically match the above.

Further Reading

The API documentation for the MapResource class provides more detail on the subject of name matching, including the special "catch all" name and a discussion of the pass-through -parameter.

Initialisation

MapResource objects are initialised with the following parameters:

mapping
A dictionary or dictionary-like object mapping names to resource objects. See above and the API documentation for a description of names.
pass_through
Indicates -whether a component should be removed from the virtual "path info" if -no specific match was made with any of the names, but if the "catch -all" name selected a resource. By default, this parameter is set to a -false value.
directory_redirects
Indicates whether a trailing / character should be added to paths which do not end with such a character, causing a redirect if such a character has to be added.
urlencoding
When -specified, this parameter forces a particular interpretation of "URL -encoded" character values in the path. Otherwise, the default encoding -is employed to interpret such values. (See "URLs and Paths" for an explanation of "URL encoded" values.)
- - \ No newline at end of file +parameter.

\ No newline at end of file diff -r fc930c1b3153 -r c392bca94682 docs/selectors.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/selectors.html Sun Jan 07 00:27:04 2007 +0000 @@ -0,0 +1,31 @@ + + + + Selectors - Components for Dispatching to Resources + + +

Selectors - Components for Dispatching to Resources

+

The Selectors module provides classes (although +currently only one class is supplied) which act as standard WebStack +resources, but which attempt to "select" other resources, dispatch each +request to those resources, and to cause various side-effects, mostly +on the attributes stored on the transaction object. These "selector" +classes behave those in the ResourceMap module, but aspire to be more generally applicable.

Introducing PathSelector

In +non-trivial applications, it is often desirable to know the path or URL +to a particular resource, especially the "root" resource under which +the application or one of its components may reside. The PathSelector +class can be instantiated and be made to refer to a resource, recording +such path or URL details in an attribute for later inspection.

+

WebStack API - The PathSelector Class

+ +

The PathSelector +class (found in the +WebStack.Resources.Selectors module) wraps resource +objects whose location (as indicated by a path or URL) should be +recorded as an attribute on the current transaction. The most common +use of the class is to record the "root" resource's location, +and this would be done as follows:

def get_site_map():
    return PathSelector(MyResource())

Here, the get_site_map +function (as described in the "Deploying a WebStack Application" document) would provide a PathSelector object instead of an instance of the MyResource class. However, the side-effect of combining these two resources would be the availability of an attribute named root on the transaction object. Thus, the "root" MyResource +object and, indeed, all resource objects visited after this side-effect +has occurred will have access to the "root" path or URL information.

Further Reading

The API documentation for the PathSelector +class provides additional information.

\ No newline at end of file