# HG changeset patch # User paulb # Date 1169160048 0 # Node ID 559901c41ce2db084e7eb709ba8857367c3821e6 # Parent 973b3249ebe795a7b0f6b92458fbbc73fd3d21a0 [project @ 2007-01-18 22:40:48 by paulb] Added PathSelector notes about remembering the root path. Added LoginRedirectResource extension notes. Updated copyright details. diff -r 973b3249ebe7 -r 559901c41ce2 docs/COPYING.txt --- a/docs/COPYING.txt Thu Jan 18 22:40:07 2007 +0000 +++ b/docs/COPYING.txt Thu Jan 18 22:40:48 2007 +0000 @@ -1,7 +1,7 @@ Licence Agreement for WebStack ------------------------------ -Copyright (C) 2004, 2005, 2006 Paul Boddie +Copyright (C) 2004, 2005, 2006, 2007 Paul Boddie This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public diff -r 973b3249ebe7 -r 559901c41ce2 docs/attributes.html --- a/docs/attributes.html Thu Jan 18 22:40:07 2007 +0000 +++ b/docs/attributes.html Thu Jan 18 22:40:48 2007 +0000 @@ -34,4 +34,24 @@ the attributes dictionary exists as long as the transaction object itself. Should information need to be stored beyond the lifetime of a transaction, the appropriate persistent information facilities should -be used instead - see "Sessions and Persistent Information" for more details.

\ No newline at end of file +be used instead - see "Sessions and Persistent Information" for more details.

Storing the Application Location in an Attribute

One +use of attributes is to take the location of an application, defined in +terms of its path, and to store that information in an attribute. Such +information would then travel to different resources in an application +as part of the transaction, enabling those resources to generate things +like hyperlinks which contain "absolute" rather than "relative" +references to various parts of the application. Consider an application +deployed at the following URL:

http://application.business.com/bizapp/

Inside this application, we may have other URLs which expose certain functions:

http://application.business.com/bizapp/services/finance/accounting
http://application.business.com/bizapp/services/customer/invoice

It +may be interesting for these functions to know the location of the +top-level or root of the application in order to, for example, generate +hyperlinks to the top-level or to other established functions. Thus, we +may decide to remember the top-level path which would be the following:

/bizapp/

Now, normally the get_path_without_info method will provide this information, but what if we wanted to remember the following path instead...?

/bizapp/services/

In +fact, we can make use of the other path-related methods to obtain this +path, provided that we ask for this information at the correct point in +processing the request. Let us imagine that we have used the MapResource class to build up the path hierarchy:

resource = MapResource({
    "services" : MapResource({
        "finance" : finance_department,
        "customer" : customer_department
        })
    })

We +would want to define a resource to process the request and +remember the path details just before choosing between the finance and +customer departments. This resource would do the following:

Ask for the path without info, along with the processed virtual path info (as described in "Paths To and Within Applications").
Join the paths together.
Store the result on an attribute (called "root", perhaps).
Invoke another resource.

The advantage of doing this dynamically is that should we decide to change the location of the application or the path to services within it, we will not need to track down hard-coded path values and change them in lots of different places.

Fortunately, WebStack provides a class to do this work for us - PathSelector - and we can use it in the following way:

from WebStack.Resources.Selectors import PathSelector

resource = MapResource({
    "services" : PathSelector(
        MapResource({
            "finance" : finance_department,
            "customer" : customer_department
            })
        )
    })

Now, once the services part of the path has been detected, the PathSelector resource will discover the path details, store them on an attribute, and then invoke the MapResource which chooses between departments, which in turn invokes other resources, and so on. However, all of the resources "below" the PathSelector resource +will have an attribute called "root" which contains the selected "root +path" of the application (or at least the interesting part of the +application).

See the "Selectors" document for more details of the PathSelector class.

\ No newline at end of file diff -r 973b3249ebe7 -r 559901c41ce2 docs/login-redirect.html --- a/docs/login-redirect.html Thu Jan 18 22:40:07 2007 +0000 +++ b/docs/login-redirect.html Thu Jan 18 22:40:48 2007 +0000 @@ -3,7 +3,6 @@ LoginRedirect and Login Modules -

LoginRedirect and Login Modules

The LoginRedirect and Login modules @@ -102,7 +101,7 @@ for this parameter, a simple page is presented to the user informing them of the situation - it is recommended that a subclass of LoginRedirectResource be employed should more informative pages be required. - +

See the API documentation for the LoginRedirectResource class for more details.

Redirection from/to the Application

Some server/framework environments do not permit automatic @@ -124,7 +123,11 @@ support the "single sign-on" aspects of this mechanism - mixing in such classes with LoginAuthenticator may provide a solution to this -issue, however.

+issue, however.

Extending LoginRedirectResource

Sometimes, using LoginRedirectResource directly is not appropriate in an application. For example, specifying the app_url and login_url as absolute URLs (so that LoginRedirectResource can +redirect users into the application and over to the login screen) may +seem like excessive detail which will need to be changed if the +application is deployed even in a slightly different location. We might +therefore wish to use a PathSelector resource (see "Transaction Attributes" and "Selectors") to record the "root path" into an application and then to employ a login URL which is relative to the "root path".

To achieve this, LoginRedirectResource provides methods which can be overridden - get_app_url and get_login_url - and we might define a subclass of LoginRedirectResource as follows:

class MyLoginRedirectResource(LoginRedirectResource):

    "An example of customising LoginRedirectResource."

    def get_login_url(self, trans):

        "Use a different login URL, using 'trans' to find out what it might be."

        # Find out what the PathSelector stored for the root of the application.

        root_path = trans.get_attributes()["root"]

        # Return the value of the login_url attribute appended to the root path.

        return root_path + self.login_url

Since LoginRedirectResource calls the get_login_url method when forming the URL to redirect to the login resource, by overriding the original method from the LoginRedirectResource class we can define different behaviour. Of course, to take advantage of this new behaviour, we must instantiate MyLoginRedirectResource instead of LoginRedirectResource when setting up the application.

Deploying a Login Application

In order for this authentication mechanism to function in its entirety, a