1.1 --- a/docs/design.html Mon Apr 25 22:03:10 2005 +0000
1.2 +++ b/docs/design.html Mon Apr 25 22:04:02 2005 +0000
1.3 @@ -10,14 +10,55 @@
1.4 <body>
1.5 <h1>Application Design Considerations</h1>
1.6 <p>When writing an application, we
1.7 -must consider a number of factors which
1.8 -have an impact on the code (and other things) that we will need to
1.9 -provide as
1.10 -part of the finished product or service.</p>
1.11 +must try and cover the three activities mentioned in our overview of
1.12 +what a simple application looks like:</p>
1.13 +<ol>
1.14 + <li>Examine the transaction, decide what the user wants to do.</li>
1.15 + <li>Perform some kind of action with the information supplied.</li>
1.16 + <li>Produce some kind of response which tells the user what happened.</li>
1.17 +</ol>
1.18 +<p>We briefly covered the third activity in the <code>MyApplication</code>
1.19 +example, but for a real, properly-behaved application, we need to visit
1.20 +each activity in detail.</p>
1.21 +<h2>Examine the Transaction</h2>
1.22 +<p>In WebStack, the transaction is an object which is passed into a
1.23 +resource when a user makes contact with an application. This
1.24 +transaction object effectively tells us what it is the user wants to
1.25 +do; it does so through a number of different pieces of information
1.26 +including the request method, headers, parameters, cookies and sessions.</p>
1.27 +<div class="WebStack">
1.28 +<h3>WebStack API - The Transaction Object</h3>
1.29 +<p>The transaction object appears as the first parameter in a
1.30 +resource's <code>respond</code> method:</p>
1.31 +<pre>class SomeResource:<br /> def respond(self, trans):<br /> [Here is where the code for the resource is written.]</pre>
1.32 +<p>For full information about transaction objects, see the API
1.33 +documentation for the <a
1.34 + href="../apidocs/public/WebStack.Generic.Transaction-class.html"><code>WebStack.Generic.Transaction</code></a>
1.35 +class.</p>
1.36 +</div>
1.37 +<p>Within this activity, certain topics are of interest:</p>
1.38 <ul>
1.39 <li><a href="paths.html">URLs and Paths</a></li>
1.40 <li><a href="methods.html">Request Methods</a></li>
1.41 <li><a href="parameters.html">Request Parameters and Uploads</a></li>
1.42 +</ul>
1.43 +<h2>Perform Actions</h2>
1.44 +<p>Of all activities summarised above, this is the most vague because
1.45 +the kinds of actions performed by applications will vary substantially
1.46 +depending on what the application is supposed to do. Indeed, it is
1.47 +within this activity that most applications will probably be integrated
1.48 +with other systems - they may access databases or Web services, for
1.49 +example.</p>
1.50 +<p>WebStack does not mandate any particular style of integration with
1.51 +other systems. It is generally recommended that developers use
1.52 +whichever Python modules or packages they prefer and just to import
1.53 +these into their applications. See <a href="integrating.html">"Integrating
1.54 +with Other Systems"</a> for advice on this subject.</p>
1.55 +<h2>Produce a Response</h2>
1.56 +<p>This activity was briefly covered in the <code>MyApplication</code>
1.57 +example, but for "real world" applications the following topics must be
1.58 +understood in more detail:</p>
1.59 +<ul>
1.60 <li><a href="responses.html">Responses and Presentation</a></li>
1.61 <li><a href="state.html">Cookies, Sessions and Persistent
1.62 Information</a></li>