← Back to branch summary

~launchpad-pqm/launchpad/devel

« back to all changes in this revision

Viewing changes to doc/webapp-process.txt

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2004-06-29 18:17:03 UTC
  • mfrom: (unknown (missing))
  • Revision ID: Arch-1:rocketfuel@canonical.com%soyuz--devel--0--patch-10
Make compatible with the ZopeX3 beta code.  Add document on writing a web app.
Patches applied:

 * steve.alexander@canonical.com/soyuz--devel--0--patch-3
   Added document on how to go about writing a web application.  Removed some lines from zopeapp.zcml that apply to zopex3 from the svn trunk, but not from the beta release

 * steve.alexander@canonical.com/soyuz--devel--0--patch-4
   Removed interpreter-configure include file, as it doesn't work with the zopex3 beta release.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/webapp-process.txt
 
1
=========================================
 
2
How to go about writing a web application
 
3
=========================================
 
4
 
 
5
Introduction
 
6
------------
 
7
 
 
8
This document presents an approach to constructing web applications,
 
9
emphasising well-designed user interaction.
 
10
 
 
11
In summary, we write a web application by
 
12
 
 
13
1. Design the database that lies behind the web application
 
14
   - Entity relationship models
 
15
   - SQL statements
 
16
2. Design the web application's user interface
 
17
   - Table of URLs (see later)
 
18
   - Page tempate mock-ups
 
19
3. Write the Interfaces that the application will use to access the database
 
20
   - interfaces.py files
 
21
4. Write the code and templates of the application
 
22
   - page templates
 
23
   - supporting classes
 
24
   - application components
 
25
 
 
26
Of course, this isn't a completely linear process.  Steps may be carried out
 
27
in parallel, and ongoing work in each step will feed into the other steps.
 
28
 
 
29
 
 
30
Web application architecture
 
31
----------------------------
 
32
 
 
33
For the purposes of this document, a web application is put together as
 
34
follows::
 
35
 
 
36
 +--------------------------------------------------------------------------+
 
37
 |              {  Amorphous cloud of URLs  }                               |
 
38
 |  URLS      {   /rosetta/foo/bar/baz.html   }                             |
 
39
 |             {                             }                              |
 
40
 |  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~  |
 
41
 |                           { Pages       SubURLs                          |
 
42
 |            PRESENTATION   { Views       Templates                        |
 
43
 |                           { Traversal   Support classes                  |
 
44
 |                                                                          |
 
45
 |  WEB APP   ------------------------------------------------- Interfaces  |
 
46
 |                                                                          |
 
47
 |            APPLICATION    { Utilities   Components                       |
 
48
 |            COMPONENTS     { Adapters                                     |
 
49
 |                                                                          |
 
50
 |                                                                          |
 
51
 |            LIBRARIES      { Python standard library                      |
 
52
 |                           { Other libraries                              |
 
53
 |            ------------------------------------------------- Interfaces  |
 
54
 |  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~   |
 
55
 |                                                                          |
 
56
 |  DATABASE     relations, fields, constraints                             |
 
57
 +--------------------------------------------------------------------------+
 
58
 
 
59
The boundaries of our web application are URLs at the top and the database
 
60
at the bottom.  So, we must carefully define these things that lie at the
 
61
boundaries, so that we can work out what must go in the middle.
 
62
 
 
63
URLs
 
64
----
 
65
 
 
66
URLs are the boundary between the web application and web browsers.  When you
 
67
point a web browser at a URL, you'll get one of the following:
 
68
 
 
69
- page
 
70
- form
 
71
- image or other data
 
72
- redirect
 
73
- "not found" error
 
74
- "unauthorized" error
 
75
 
 
76
We'll be mostly concerned with pages, forms and redirects.  We'll be concerned
 
77
with image and other data only when they are "managed content" and not just
 
78
part of the skin of the site.  The photograph of a member of the site is an
 
79
example of managed content: it is stored in the database and may be
 
80
manipulated through using the application.  CSS files, javascript files,
 
81
icons and logos are typically elements that make up the "skin" of the
 
82
application, and are not managed through the application.
 
83
 
 
84
Another example of image or other data that is managed content is if we want
 
85
to allow users to download a .po or .pot file of translations.
 
86
 
 
87
Forms are rendered in HTML and will typically be "self-posting forms".  That
 
88
is, the address posted to when the [submit] button is pressed will be the
 
89
same as the address the page was got from.  This allows browsers' bookmarks
 
90
to work properly, allows us to straightforwardly validate data entered into
 
91
the form, and keeps the URL space neat.
 
92
 
 
93
The "not found" error is the familiar "404 Not Found" given when someone
 
94
tries to access a URL that is not known by our system.
 
95
 
 
96
An "unauthorized" error means that accessing the given URL requires some
 
97
authentication.  The browser will prompt the user to provide some additional
 
98
authentication.  Alternatively, if we use other login schemes than HTTP Basic
 
99
or HTTP Digest, then the web application may present a login form to the
 
100
user.
 
101
 
 
102
A "redirect" causes the browser to immediately fetch a different URL.  This
 
103
process is usually not noticed by the user.
 
104
 
 
105
 
 
106
The URL table
 
107
-------------
 
108
 
 
109
We need to construct a table describing the URLs used in our application. We
 
110
won't bother about the protocol part or any leading path segments of the URL.
 
111
In the table below, we'll assume all URLs start http://example.com/rosetta/...
 
112
 
 
113
The table has the following columns
 
114
 
 
115
- URL: The rest of the URL after /rosetta.  For clarity, we'll start it with
 
116
  a "./".  So, the rosetta application's main page might be "./index.html".
 
117
  If this table is written in HTML, this may be a link to a mock-up HTML page
 
118
  showing what will be found at that URL.
 
119
 
 
120
- Default: For application components, the default page to use.  More about
 
121
  this later.
 
122
 
 
123
- Type: This is one of "app component", "page", "form", "redirect", "data"
 
124
 
 
125
- Description: A textual description of what is found at this URL.
 
126
  This may be a link to further information about the functioning of that
 
127
  page, form validation constraints, and so on.
 
128
 
 
129
When you get an App Component at a particular URL, what does that mean?  At
 
130
certain points in our URL space, we want to expose a set of related
 
131
functionality under a particular URL.  For example, the URL
 
132
"./projects/mozilla/show-teams" might show the teams working on the Mozilla
 
133
project, while "./projects/mozilla/translations" might show the translations
 
134
of the mozilla project.  Users of the system will come to understand that
 
135
things related to Mozilla are to be found at URLs starting with
 
136
"./projects/mozilla".  We want to present some page at "./projects/mozilla".
 
137
Rather than make a special "no name" page for this, we choose one of the
 
138
other pages that we want to return.  Mozilla is a Project.  So, if the
 
139
default page for a Project is "translations", then going to
 
140
"./projects/mozilla" will return the same page as
 
141
"./projects/mozilla/translations".  The usual default page is "index.html".
 
142
 
 
143
 
 
144
Here's an example of a table for the Rosetta project::
 
145
 
 
146
  URL                 Default      Type            Description
 
147
 
 
148
  ./                  index.html   app component   The rosetta application
 
149
 
 
150
  ./index.html                     page            Initial navigation page
 
151
 
 
152
  ./intro.html                     page            Introductory page
 
153
 
 
154
  ./signup.html                    form            Allows a new user to
 
155
                                                   register with the system.
 
156
 
 
157
  ./projects          index.html   app component   Collection of rosetta
 
158
                                                   projects
 
159
 
 
160
  ./projects/index.html            form            Shows ways to search
 
161
                                                   through projects
 
162
 
 
163
  ./projects/$PROJECT translations app component   A particular project
 
164
                                                   $PROJECT is the name of
 
165
                                                   the project. See key below.
 
166
 
 
167
  ./projects/$PROJECT/translations page            Shows all translations
 
168
                                                   for this project.
 
169
 
 
170
 
 
171
  Key to $VARs
 
172
  ============
 
173
  $PROJECT    The name of the project.  This is the name attribute of
 
174
              the IProject interface, or the name field in the Project
 
175
              relation.  Case is not significant, and is normalized to
 
176
              lower-case in the UI.  Examples: 'mozilla', 'gtk+'.
 
177
 
 
178
We can use the URL table for simple automated functional testing of the web
 
179
application, given some suitable $VAR substitutions.
 
180
 
 
181
 
 
182
Structure of a web application URL
 
183
----------------------------------
 
184
 
 
185
We need to know what types of things are at a particular URL.  Here's an
 
186
example of a typical URL in a web application.  This time, I've included
 
187
the "rosetta" path segment at the root.
 
188
 
 
189
  /rosetta/projects/$PACKAGENAME/teams/$TEAM/add-member.html
 
190
   |       |        |            |     |     |
 
191
   |       |        |            |     |     page to add a new member
 
192
   |       |        |            |     Name of a particular team "22"
 
193
   |       |        |            The teams working on this project
 
194
   |       |        A particular project name, such as "mozilla"
 
195
   |       Collection of projects that can be queried
 
196
  The rosetta application
 
197
 
 
198
 
 
199
Glossary
 
200
--------
 
201
 
 
202
Skin:
 
203
    The way the user interface looks in a web browser.  The elements of this
 
204
    user interface, including CSS, images and an overall site template.
 
205
 
 
206
    It is possible to provide multiple skins to the same web application,
 
207
    for example a simple one and a very complex one.
 
208
 
 
209
Published:
 
210
    Something that is made available at a particular URL is said to be
 
211
    published.
 
212
 
 
213
Presentation component:
 
214
    Some software that interacts with the browser's request and returns
 
215
    information to the browser.  This is typically a page template or a
 
216
    page template plus a supporting class.
 
217
 
 
218
    Other presentation components are traversers, which know what to do
 
219
    when further path segments are given in a URL; and resources, which
 
220
    are CSS files, javascript files, logos, icons, etc.
 
221
 
 
222
Application component:
 
223
    An object that represents application functionality, but not presentation
 
224
    functionality.  It should have a well-defined interface so that different
 
225
    implementations of a given application component can be presented by
 
226
    the same presentation components.
 
227
 
 
228
Component:
 
229
    An object that has clearly defined interfaces.
 
230
 
 
231
    These interfaces may represent what it offers, or what it requires in
 
232
    order to function.
 
233
 
 
234
Utility:
 
235
    A component that is looked up by the interface that it provides.
 
236
 
 
237
Adapter:
 
238
    A component that knows how to use a particular interface in order to
 
239
    provide a different interface.
 
240
 
 
241
Interface:
 
242
    A software-readable definition of an API provided by some object.
 
243
 
 
244
View:
 
245
    A kind of presentation component that provides a representation of
 
246
    some other component.
 
247
 
 
248
Browser presentation:
 
249
    Presentation intended for a web browser, as distinct from a presentation
 
250
    intended for XML-RPC or webdav.  Or even email.
 
251
 
 
252
Non-published {view,resource}:
 
253
    A {view,resource} that is used by other presentation components, but
 
254
    that is not itself addressable by a URL.
 
255
 
 
256
 
 
257
# arch-tag: cf2cb34d-52a5-4615-b135-439d70f43f36