1.1 --- a/docs/index.html Sun Apr 24 15:43:10 2005 +0000
1.2 +++ b/docs/index.html Sun Apr 24 22:47:22 2005 +0000
1.3 @@ -1,36 +1,32 @@
1.4 -<?xml version="1.0" encoding="iso-8859-1"?>
1.5 -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
1.6 - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.7 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.8 <html xmlns="http://www.w3.org/1999/xhtml">
1.9 <head>
1.10 <title>Creating Web Applications with WebStack</title>
1.11 - <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.12 + <meta name="generator"
1.13 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.14 <link href="styles.css" rel="stylesheet" type="text/css" />
1.15 </head>
1.16 -
1.17 <body>
1.18 <h1>Creating Web Applications with WebStack</h1>
1.19 -
1.20 -<p>This set of documents describes the process of making a Web application
1.21 +<p>This set of documents describes the process of making a Web
1.22 +application
1.23 using the WebStack framework.</p>
1.24 -
1.25 <h2>Setting Up</h2>
1.26 -
1.27 <p>First of all, let us assume that the WebStack distribution has been
1.28 unpacked and now sits in the <code>WebStack-0.9</code> directory.</p>
1.29 -
1.30 -<p>Before we begin, we must make sure that the WebStack package is available
1.31 +<p>Before we begin, we must make sure that the WebStack package is
1.32 +available
1.33 to Python. The easiest way to do this is to change into the
1.34 <code>WebStack-0.9</code> directory and to run the <code>setup.py</code>
1.35 script provided with the version of Python you are going to be using
1.36 (possibly as a privileged user like <code>root</code>):</p>
1.37 <pre>cd WebStack-0.9<br />python setup.py install</pre>
1.38 -
1.39 -<p>If you don't want to install WebStack in this way, or if you can't do so
1.40 -because you don't have <code>root</code> privileges, you can just make sure
1.41 -that the <code>WebStack-0.9</code> directory sits on the
1.42 +<p>If you don't want to install WebStack in this way, or if you can't
1.43 +do so
1.44 +because you don't have <code>root</code> privileges, you can just make
1.45 +sure
1.46 +that the <code>WebStack-0.9</code> directory sits on your
1.47 <code>PYTHONPATH</code>.</p>
1.48 -
1.49 <h2>About WebStack Applications</h2>
1.50 <ul>
1.51 <li><a href="anatomy.html">Anatomy of a WebStack Application</a></li>
2.1 --- a/docs/paths-filesystem.html Sun Apr 24 15:43:10 2005 +0000
2.2 +++ b/docs/paths-filesystem.html Sun Apr 24 22:47:22 2005 +0000
2.3 @@ -1,70 +1,117 @@
2.4 -<?xml version="1.0" encoding="iso-8859-1"?>
2.5 -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2.6 - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2.7 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2.8 <html xmlns="http://www.w3.org/1999/xhtml">
2.9 <head>
2.10 - <title>Treating the Path Like a Filesystem</title>
2.11 - <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
2.12 + <title>Treating the Path Like a
2.13 +Filesystem</title>
2.14 + <meta name="generator"
2.15 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
2.16 <link href="styles.css" rel="stylesheet" type="text/css" />
2.17 </head>
2.18 -
2.19 <body>
2.20 -<h1>Treating the Path Like a Filesystem</h1>
2.21 -
2.22 -<p>...or as a reference into deeply categorized resources. In this approach,
2.23 +<h1>Treating the Path Like a
2.24 +Filesystem</h1>
2.25 +<p>...or as a reference into
2.26 +deeply categorized resources. In this approach,
2.27 we take a path like this...</p>
2.28 <pre>/documents/news/2005/article.html</pre>
2.29 -
2.30 -<p>...and we consider <code>documents</code>, <code>news</code>, and
2.31 -<code>2005</code> as directories, and <code>article.html</code> as a
2.32 +<p>...and we consider <code>documents</code>,
2.33 +<code>news</code>,
2.34 +and
2.35 +<code>2005</code>
2.36 +as directories, and <code>article.html</code>
2.37 +as a
2.38 file-like resource. If we ask for the following path...</p>
2.39 <pre>/documents/news/2005</pre>
2.40 -
2.41 -<p>...we may decide to provide a listing of files within that directory, or
2.42 -we may decide to refuse such a request. Indeed some approaches will insist
2.43 -that such a listing may only be produced with the following path instead:</p>
2.44 +<p>...we may decide to provide a
2.45 +listing of files within that directory, or
2.46 +we may decide to refuse such a request. Indeed some kinds of
2.47 +applications insist
2.48 +that such a listing may only be produced with the following path
2.49 +instead:</p>
2.50 <pre>/documents/news/2005/</pre>
2.51 -
2.52 -<p>Applications of this kind are quite common since the publishing of files
2.53 -on a Web server often just involves exposing parts of a real filesystem to
2.54 +<p>Applications of this kind are
2.55 +quite common since the publishing of files
2.56 +on a Web server often just involves exposing parts of a real filesystem
2.57 +to
2.58 requests through the server.</p>
2.59 -
2.60 -<h2>Resource Hierarchies in WebStack</h2>
2.61 -
2.62 -<p>We might decide to represent components in these kinds of paths using
2.63 -different resource classes, so that folders or directories are represented by
2.64 -one kind of resource class and files or documents are represented by other
2.65 -kinds of resource classes. We might then predefine a hierarchy of resources
2.66 -so that when a request arrives for a resource, we can check it against the
2.67 -hierarchy and process the request according to whichever type of resource is
2.68 -being accessed.</p>
2.69 -
2.70 -<p>Consider the above hierarchy; we would implement such a hierarchy with a
2.71 -resource object mapped to <code>documents</code>, and that resource object
2.72 +<h2>Resource Hierarchies in
2.73 +WebStack</h2>
2.74 +<p>There are a number of different
2.75 +ways that paths can be interpreted and handled in WebStack
2.76 +applications, including...</p>
2.77 +<ul>
2.78 + <li>Using predefined hierarchies
2.79 +of resources.</li>
2.80 + <li>By inspecting the path in a
2.81 +top-level resource and then creating resources to deal with different
2.82 +cases.</li>
2.83 + <li>By handling all kinds of
2.84 +paths in the same resource.</li>
2.85 +</ul>
2.86 +<h3>Predefining Resource
2.87 +Hierarchies</h3>
2.88 +<p>We might decide to represent
2.89 +components in these kinds of paths using
2.90 +different resource classes; for example:</p>
2.91 +<ul>
2.92 + <li>Folders or directories are
2.93 +represented by a special resource class which contains other
2.94 +folders and possibly some files.</li>
2.95 + <li>Files or documents are
2.96 +represented by special resource classes which provide access
2.97 +to the content of such files.</li>
2.98 +</ul>
2.99 +We might then predefine a hierarchy of resources
2.100 +so that when a request arrives for a resource, we can check it against
2.101 +the
2.102 +hierarchy and process the request according to whichever type of
2.103 +resource is
2.104 +being accessed. For example:<br />
2.105 +<ul>
2.106 + <li><code>documents</code>
2.107 + <ul>
2.108 + <li><code>news</code>
2.109 + <ul>
2.110 + <li><code>2005</code>
2.111 + <ul>
2.112 + <li><code>article.html</code></li>
2.113 + <li><code>another.html</code></li>
2.114 + </ul>
2.115 + </li>
2.116 + <li><code>2004</code>
2.117 + <ul>
2.118 + <li><code>document.html</code></li>
2.119 + </ul>
2.120 + </li>
2.121 + </ul>
2.122 + </li>
2.123 + </ul>
2.124 + </li>
2.125 +</ul>
2.126 +<p>Consider the above hierarchy;
2.127 +we would implement such a hierarchy with a
2.128 +resource object mapped to <code>documents</code>,
2.129 +and that resource object
2.130 would contain a mapping of years to other resources. Eventually, at the
2.131 -bottom of the hierarchy, individual resources would represent articles and be
2.132 +bottom of the hierarchy, individual resources would represent articles
2.133 +and be
2.134 mapped to names such as <code>article.html</code>.</p>
2.135 -
2.136 <div class="WebStack">
2.137 -<h3>WebStack API - Predefining Resource Hierarchies in Adapter Code</h3>
2.138 -
2.139 -<p>WebStack provides a resource class for convenient mapping of path
2.140 +<h3>WebStack API - Predefining
2.141 +Resource Hierarchies in Adapter Code</h3>
2.142 +<p>WebStack provides a resource
2.143 +class for convenient mapping of path
2.144 components (ie. names) to resource objects:
2.145 <code>WebStack.Resources.ResourceMap.MapResource</code></p>
2.146 -
2.147 -<p>This class can be used in adapter or "glue" code to initialise an
2.148 +<p>This class can be used in <a href="deploying.html">adapter code</a>
2.149 +to initialise an
2.150 application as follows:</p>
2.151 -<pre>from WebStack.Resources.ResourceMap import MapResource
2.152 -article_resource = [some resource representing the article]
2.153 -year_2004_resource = [a MapResource with definitions]
2.154 -year_2005_resource = MapResource({"article.html" : article_resource})
2.155 -news_resource = MapResource({"2005" : year_2005_resource, "2004" : year_2004_resource})
2.156 -documents_resource = MapResource({"news" : news_resource})
2.157 -top_resource = MapResource({"documents" : documents_resource})</pre>
2.158 +<pre>from WebStack.Resources.ResourceMap import MapResource<br />from MyApplication import FileResource # import some resource class<br /><br />article_resource = FileResource(...) # make a resource representing the article<br />document_resource = FileResource(...) # make a resource representing the document<br />year_2004_resource = MapResource({"document.html" : document_resource})<br />year_2005_resource = MapResource({"article.html" : article_resource})<br />news_resource = MapResource({"2005" : year_2005_resource, "2004" : year_2004_resource})<br />documents_resource = MapResource({"news" : news_resource})<br />top_resource = MapResource({"documents" : documents_resource})</pre>
2.159 </div>
2.160 -
2.161 -<p>Of course, predefining hierarchies is not the only way to support such
2.162 +<p>Of course, predefining resource
2.163 +objects is not the only way to support such
2.164 hierarchies. We could inspect paths and act dynamically on the supplied
2.165 -information.</p>
2.166 +information, either choosing to create resources or choosing to handle
2.167 +such paths in the same resource.</p>
2.168 </body>
2.169 </html>