← Back to branch summary

~azzar1/unity/add-show-desktop-key

« back to all changes in this revision

Viewing changes to doc/notes/apps/dispatch.txt

  • Committer: mattgiuca
  • Date: 2008-01-11 00:49:06 UTC
  • Revision ID: svn-v3-trunk0:2b9c9e99-6f39-0410-b283-7f802c844ae2:trunk:172
util: Added buildurl function.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/notes/apps/dispatch.txt
 
1
IVLE Dispatch Module Design
 
2
===========================
 
3
 
 
4
    Author: Matt Giuca
 
5
    Date: 11/12/2007
 
6
 
 
7
This is the design for the dispatch module (the top-level app which handles
 
8
all requests in the web app and passes them on to other apps).
 
9
 
 
10
Request handling sequence
 
11
-------------------------
 
12
 
 
13
The request handling sequence consists of two parts. The first part is
 
14
dispatch being called. It autonomously performs auth and some housekeeping,
 
15
and then passes control to another specified app.
 
16
 
 
17
The second part of request handling is done by the app in question. The object
 
18
which dispatch passes the app has several methods in it which the app can
 
19
call. In this way, dispatch code is still used in the second part of the
 
20
request handling, but it is used passively instead of actively.
 
21
 
 
22
Finally, dispatch cleans up a little bit (writing footers, etc) when the app
 
23
exits.
 
24
 
 
25
1. dispatch loads. It imports config modules, so it has access to
 
26
    admin-configured information about the plugged in apps and other
 
27
    settings.
 
28
2. Breaks the URL and request data down and builds the IVLE request object
 
29
    (which is higher level than the Apache request object and independent of
 
30
    mod_python). This includes breaking the path into the "first directory"
 
31
    (the app name) and the rest of the path (which is passed to the app as the
 
32
    "path").
 
33
3. Decides which app to load by looking it up in the app list. If no path is
 
34
    specified, selects the default app (does not redirect just yet). If the
 
35
    app is not found in the app list, throws a 404 error and exits.
 
36
4. If the app requires authentication, checks the session information to see
 
37
    if a user is logged in. If not, passes control to a special "app" (built
 
38
    into dispatch, but with the same interface as other apps), the login page,
 
39
    and skips to step 7.
 
40
5. If no app was specified, performs a redirect to the default app, and
 
41
    exits.
 
42
6. Passes control to the specified app.
 
43
7. After the app completes, performs cleanup (such as writing HTML footer).
 
44
 
 
45
The dispatch also provides several callbacks.
 
46
 
 
47
The dispatch "request" object could just be the Apache request object, but
 
48
augmented with additional methods and attributes, and an overridden "write"
 
49
method.
 
50
 
 
51
### Writing callbacks ###
 
52
 
 
53
One important callback sequence is writing to the output. The dispatch does
 
54
not provide the app with an Apache request object. This is to ensure that none
 
55
of the apps are dependent on mod_python (even though dispatch, itself, is).
 
56
Each app therefore calls the dispatch request object to do all the writing.
 
57
 
 
58
(Note the apps should be given access to the Apache request object but
 
59
recommended not to use it. This is so that "exec" can pass it to the executed
 
60
code apps).
 
61
 
 
62
The writing sequence takes place in two parts: writing the HTTP headers, and
 
63
writing the response.
 
64
 
 
65
The HTTP headers are written by dispatch, not the app. The app just sets
 
66
fields in the request object, such as "content_type", "title" and
 
67
"write_html_head_foot". (This is similar to how Apache works but has some
 
68
extra fields).
 
69
 
 
70
When the first actual write call is made, the app looks at the fields and
 
71
writes out the HTTP headers. The "write_html_head_foot" field, if True, causes
 
72
dispatch to also write out the IVLE HTML header bar section.
 
73
 
 
74
When doing the cleanup step, if write_html_head_foot is set, dispatch then
 
75
writes the HTML footer.
 
76
 
 
77
The header and footer includes the html and body tags. Therefore, any app
 
78
which sets "write_html_head_foot" should just write body content, no html or
 
79
body tags.
 
80
 
 
81
Login screen
 
82
------------
 
83
The login screen is a special part of IVLE because it is not part of any
 
84
specific app, and does not have its own URL (there is no `/login`). It is
 
85
actually part of the dispatch module.
 
86
 
 
87
The login screen is displayed instead of whichever page was requested if the
 
88
app or page requested requires login. It does not navigate away from that page
 
89
(it keeps the same URL as requested). This is so that once the login is
 
90
successful, it can reload that URL and be on the requested page.
 
91
 
 
92
The login screen gracefully handles browsers without JavaScript, giving a nice
 
93
error message. The other pages won't necessarily be so graceful, as the user
 
94
is expected to have JavaScript if they passed the login screen.
 
95
 
 
96
The login interaction will be done with Ajax, because it might as well be.
 
97
This simplifies the system because the primary (non-ajax) requests do not
 
98
contain login POSTdata. The login is made to a special url which returns JSON,
 
99
and sets cookies/sessions. Upon success, the JavaScript itself performs a
 
100
hard refresh, which then succeeds because the cookie has been set to log in.
 
101
 
 
102
The login screen has the login box on the right, and displays other system
 
103
information on the rest of the screen. (This information is stuff the students
 
104
should probably see once in awhile even though they won't navigate explicitly
 
105
to it - system and subject announcements, and a random "tip of the day").
 
106
 
 
107
The IVLE Request object
 
108
-----------------------
 
109
 
 
110
The IVLE request object is mostly a wrapper around the Apache request object,
 
111
but it's a bit higher level and does not depend upon mod_python.
 
112
 
 
113
The file dispatch/request.py (or documentation generated from it) formally
 
114
specifies the attributes and methods of this object.