1.1 --- a/docs/COPYING.txt Thu Jan 18 22:40:07 2007 +0000
1.2 +++ b/docs/COPYING.txt Thu Jan 18 22:40:48 2007 +0000
1.3 @@ -1,7 +1,7 @@
1.4 Licence Agreement for WebStack
1.5 ------------------------------
1.6
1.7 -Copyright (C) 2004, 2005, 2006 Paul Boddie <paul@boddie.org.uk>
1.8 +Copyright (C) 2004, 2005, 2006, 2007 Paul Boddie <paul@boddie.org.uk>
1.9
1.10 This library is free software; you can redistribute it and/or
1.11 modify it under the terms of the GNU Lesser General Public
2.1 --- a/docs/attributes.html Thu Jan 18 22:40:07 2007 +0000
2.2 +++ b/docs/attributes.html Thu Jan 18 22:40:48 2007 +0000
2.3 @@ -34,4 +34,24 @@
2.4 the attributes dictionary exists as long as the transaction object
2.5 itself. Should information need to be stored beyond the lifetime of a
2.6 transaction, the appropriate persistent information facilities should
2.7 -be used instead - see <a href="sessions.html">"Sessions and Persistent Information"</a> for more details.</p></body></html>
2.8 \ No newline at end of file
2.9 +be used instead - see <a href="sessions.html">"Sessions and Persistent Information"</a> for more details.</p><h2>Storing the Application Location in an Attribute</h2><p>One
2.10 +use of attributes is to take the location of an application, defined in
2.11 +terms of its path, and to store that information in an attribute. Such
2.12 +information would then travel to different resources in an application
2.13 +as part of the transaction, enabling those resources to generate things
2.14 +like hyperlinks which contain "absolute" rather than "relative"
2.15 +references to various parts of the application. Consider an application
2.16 +deployed at the following URL:</p><pre>http://application.business.com/bizapp/</pre><p>Inside this application, we may have other URLs which expose certain functions:</p><pre>http://application.business.com/bizapp/services/finance/accounting<br />http://application.business.com/bizapp/services/customer/invoice</pre><p>It
2.17 +may be interesting for these functions to know the location of the
2.18 +top-level or root of the application in order to, for example, generate
2.19 +hyperlinks to the top-level or to other established functions. Thus, we
2.20 +may decide to remember the top-level path which would be the following:</p><pre>/bizapp/</pre><p>Now, normally the <code>get_path_without_info</code> method will provide this information, but what if we wanted to remember the following path instead...?</p><pre>/bizapp/services/</pre><p>In
2.21 +fact, we can make use of the other path-related methods to obtain this
2.22 +path, provided that we ask for this information at the correct point in
2.23 +processing the request. Let us imagine that we have used the <a href="resource-map.html"><code>MapResource</code></a> class to build up the path hierarchy:</p><pre>resource = MapResource({<br /> "services" : MapResource({<br /> "finance" : finance_department,<br /> "customer" : customer_department<br /> })<br /> })</pre><p>We
2.24 +would want to define a resource to process the request and
2.25 +remember the path details just before choosing between the finance and
2.26 +customer departments. This resource would do the following:</p><ol><li>Ask for the path without info, along with the processed virtual path info (as described in <a href="path-info.html">"Paths To and Within Applications"</a>).</li><li>Join the paths together.</li><li>Store the result on an attribute (called "root", perhaps).</li><li>Invoke another resource.</li></ol><p>The advantage of doing this dynamically is that should we decide to change the location of the application or the path to <code>services</code> within it, we will not need to track down hard-coded path values and change them in lots of different places.</p><p>Fortunately, WebStack provides a class to do this work for us - <code>PathSelector</code> - and we can use it in the following way:</p><pre>from WebStack.Resources.Selectors import PathSelector<br /><br />resource = MapResource({<br /> "services" : PathSelector(<br /> MapResource({<br /> "finance" : finance_department,<br /> "customer" : customer_department<br /> })<br /> )<br /> })</pre><p>Now, once the <code>services</code> part of the path has been detected, the <code>PathSelector</code> resource will discover the path details, store them on an attribute, and then invoke the <code>MapResource</code> which chooses between departments, which in turn invokes other resources, and so on. However, all of the resources "below" the <code>PathSelector</code> resource
2.27 +will have an attribute called "root" which contains the selected "root
2.28 +path" of the application (or at least the interesting part of the
2.29 +application).</p><p>See the <a href="selectors.html">"Selectors"</a> document for more details of the <code>PathSelector</code> class.</p></body></html>
2.30 \ No newline at end of file
3.1 --- a/docs/login-redirect.html Thu Jan 18 22:40:07 2007 +0000
3.2 +++ b/docs/login-redirect.html Thu Jan 18 22:40:48 2007 +0000
3.3 @@ -3,7 +3,6 @@
3.4
3.5 <title>LoginRedirect and Login Modules</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>LoginRedirect and Login Modules</h1>
3.10 <p>The <code>LoginRedirect</code> and <code>Login</code> modules
3.11 @@ -102,7 +101,7 @@
3.12 for this parameter, a simple page is presented to the user informing
3.13 them of the situation - it is recommended that a subclass of <code>LoginRedirectResource</code>
3.14 be employed should more informative pages be required.</dd>
3.15 -</dl>
3.16 +</dl><p>See the <a href="../apidocs/public/WebStack.Resources.LoginRedirect.LoginRedirectResource-class.html">API documentation</a> for the <code>LoginRedirectResource</code> class for more details.</p>
3.17 </div>
3.18 <h3>Redirection from/to the Application</h3>
3.19 <p>Some server/framework environments do not permit automatic
3.20 @@ -124,7 +123,11 @@
3.21 support the "single sign-on" aspects of this mechanism - mixing in such
3.22 classes with <code>LoginAuthenticator</code> may provide a solution to
3.23 this
3.24 -issue, however.</p>
3.25 +issue, however.</p><h2>Extending LoginRedirectResource</h2><p>Sometimes, using <code>LoginRedirectResource</code> directly is not appropriate in an application. For example, specifying the <code>app_url</code> and <code>login_url</code> as absolute URLs (so that <code>LoginRedirectResource</code> can
3.26 +redirect users into the application and over to the login screen) may
3.27 +seem like excessive detail which will need to be changed if the
3.28 +application is deployed even in a slightly different location. We might
3.29 +therefore wish to use a <code>PathSelector</code> resource (see <a href="attributes.html">"Transaction Attributes"</a> and <a href="selectors.html">"Selectors"</a>) to record the "root path" into an application and then to employ a login URL which is relative to the "root path".</p><p>To achieve this, <code>LoginRedirectResource</code> provides methods which can be overridden - <code>get_app_url</code> and <code>get_login_url</code> - and we might define a subclass of <code>LoginRedirectResource</code> as follows:</p><pre>class MyLoginRedirectResource(LoginRedirectResource):<br /><br /> "An example of customising LoginRedirectResource."<br /><br /> def get_login_url(self, trans):<br /><br /> "Use a different login URL, using 'trans' to find out what it might be."<br /><br /> # Find out what the PathSelector stored for the root of the application.<br /><br /> root_path = trans.get_attributes()["root"]<br /><br /> # Return the value of the login_url attribute appended to the root path.<br /><br /> return root_path + self.login_url</pre><p>Since <code>LoginRedirectResource</code> calls the <code>get_login_url</code> method when forming the URL to redirect to the login resource, by overriding the original method from the <code>LoginRedirectResource</code> class we can define different behaviour. Of course, to take advantage of this new behaviour, we must instantiate <code>MyLoginRedirectResource</code> instead of <code>LoginRedirectResource</code> when setting up the application.</p>
3.30 <h2>Deploying a Login Application</h2>
3.31 <p>In order for this authentication mechanism to function in its
3.32 entirety, a