1.1 --- a/docs/anatomy.html Mon Apr 18 22:47:28 2005 +0000
1.2 +++ b/docs/anatomy.html Tue Apr 19 22:32:46 2005 +0000
1.3 @@ -1,6 +1,7 @@
1.4 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.5 <html xmlns="http://www.w3.org/1999/xhtml">
1.6 <head>
1.7 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
1.8 <title>Anatomy of a WebStack Application</title>
1.9 <meta name="generator"
1.10 content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.11 @@ -16,46 +17,59 @@
1.12 which it must respond by writing out messages to send back -
1.13 specifically HTTP responses. When using WebStack, we think of the
1.14 situation in terms of the following components:</p>
1.15 -<table style="text-align: left; margin-left: auto; margin-right: auto;"
1.16 - class="layers" border="1" cellpadding="5" cellspacing="0">
1.17 +<table
1.18 + style="text-align: left; margin-left: auto; margin-right: auto; width: 80%;"
1.19 + class="layers" border="0" cellpadding="5" cellspacing="0">
1.20 <tbody>
1.21 <tr>
1.22 - <th
1.23 - style="text-align: center; background-color: rgb(255, 102, 102); vertical-align: middle;">Application
1.24 - <span class="explanation">-
1.25 -The application is described in this part of the documentation.</span> </th>
1.26 + <td width="40%"></td>
1.27 + <th style="text-align: center;">What
1.28 +it does</th>
1.29 + <th style="text-align: center;">How much work</th>
1.30 + <th style="text-align: center;">Where
1.31 +to look</th>
1.32 </tr>
1.33 <tr>
1.34 <th
1.35 - style="background-color: rgb(255, 255, 102); text-align: center; vertical-align: middle;">Adapter
1.36 - <span class="explanation">-
1.37 -Adapters are explained in the <a href="deploying.html">deployment
1.38 -documentation</a>.</span> </th>
1.39 + style="text-align: center; vertical-align: middle; background-color: rgb(193, 255, 102); border-top-style: solid; border-left-style: solid; border-right-style: solid; border-top-width: 1px; border-left-width: 1px; border-right-width: 1px;">Application
1.40 + </th>
1.41 + <td style="text-align: center;"><span class="explanation">This
1.42 +defines what the user sees.
1.43 + </span></td>
1.44 + <td align="center" valign="undefined">Most new code will be
1.45 +written in the application.</td>
1.46 + <td align="center" valign="undefined">The application is
1.47 +described in
1.48 + <a href="resources.html">this part of the documentation</a>.</td>
1.49 </tr>
1.50 <tr>
1.51 <th
1.52 - style="background-color: rgb(153, 153, 255); text-align: center; vertical-align: middle;">Server
1.53 -environment <span class="explanation">-
1.54 -Server environments are covered in the <a href="deploying.html">deployment
1.55 -documentation</a>.</span> </th>
1.56 + style="border-width: 1px; text-align: center; vertical-align: middle; background-color: rgb(102, 203, 255); border-left-style: solid; border-right-style: solid; border-top-style: solid;">Adapter
1.57 + </th>
1.58 + <td style="text-align: center;"><span class="explanation">This
1.59 +"glues" the application to the environment.</span></td>
1.60 + <td align="center" valign="undefined">Mostly copying an existing
1.61 +adapter or writing a short module.</td>
1.62 + <td align="center" valign="undefined">Adapters are explained in
1.63 +the <a href="deploying.html">deployment
1.64 +documentation</a>.
1.65 + </td>
1.66 + </tr>
1.67 + <tr>
1.68 + <th
1.69 + style="border-style: solid; border-width: 1px; text-align: center; vertical-align: middle; background-color: rgb(192, 192, 192);">Server
1.70 +environment </th>
1.71 + <td align="center" valign="undefined"><span class="explanation">This
1.72 +is where the application runs.</span></td>
1.73 + <td align="center" valign="undefined">Some configuration needed,
1.74 +if any at all.</td>
1.75 + <td align="center" valign="undefined">Server environments are
1.76 +covered
1.77 +in the <a href="deploying.html">deployment
1.78 +documentation</a>.
1.79 + </td>
1.80 </tr>
1.81 </tbody>
1.82 </table>
1.83 -<p>To get an application up and
1.84 -running, this is what you have to do:</p>
1.85 -<ol>
1.86 - <li>Write some application code
1.87 -which uses the WebStack API.</li>
1.88 - <li>Write some simple adapter
1.89 -code - this code "glues" the application to the environment that you
1.90 -want to use.</li>
1.91 -</ol>
1.92 -<p>In this part of the
1.93 -documentation, we will ignore the second
1.94 -activity (it is covered in <a href="deploying.html">"Deploying a
1.95 -WebStack
1.96 -Application"</a>) and concentrate on the more important task of
1.97 -defining an application's functionality with <a
1.98 - href="simple-example.html">"A Very Simple Example"</a>.</p>
1.99 </body>
1.100 </html>
2.1 --- a/docs/deploying.html Mon Apr 18 22:47:28 2005 +0000
2.2 +++ b/docs/deploying.html Tue Apr 19 22:32:46 2005 +0000
2.3 @@ -1,37 +1,39 @@
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>Deploying a WebStack Application</title>
2.11 - <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
2.12 + <meta name="generator"
2.13 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
2.14 <link href="styles.css" rel="stylesheet" type="text/css" />
2.15 </head>
2.16 -
2.17 <body>
2.18 <h1>Deploying a WebStack Application</h1>
2.19 -
2.20 <p>The process of deploying a WebStack application should be as
2.21 -straightforward as taking some adapter or "glue" code and either running it
2.22 -or using the deployment processes of the server environment or framework in
2.23 +straightforward as taking some adapter or "glue" code and either
2.24 +running it
2.25 +or using the deployment processes of the server environment or
2.26 +framework in
2.27 which the application will be living.</p>
2.28 -
2.29 <h2>The Adapter Code</h2>
2.30 -
2.31 <p>What adapter or "glue" code does is to set up your applications main
2.32 resource object and to hook that object up with the underlying server
2.33 -environment. It typically looks something like this:</p>
2.34 -<pre>from WebStack.Adapters.CGI import deploy # import the support for the server environment
2.35 -from MyApplication import MyResource # import the main resource class
2.36 -deploy(MyResource()) # connect a resource object to the server environment</pre>
2.37 -
2.38 +environment. For the <code>MyApplication</code> <a
2.39 + href="resources.html">example</a> it typically looks something like
2.40 +this:</p>
2.41 +<pre>from WebStack.Adapters.BaseHTTPRequestHandler import deploy # import the support for the server environment<br />from MyApplication import MyResource # import the main resource class<br />deploy(MyResource()) # connect a resource object to the server environment</pre>
2.42 +<p>In the case of BaseHTTPRequestHandler, which is a module in the
2.43 +Python standard library, you can just run this code, making sure that
2.44 +the <code>MyApplication</code> module or package is on your <code>PYTHONPATH</code>.
2.45 +Then, you can visit <code>http://localhost:8080</code> in your
2.46 +browser and see the result.</p>
2.47 +<h2>More Demanding Adapter Code</h2>
2.48 <p>Unfortunately, not all server environments can be connected up with
2.49 applications this easily. Some environments require special classes and
2.50 -functions to be defined in the adapter code in order for the applications to
2.51 +functions to be defined in the adapter code in order for the
2.52 +applications to
2.53 be properly integrated into the environments. Here is a summary which
2.54 indicates the server environments or frameworks which need most work:</p>
2.55 -
2.56 -<table border="1" cellspacing="0" cellpadding="5">
2.57 +<table border="1" cellpadding="5" cellspacing="0">
2.58 <tbody>
2.59 <tr>
2.60 <th>Framework</th>
2.61 @@ -56,8 +58,8 @@
2.62 <tr>
2.63 <td>mod_python</td>
2.64 <td>Must implement <code>handler</code> function</td>
2.65 - <td>Web server runs the adapter code (which must be declared within
2.66 - Apache)</td>
2.67 + <td>Web server runs the adapter code (which must be declared
2.68 +within Apache)</td>
2.69 </tr>
2.70 <tr>
2.71 <td>Twisted</td>
2.72 @@ -67,9 +69,8 @@
2.73 <tr>
2.74 <td>Webware</td>
2.75 <td><= 0.8.1: Must implement <code>InstallInWebKit</code>
2.76 - function<br />
2.77 - > 0.8.1: Simple, but must provide a <code>urlParser</code>
2.78 - object</td>
2.79 +function<br />
2.80 +> 0.8.1: Simple, but must provide a <code>urlParser</code> object</td>
2.81 <td>Application must be deployed within WebKit</td>
2.82 </tr>
2.83 <tr>
2.84 @@ -84,7 +85,6 @@
2.85 </tr>
2.86 </tbody>
2.87 </table>
2.88 -
2.89 <h2>The Deployment Process</h2>
2.90 <ul>
2.91 <li><a href="writing-adapters.html">Writing Adapters</a></li>
3.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
3.2 +++ b/docs/resources.html Tue Apr 19 22:32:46 2005 +0000
3.3 @@ -0,0 +1,71 @@
3.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3.5 +<html xmlns="http://www.w3.org/1999/xhtml">
3.6 +<head>
3.7 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
3.8 + <title>Applications and Resources</title>
3.9 + <meta name="generator"
3.10 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
3.11 + <link href="styles.css" rel="stylesheet" type="text/css" />
3.12 +</head>
3.13 +<body>
3.14 +<h1>Applications and Resources</h1>
3.15 +At its simplest a WebStack application is just a single Python
3.16 +class that we call a "resource". We can either create a module file <code>MyApplication.py</code>
3.17 +(for example) or a
3.18 +package directory <code>MyApplication</code> (for example) containing
3.19 +a module file <code>__init__.py</code>, and we write into that file a
3.20 +definition
3.21 +of the resource as follows:
3.22 +<pre>class MyResource:<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>
3.23 +<p>It is in this kind of resource class that we write the
3.24 +actual application code or at least the beginnings of it. When a user
3.25 +of the application sends us a request,
3.26 +the <code>respond</code> method will be called and the code
3.27 +within it executed. The parts of the pseudo-code in
3.28 +the above text which aren't valid Python
3.29 +(ie. the bits in square brackets) will use the <code>trans</code>
3.30 +object to find out what any given user of the application has sent us,
3.31 +and to send information back
3.32 +to the
3.33 +user in response.</p>
3.34 +<h2>Starting Simple</h2>
3.35 +<p>The simplest way to turn this into a working application is to
3.36 +ignore the first two activities mentioned in the pseudo-code and just
3.37 +to produce some kind of
3.38 +response. Here is how we might do that (in our module file <code>MyApplication.py</code>
3.39 +or <code>MyApplication/__init__.py</code>):</p>
3.40 +<pre>class MyResource:<br /> def respond(self, trans):<br /> out = trans.get_response_stream()<br /> print >>out, "Hello world."</pre>
3.41 +<p>To deploy this, we need an adapter - see <a href="deploying.html">"Deploying
3.42 +a WebStack Application"</a> for something which will work with this
3.43 +example.
3.44 +</p>
3.45 +<h2>How Resources are Created
3.46 +</h2>
3.47 +<p>In the above example, the only thing we need to
3.48 +consider is
3.49 +what our code does, not how resource objects are created and invoked
3.50 +(that is
3.51 +done in the <a href="deploying.html">adapter code</a>). In more
3.52 +complicated applications, there may
3.53 +be a
3.54 +need to create our own resource objects explicitly, but this is not
3.55 +particularly interesting to think about at this point - see <a
3.56 + href="paths-filesystem.html">"Treating the Path Like
3.57 +a Filesystem"</a> for a
3.58 +discussion of multiple resource objects.</p>
3.59 +<h2>Design Considerations</h2>
3.60 +<p>When writing an application, we
3.61 +must consider a number of factors which
3.62 +have an impact on the code (and other things) that we will need to
3.63 +provide as
3.64 +part of the finished product or service.</p>
3.65 +<ul>
3.66 + <li><a href="paths.html">URLs and Paths</a></li>
3.67 + <li><a href="methods.html">Request Methods</a></li>
3.68 + <li><a href="parameters.html">Request Parameters and Uploads</a></li>
3.69 + <li><a href="responses.html">Responses and Presentation</a></li>
3.70 + <li><a href="state.html">Cookies, Sessions and Persistent
3.71 +Information</a></li>
3.72 +</ul>
3.73 +</body>
3.74 +</html>
4.1 --- a/docs/simple-example.html Mon Apr 18 22:47:28 2005 +0000
4.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
4.3 @@ -1,53 +0,0 @@
4.4 -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4.5 -<html xmlns="http://www.w3.org/1999/xhtml">
4.6 -<head>
4.7 - <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
4.8 - <title>A Very Simple Example</title>
4.9 - <meta name="generator"
4.10 - content="amaya 8.1a, see http://www.w3.org/Amaya/" />
4.11 - <link href="styles.css" rel="stylesheet" type="text/css" />
4.12 -</head>
4.13 -<body>
4.14 -<h1>A Very Simple Example</h1>
4.15 -At its simplest a WebStack application is just a Python class,
4.16 -living in a module or package, having this form:
4.17 -<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>
4.18 -<p>The parts of the pseudo-code in
4.19 -the above text which aren't valid Python
4.20 -(ie. the bits in square brackets) will use various WebStack API calls
4.21 -to look
4.22 -at what the user specified in the request and to send information back
4.23 -to the
4.24 -user in the response.</p>
4.25 -<h2>Resource Classes
4.26 -</h2>
4.27 -<p>It is in this kind of resource class that we write the
4.28 -application code. In the above example, the only thing we need to
4.29 -consider is
4.30 -what our code does, not how resource objects are created and invoked
4.31 -(that is
4.32 -done in the <a href="deploying.html">adapter code</a>). In more
4.33 -complicated applications, there may
4.34 -be a
4.35 -need to create our own resource objects explicitly, but this is not
4.36 -particularly interesting to think about at this point - see <a
4.37 - href="paths-filesystem.html">"Treating the Path Like
4.38 -a Filesystem"</a> for a
4.39 -discussion of multiple resource objects.
4.40 -</p>
4.41 -<h2>Design Considerations</h2>
4.42 -<p>When writing an application, we
4.43 -must consider a number of factors which
4.44 -have an impact on the code (and other things) that we will need to
4.45 -provide as
4.46 -part of the finished product or service.</p>
4.47 -<ul>
4.48 - <li><a href="paths.html">URLs and Paths</a></li>
4.49 - <li><a href="methods.html">Request Methods</a></li>
4.50 - <li><a href="parameters.html">Request Parameters and Uploads</a></li>
4.51 - <li><a href="responses.html">Responses and Presentation</a></li>
4.52 - <li><a href="state.html">Cookies, Sessions and Persistent
4.53 -Information</a></li>
4.54 -</ul>
4.55 -</body>
4.56 -</html>
5.1 --- a/docs/styles.css Mon Apr 18 22:47:28 2005 +0000
5.2 +++ b/docs/styles.css Tue Apr 19 22:32:46 2005 +0000
5.3 @@ -42,17 +42,15 @@
5.4 th, td, caption { font-size: 12pt;
5.5 }
5.6
5.7 - .explanation { border-style: solid;
5.8 - border-width: 2px;
5.9 + .explanation { border-style: dotted;
5.10 + border-width: 1px;
5.11 padding: 0.25em;
5.12 - top: -0.5em;
5.13 - width: 40%;
5.14 display: block;
5.15 - float: right;
5.16 position: relative;
5.17 - left: 10%;
5.18 background-color: rgb(255, 255, 153);
5.19 font-weight: normal;
5.20 + top: 0.5em;
5.21 + left: -1em;
5.22 }
5.23
5.24 .layers { width: 60%;