1.1 --- a/docs/resources.html Tue Apr 19 22:32:46 2005 +0000
1.2 +++ b/docs/resources.html Sun Apr 24 15:43:10 2005 +0000
1.3 @@ -10,62 +10,72 @@
1.4 <body>
1.5 <h1>Applications and Resources</h1>
1.6 At its simplest a WebStack application is just a single Python
1.7 -class that we call a "resource". We can either create a module file <code>MyApplication.py</code>
1.8 -(for example) or a
1.9 -package directory <code>MyApplication</code> (for example) containing
1.10 -a module file <code>__init__.py</code>, and we write into that file a
1.11 -definition
1.12 -of the resource as follows:
1.13 -<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>
1.14 -<p>It is in this kind of resource class that we write the
1.15 +class that we call a "resource". This class can be defined inside a
1.16 +normal Python module or package, so let us start by doing the following:<br />
1.17 +<ol>
1.18 + <li>Create a new directory for
1.19 +our application; choose any name since we just want an empty space in
1.20 +which to put new files.</li>
1.21 + <li>Create a file called <code>MyApplication.py</code>
1.22 +- this is our module.</li>
1.23 +</ol>
1.24 +We are going to call our resource <code>MyResource</code>
1.25 +and in principle it will have a structure that looks like this:
1.26 +<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>
1.27 +<p>It is in this kind of resource
1.28 +class that we write the
1.29 actual application code or at least the beginnings of it. When a user
1.30 of the application sends us a request,
1.31 -the <code>respond</code> method will be called and the code
1.32 +the <code>respond</code> method
1.33 +will be called and the code
1.34 within it executed. The parts of the pseudo-code in
1.35 the above text which aren't valid Python
1.36 -(ie. the bits in square brackets) will use the <code>trans</code>
1.37 +(ie. the bits in square brackets) will, when we have written them, use
1.38 +the <code>trans</code>
1.39 object to find out what any given user of the application has sent us,
1.40 and to send information back
1.41 to the
1.42 user in response.</p>
1.43 <h2>Starting Simple</h2>
1.44 -<p>The simplest way to turn this into a working application is to
1.45 +<p>The simplest way to turn this
1.46 +into a working application is to
1.47 ignore the first two activities mentioned in the pseudo-code and just
1.48 to produce some kind of
1.49 -response. Here is how we might do that (in our module file <code>MyApplication.py</code>
1.50 -or <code>MyApplication/__init__.py</code>):</p>
1.51 +response. Here is how we can make our application do something:</p>
1.52 +<ol>
1.53 + <li>Edit the module
1.54 +file <code>MyApplication.py</code>.</li>
1.55 + <li>Write into it the following
1.56 +code which defines <code>MyResource</code>:</li>
1.57 +</ol>
1.58 <pre>class MyResource:<br /> def respond(self, trans):<br /> out = trans.get_response_stream()<br /> print >>out, "Hello world."</pre>
1.59 -<p>To deploy this, we need an adapter - see <a href="deploying.html">"Deploying
1.60 -a WebStack Application"</a> for something which will work with this
1.61 -example.
1.62 -</p>
1.63 -<h2>How Resources are Created
1.64 -</h2>
1.65 -<p>In the above example, the only thing we need to
1.66 -consider is
1.67 -what our code does, not how resource objects are created and invoked
1.68 -(that is
1.69 -done in the <a href="deploying.html">adapter code</a>). In more
1.70 -complicated applications, there may
1.71 -be a
1.72 -need to create our own resource objects explicitly, but this is not
1.73 -particularly interesting to think about at this point - see <a
1.74 - href="paths-filesystem.html">"Treating the Path Like
1.75 -a Filesystem"</a> for a
1.76 -discussion of multiple resource objects.</p>
1.77 -<h2>Design Considerations</h2>
1.78 -<p>When writing an application, we
1.79 -must consider a number of factors which
1.80 -have an impact on the code (and other things) that we will need to
1.81 -provide as
1.82 -part of the finished product or service.</p>
1.83 +<h2>Testing the Resource</h2>
1.84 +<p>To test this resource we need to deploy it, and to do that we need
1.85 +an
1.86 +adapter. Here is a quick way of writing an adapter and testing this
1.87 +code:</p>
1.88 +<ol>
1.89 + <li> Create a file called <code>MyAdapter.py</code> - you
1.90 +can choose another name if you want - this will be where the adapter
1.91 +code lives.</li>
1.92 + <li>Copy the example adapter in <a href="deploying.html">"Deploying
1.93 +a WebStack Application"</a> and write it into <code>MyAdapter.py</code>.</li>
1.94 + <li>Now, with two files in your directory, <code>MyApplication.py</code>
1.95 +and <code>MyAdapter.py</code>, you may run <code>MyAdapter.py</code>
1.96 +as follows:</li>
1.97 +</ol>
1.98 +<pre>python MyAdapter.py</pre>
1.99 +<p>This should start the adapter program and print the following
1.100 +message:</p>
1.101 +<pre>Serving...</pre>
1.102 +<p>You should now be able to visit <code>http://localhost:8080</code>
1.103 +in your
1.104 +browser and see the message printed by your application:</p>
1.105 +<pre>Hello world.</pre>
1.106 +<h2>About Resources</h2>
1.107 <ul>
1.108 - <li><a href="paths.html">URLs and Paths</a></li>
1.109 - <li><a href="methods.html">Request Methods</a></li>
1.110 - <li><a href="parameters.html">Request Parameters and Uploads</a></li>
1.111 - <li><a href="responses.html">Responses and Presentation</a></li>
1.112 - <li><a href="state.html">Cookies, Sessions and Persistent
1.113 -Information</a></li>
1.114 + <li><a href="resource-creation.html">How Resources are Created</a></li>
1.115 + <li><a href="design.html">Application Design Considerations</a></li>
1.116 </ul>
1.117 </body>
1.118 </html>