# HG changeset patch # User paulb # Date 1113949966 0 # Node ID 6947214e9dd404c321ef77e13607e947d8647662 # Parent 7b8005a9072a9df6d92e6851fa35b358318e8b24 [project @ 2005-04-19 22:32:46 by paulb] Improved the anatomy layout. Renamed simple-example.html to resources.html and made it more concrete, together with the deployment documentation. diff -r 7b8005a9072a -r 6947214e9dd4 docs/anatomy.html --- a/docs/anatomy.html Mon Apr 18 22:47:28 2005 +0000 +++ b/docs/anatomy.html Tue Apr 19 22:32:46 2005 +0000 @@ -1,6 +1,7 @@
+Application - - -The application is described in this part of the documentation. | ++ | What +it does | +How much work | +Where +to look |
---|---|---|---|---|
Adapter - - -Adapters are explained in the deployment -documentation. | + 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 + +This +defines what the user sees. + | +Most new code will be +written in the application. | +The application is +described in + this part of the documentation. | |
Server -environment - -Server environments are covered in the deployment -documentation. | + 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 + +This +"glues" the application to the environment. | +Mostly copying an existing +adapter or writing a short module. | +Adapters are explained in +the deployment +documentation. + | +|
Server +environment | +This +is where the application runs. | +Some configuration needed, +if any at all. | +Server environments are +covered +in the deployment +documentation. + |
To get an application up and -running, this is what you have to do:
-In this part of the -documentation, we will ignore the second -activity (it is covered in "Deploying a -WebStack -Application") and concentrate on the more important task of -defining an application's functionality with "A Very Simple Example".
diff -r 7b8005a9072a -r 6947214e9dd4 docs/deploying.html --- a/docs/deploying.html Mon Apr 18 22:47:28 2005 +0000 +++ b/docs/deploying.html Tue Apr 19 22:32:46 2005 +0000 @@ -1,37 +1,39 @@ - - +The process of deploying a WebStack application should be as -straightforward as taking some adapter or "glue" code and either running it -or using the deployment processes of the server environment or framework in +straightforward as taking some adapter or "glue" code and either +running it +or using the deployment processes of the server environment or +framework in which the application will be living.
-What adapter or "glue" code does is to set up your applications main resource object and to hook that object up with the underlying server -environment. It typically looks something like this:
-from WebStack.Adapters.CGI import deploy # import the support for the server environment -from MyApplication import MyResource # import the main resource class -deploy(MyResource()) # connect a resource object to the server environment- +environment. For the
MyApplication
example it typically looks something like
+this:
+from WebStack.Adapters.BaseHTTPRequestHandler import deploy # import the support for the server environment+
from MyApplication import MyResource # import the main resource class
deploy(MyResource()) # connect a resource object to the server environment
In the case of BaseHTTPRequestHandler, which is a module in the
+Python standard library, you can just run this code, making sure that
+the MyApplication
module or package is on your PYTHONPATH
.
+Then, you can visit http://localhost:8080
in your
+browser and see the result.
Unfortunately, not all server environments can be connected up with applications this easily. Some environments require special classes and -functions to be defined in the adapter code in order for the applications to +functions to be defined in the adapter code in order for the +applications to be properly integrated into the environments. Here is a summary which indicates the server environments or frameworks which need most work:
- -Framework | @@ -56,8 +58,8 @@|||
---|---|---|---|
mod_python | Must implement handler function |
- Web server runs the adapter code (which must be declared within - Apache) | +Web server runs the adapter code (which must be declared +within Apache) |
Twisted | @@ -67,9 +69,8 @@|||
Webware | <= 0.8.1: Must implement InstallInWebKit
- function- > 0.8.1: Simple, but must provide a urlParser
- object |
+functionApplication must be deployed within WebKit | |
MyApplication.py
+(for example) or a
+package directory MyApplication
(for example) containing
+a module file __init__.py
, and we write into that file a
+definition
+of the resource as follows:
+class MyResource:+
def respond(self, trans):
[Examine the transaction, decide what the user wants to do.]
[Perform some kind of action with the information supplied.]
[Produce some kind of response which tells the user what happened.]
It is in this kind of resource class that we write the
+actual application code or at least the beginnings of it. When a user
+of the application sends us a request,
+the respond
method will be called and the code
+within it executed. The parts of the pseudo-code in
+the above text which aren't valid Python
+(ie. the bits in square brackets) will use the trans
+object to find out what any given user of the application has sent us,
+and to send information back
+to the
+user in response.
The simplest way to turn this into a working application is to
+ignore the first two activities mentioned in the pseudo-code and just
+to produce some kind of
+response. Here is how we might do that (in our module file MyApplication.py
+or MyApplication/__init__.py
):
class MyResource:+
def respond(self, trans):
out = trans.get_response_stream()
print >>out, "Hello world."
To deploy this, we need an adapter - see "Deploying +a WebStack Application" for something which will work with this +example. +
+In the above example, the only thing we need to +consider is +what our code does, not how resource objects are created and invoked +(that is +done in the adapter code). In more +complicated applications, there may +be a +need to create our own resource objects explicitly, but this is not +particularly interesting to think about at this point - see "Treating the Path Like +a Filesystem" for a +discussion of multiple resource objects.
+When writing an application, we +must consider a number of factors which +have an impact on the code (and other things) that we will need to +provide as +part of the finished product or service.
+class MyResource:-
"This is a resource - something which defines the behaviour of an application."
def respond(self, trans):
[Examine the transaction, decide what the user wants to do.]
[Perform some kind of action with the information supplied.]
[Produce some kind of response which tells the user what happened.]
The parts of the pseudo-code in -the above text which aren't valid Python -(ie. the bits in square brackets) will use various WebStack API calls -to look -at what the user specified in the request and to send information back -to the -user in the response.
-It is in this kind of resource class that we write the -application code. In the above example, the only thing we need to -consider is -what our code does, not how resource objects are created and invoked -(that is -done in the adapter code). In more -complicated applications, there may -be a -need to create our own resource objects explicitly, but this is not -particularly interesting to think about at this point - see "Treating the Path Like -a Filesystem" for a -discussion of multiple resource objects. -
-When writing an application, we -must consider a number of factors which -have an impact on the code (and other things) that we will need to -provide as -part of the finished product or service.
- - - diff -r 7b8005a9072a -r 6947214e9dd4 docs/styles.css --- a/docs/styles.css Mon Apr 18 22:47:28 2005 +0000 +++ b/docs/styles.css Tue Apr 19 22:32:46 2005 +0000 @@ -42,17 +42,15 @@ th, td, caption { font-size: 12pt; } - .explanation { border-style: solid; - border-width: 2px; + .explanation { border-style: dotted; + border-width: 1px; padding: 0.25em; - top: -0.5em; - width: 40%; display: block; - float: right; position: relative; - left: 10%; background-color: rgb(255, 255, 153); font-weight: normal; + top: 0.5em; + left: -1em; } .layers { width: 60%;