1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/anatomy.html Fri Apr 08 22:33:56 2005 +0000
1.3 @@ -0,0 +1,67 @@
1.4 +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
1.5 +<html xmlns="http://www.w3.org/1999/xhtml">
1.6 +<head>
1.7 + <title>Anatomy of a WebStack Application</title>
1.8 + <meta name="generator"
1.9 + content="amaya 8.1a, see http://www.w3.org/Amaya/">
1.10 + <link xmlns:xlink="http://www.w3.org/1999/xlink" href="styles.css"
1.11 + rel="stylesheet" type="text/css">
1.12 +</head>
1.13 +<body>
1.14 +<h1>Anatomy of a WebStack Application</h1>
1.15 +<p>The simplest way to think of a Web application is as just some code
1.16 +which
1.17 +gets run every time an HTTP request arrives at a specific network
1.18 +address and
1.19 +which produces an HTTP response. Without WebStack, such code often
1.20 +needs to
1.21 +be tailored to the software which causes it to be run, but with
1.22 +WebStack you
1.23 +just need to do this:</p>
1.24 +<ol>
1.25 + <li>Write some application code which uses the WebStack API - this
1.26 +code can be run within any of the supported environments.</li>
1.27 + <li>Write some simple adapter or "glue" code - this code makes the
1.28 +application work with each of the environments that you want to use and
1.29 +should be much smaller in size than the application code.</li>
1.30 +</ol>
1.31 +<p>Most of the time, you need only to think about the first activity
1.32 +(writing
1.33 +against the WebStack API).<br>
1.34 +</p>
1.35 +<h2>A Very Simple Example</h2>
1.36 +In the simplest case, you just need to produce a Python class which
1.37 +takes
1.38 +this form:
1.39 +<pre>class MyResource:<br><br> "This is a resource - something which defines the behaviour of an application."<br><br> def respond(self, trans):<br> [Examine the transaction, decide what the user wants to do.]<br> [Perform some kind of action with the information supplied.]<br> [Produce some kind of response which tells the user what happened.]</pre>
1.40 +<p>The parts of the pseudo-code in the above text which aren't valid
1.41 +Python
1.42 +(ie. the bits in square brackets) will use various WebStack API calls
1.43 +to look
1.44 +at what the user specified in the request and to send information back
1.45 +to the
1.46 +user in the response.<br>
1.47 +</p>
1.48 +<p>WebStack applications consist of resource classes which contain the
1.49 +application code. In the above example, the only thing we need to
1.50 +consider is what our code does, not how resource objects are created
1.51 +and invoked (that is done in the adapter code). In more complicated
1.52 +applications, there may be a need to create our own resource objects
1.53 +explicitly, but this is not particularly interesting to think about at
1.54 +this point - see <a href="paths-filesystem.html">"Treating the Path
1.55 +Like a Filesystem"</a> for a discussion of multiple resource objects.<br>
1.56 +</p>
1.57 +<h2>Design Considerations</h2>
1.58 +<p>When writing an application, we must consider a number of factors
1.59 +which
1.60 +have an impact on the code (and other things) that we will need to
1.61 +provide as
1.62 +part of the finished product or service.</p>
1.63 +<ul>
1.64 + <li><a href="paths.html">URLs and Paths</a></li>
1.65 + <li><a href="methods.html">Request Methods</a></li>
1.66 + <li><a href="parameters.html">Request Parameters and Uploads</a></li>
1.67 + <li><a href="responses.html">Responses and Presentation</a></li>
1.68 +</ul>
1.69 +</body>
1.70 +</html>
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/docs/index.html Fri Apr 08 22:33:56 2005 +0000
2.3 @@ -0,0 +1,38 @@
2.4 +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2.5 +<html xmlns="http://www.w3.org/1999/xhtml">
2.6 +<head>
2.7 + <title>Creating Web Applications with WebStack</title>
2.8 + <meta name="generator"
2.9 + content="amaya 8.1a, see http://www.w3.org/Amaya/">
2.10 + <link xmlns:xlink="http://www.w3.org/1999/xlink" href="styles.css"
2.11 + rel="stylesheet" type="text/css">
2.12 +</head>
2.13 +<body>
2.14 +<h1>Creating Web Applications with WebStack</h1>
2.15 +<p>This set of documents describes the process of making a Web
2.16 +application
2.17 +using the WebStack framework.</p>
2.18 +<h2>Setting Up</h2>
2.19 +<p>First of all, let us assume that the WebStack distribution has been
2.20 +unpacked and now sits in the <code>WebStack-0.9</code> directory.</p>
2.21 +<p>Before we begin, we must make sure that the WebStack package is
2.22 +available
2.23 +to Python. The easiest way to do this is to change into the
2.24 +<code>WebStack-0.9</code> directory and to run the <code>setup.py</code>
2.25 +script provided with the version of Python you are going to be using
2.26 +(possibly as a privileged user like <code>root</code>):</p>
2.27 +<pre>cd WebStack-0.9<br>python setup.py install</pre>
2.28 +<p>If you don't want to install WebStack in this way, or if you can't
2.29 +do so
2.30 +because you don't have <code>root</code> privileges, you can just make
2.31 +sure
2.32 +that the <code>WebStack-0.9</code> directory sits on the
2.33 +<code>PYTHONPATH</code>.</p>
2.34 +<h2>About WebStack Applications</h2>
2.35 +<ul>
2.36 + <li><a href="anatomy.html">Anatomy of a WebStack Application</a></li>
2.37 + <li><a href="deploying.html">Deploying a WebStack Application</a><br>
2.38 + </li>
2.39 +</ul>
2.40 +</body>
2.41 +</html>
3.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
3.2 +++ b/docs/paths-filesystem.html Fri Apr 08 22:33:56 2005 +0000
3.3 @@ -0,0 +1,69 @@
3.4 +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
3.5 +<html>
3.6 +<head>
3.7 + <meta http-equiv="Content-Type" content="text/html">
3.8 + <title>Treating the Path Like a Filesystem</title>
3.9 + <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/">
3.10 + <link href="styles.css" rel="stylesheet" type="text/css">
3.11 +</head>
3.12 +
3.13 +<body>
3.14 +<h1>Treating the Path Like a Filesystem</h1>
3.15 +
3.16 +<p>...or as a reference into deeply categorized resources. In this approach,
3.17 +we take a path like this...</p>
3.18 +<pre>/documents/news/2005/article.html</pre>
3.19 +
3.20 +<p>...and we consider <code>documents</code>, <code>news</code>, and
3.21 +<code>2005</code> as directories, and <code>article.html</code> as a
3.22 +file-like resource. If we ask for the following path...</p>
3.23 +<pre>/documents/news/2005</pre>
3.24 +
3.25 +<p>...we may decide to provide a listing of files within that directory, or
3.26 +we may decide to refuse such a request. Indeed some approaches will insist
3.27 +that such a listing may only be produced with the following path instead:</p>
3.28 +<pre>/documents/news/2005/</pre>
3.29 +
3.30 +<p>Applications of this kind are quite common since the publishing of files
3.31 +on a Web server often just involves exposing parts of a real filesystem to
3.32 +requests through the server.</p>
3.33 +
3.34 +<h2>Resource Hierarchies in WebStack</h2>
3.35 +
3.36 +<p>We might decide to represent components in these kinds of paths using
3.37 +different resource classes, so that folders or directories are represented by
3.38 +one kind of resource class and files or documents are represented by other
3.39 +kinds of resource classes. We might then predefine a hierarchy of resources
3.40 +so that when a request arrives for a resource, we can check it against the
3.41 +hierarchy and process the request according to whichever type of resource is
3.42 +being accessed.</p>
3.43 +
3.44 +<p>Consider the above hierarchy; we would implement such a hierarchy with a
3.45 +resource object mapped to <code>documents</code>, and that resource object
3.46 +would contain a mapping of years to other resources. Eventually, at the
3.47 +bottom of the hierarchy, individual resources would represent articles and be
3.48 +mapped to names such as <code>article.html</code>.</p>
3.49 +
3.50 +<div class="WebStack">
3.51 +<h3>WebStack API - Predefining Resource Hierarchies in Adapter Code</h3>
3.52 +
3.53 +<p>WebStack provides a resource class for convenient mapping of path
3.54 +components (ie. names) to resource objects:
3.55 +<code>WebStack.Resources.ResourceMap.MapResource</code></p>
3.56 +
3.57 +<p>This class can be used in adapter or "glue" code to initialise an
3.58 +application as follows:</p>
3.59 +<pre>from WebStack.Resources.ResourceMap import MapResource
3.60 +article_resource = [some resource representing the article]
3.61 +year_2004_resource = [a MapResource with definitions]
3.62 +year_2005_resource = MapResource({"article.html" : article_resource})
3.63 +news_resource = MapResource({"2005" : year_2005_resource, "2004" : year_2004_resource})
3.64 +documents_resource = MapResource({"news" : news_resource})
3.65 +top_resource = MapResource({"documents" : documents_resource})</pre>
3.66 +</div>
3.67 +
3.68 +<p>Of course, predefining hierarchies is not the only way to support such
3.69 +hierarchies. We could inspect paths and act dynamically on the supplied
3.70 +information.</p>
3.71 +</body>
3.72 +</html>
4.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
4.2 +++ b/docs/paths-opaque.html Fri Apr 08 22:33:56 2005 +0000
4.3 @@ -0,0 +1,28 @@
4.4 +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4.5 +<html xmlns="http://www.w3.org/1999/xhtml">
4.6 +<head>
4.7 + <title>Using the Path as an Opaque Reference into an Application</title>
4.8 + <meta name="generator"
4.9 + content="amaya 8.1a, see http://www.w3.org/Amaya/">
4.10 + <link xmlns:xlink="http://www.w3.org/1999/xlink" href="styles.css"
4.11 + rel="stylesheet" type="text/css">
4.12 +</head>
4.13 +<body>
4.14 +<h1>Using the Path as an Opaque Reference into an Application</h1>
4.15 +<p>Since many Web applications have complete control over how paths are
4.16 +interpreted, the form of the path doesn't necessarily have to follow
4.17 +any
4.18 +obvious structure as far as users of your application is concerned.
4.19 +Here's an
4.20 +example:</p>
4.21 +<pre>/000251923572ax-0015</pre>
4.22 +<p>However, many would argue that such obscure references, whilst
4.23 +perfectly
4.24 +acceptable to machines, would make any application counter-intuitive
4.25 +and very
4.26 +difficult to reference. Sometimes, application developers do not want
4.27 +people
4.28 +"bookmarking" resources or functions within an application, and so such
4.29 +concerns don't matter to them.</p>
4.30 +</body>
4.31 +</html>
5.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
5.2 +++ b/docs/paths-services.html Fri Apr 08 22:33:56 2005 +0000
5.3 @@ -0,0 +1,25 @@
5.4 +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
5.5 +<html xmlns="http://www.w3.org/1999/xhtml">
5.6 +<head>
5.7 + <title>Treating the Path Mostly Like a Filesystem</title>
5.8 + <meta name="generator"
5.9 + content="amaya 8.1a, see http://www.w3.org/Amaya/">
5.10 + <link xmlns:xlink="http://www.w3.org/1999/xlink" href="styles.css"
5.11 + rel="stylesheet" type="text/css">
5.12 +</head>
5.13 +<body>
5.14 +<h1>Treating the Path Mostly Like a Filesystem</h1>
5.15 +<p>...but really using it to broadly identify different resources or
5.16 +services. In this approach, we take a path like this...</p>
5.17 +<pre>/tools/viewer</pre>
5.18 +<p>...and interpret it as being a request for a certain function of the
5.19 +application. Often, this approach is used because it matches some
5.20 +aspect of
5.21 +how the application is actually organised. Consider this example:</p>
5.22 +<pre>/cgi-bin/script.pl</pre>
5.23 +<p>This kind of thing generally appears in URLs because of the way the
5.24 +application concerned has been deployed - CGI programs live in a
5.25 +particular
5.26 +place and are accessed using a special path "prefix".</p>
5.27 +</body>
5.28 +</html>
6.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
6.2 +++ b/docs/paths.html Fri Apr 08 22:33:56 2005 +0000
6.3 @@ -0,0 +1,120 @@
6.4 +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
6.5 +<html>
6.6 +<head>
6.7 + <meta http-equiv="Content-Type" content="text/html">
6.8 + <title>URLs and Paths</title>
6.9 + <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/">
6.10 + <link href="styles.css" rel="stylesheet" type="text/css">
6.11 +</head>
6.12 +
6.13 +<body>
6.14 +<h1>URLs and Paths</h1>
6.15 +
6.16 +<p>The URL at which your application shall appear is arguably the first part
6.17 +of the application's user interface that any user will see. In this context,
6.18 +a user can be any of the following things:</p>
6.19 +<ul>
6.20 + <li>A real person entering the URL into a browser's address bar.</li>
6.21 + <li>A real person linking to your application by writing the URL in a
6.22 + separate Web page.</li>
6.23 + <li>A program which has the URL defined within it and which may manipulate
6.24 + the URL to perform certain kinds of operations.</li>
6.25 +</ul>
6.26 +
6.27 +<h2>Interpreting Path Information</h2>
6.28 +
6.29 +<p>What the URL is supposed to do is to say where (on the Internet or on an
6.30 +intranet) your application resides and which resource or service is being
6.31 +accessed, and these look like this:</p>
6.32 +<pre>http://www.boddie.org.uk/python/WebStack.html</pre>
6.33 +
6.34 +<p>With WebStack, we also talk about a "path" as being just the part of the
6.35 +URL which refers to the resource or service, ignoring the actual Internet
6.36 +address, and so these look like this:</p>
6.37 +<pre>/python/WebStack.html</pre>
6.38 +
6.39 +<p>When writing a Web application, most of the time you just need to
6.40 +concentrate on the path because the address doesn't usually tell you anything
6.41 +you don't already know. What you need to do is to interpret the path
6.42 +specified in the request in order to work out which resource or service the
6.43 +request is destined for.<br>
6.44 +</p>
6.45 +
6.46 +<div class="WebStack">
6.47 +<h3>WebStack API - Path Methods in Transaction Objects</h3>
6.48 +
6.49 +<p>WebStack provides the following transaction methods for inspecting path
6.50 +information:</p>
6.51 +<dl>
6.52 + <dt><code>get_path</code></dt>
6.53 + <dd>This gets the entire path of a resource including parameter
6.54 + information - see <a href="parameters.html">"Request Parameters and
6.55 + Uploads"</a>.</dd>
6.56 + <dt><code>get_path_without_query</code></dt>
6.57 + <dd>This gets the entire path of a resource but without any parameter
6.58 + information.</dd>
6.59 +</dl>
6.60 +</div>
6.61 +
6.62 +<h2>Paths To and Within an Application</h2>
6.63 +One thing to be aware of in the code of an application is which part of a
6.64 +path refers to the location of the application in a server environment and
6.65 +which refers to some resource within the application itself. Consider this
6.66 +path:<br>
6.67 +
6.68 +<pre>/folder/application/resource</pre>
6.69 +Let us say that the application was deployed in a Zope server instance inside
6.70 +<code>folder</code> and with the name <code>application</code>. We may then
6.71 +say that the path to the application is this:
6.72 +<pre>/folder/application</pre>
6.73 +Meanwhile, the path within the application is just this:
6.74 +<pre>/resource</pre>
6.75 +
6.76 +<div class="WebStack">
6.77 +<h3>WebStack API - Paths To Resources Within Applications</h3>
6.78 +
6.79 +<p>On transaction objects, the following methods exist to inspect paths to
6.80 +resources within applications.</p>
6.81 +<dl>
6.82 + <dt><code>get_path_info</code></dt>
6.83 + <dd>This gets the path of a resource within an application.</dd>
6.84 + <dt><code>get_virtual_path_info</code></dt>
6.85 + <dd>This gets the path of a resource within a part of an application -
6.86 + the application itself decides the scope of the path and can set the
6.87 + "virtual path info" using the <code>set_virtual_path_info</code>
6.88 + method.</dd>
6.89 +</dl>
6.90 +</div>
6.91 +
6.92 +<h2>Approaches to Path Interpretation<br>
6.93 +</h2>
6.94 +
6.95 +<p>There are various differing approaches to the problem of interpreting
6.96 +paths to resources within Web applications, but these can mostly be divided
6.97 +into three categories:</p>
6.98 +
6.99 +<table border="1" cellspacing="0" cellpadding="5">
6.100 + <tbody>
6.101 + <tr>
6.102 + <th>Approach</th>
6.103 + <th>Examples</th>
6.104 + </tr>
6.105 + <tr>
6.106 + <td><a href="paths-filesystem.html">Path as filesystem</a></td>
6.107 + <td>WebDAV interface to a repository</td>
6.108 + </tr>
6.109 + <tr>
6.110 + <td><a href="paths-services.html">Path as resource or service
6.111 + identifier</a></td>
6.112 + <td>A Web shop with very simple paths, eg. <code>/products</code>,
6.113 + <code>/checkout</code>, <code>/orders</code></td>
6.114 + </tr>
6.115 + <tr>
6.116 + <td><a href="paths-opaque.html">Path as opaque reference</a></td>
6.117 + <td>An e-mail reader where the messages already have strange and
6.118 + unreadable message identifiers</td>
6.119 + </tr>
6.120 + </tbody>
6.121 +</table>
6.122 +</body>
6.123 +</html>