← Back to branch summary

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

« back to all changes in this revision

Viewing changes to doc/app_howto.txt

  • Committer: mattgiuca
  • Date: 2007-12-16 23:02:54 UTC
  • Revision ID: svn-v3-trunk0:2b9c9e99-6f39-0410-b283-7f802c844ae2:trunk:67
doc: Added app_howto doc, a guide on IVLE apps interface.
        Added Makefile for this directory.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/app_howto.txt
60
60
Application Interface
61
61
---------------------
62
62
 
63
 
The application directory must have two special files:
64
 
 
65
 
* `__init__.py` is the application entrypoint, discussed below.
66
 
* `help.html` is the application's help file. Only required if `hashelp` is
67
 
    set to True in the application database.
68
 
 
69
 
The directory may contain any other files you wish, including other Python
70
 
modules to import. Note that no files places in the application directory or
71
 
its subdirectories will be directly visible from the web.
72
 
 
73
 
If you wish to make static files such as images, JavaScript and CSS content
74
 
available, they must be placed in `media/apps/yourapp`. Import common.util and
75
 
use `util.make_path` to generate URLs which point to the media directory.
76
 
 
77
 
`__init__.py` must contain a function `handle(req)` which takes 1 argument.
78
 
The argument, "req", will be passed an IVLE Request object. This is very
79
 
similar to the mod_python/Apache Request object but has an
80
 
independently-defined interface. The Request object provides input data in its
81
 
fields. It also provides a `write` method through which the application sends
82
 
its output.
83
 
 
84
 
The `handle` function has no return value.
85
 
 
86
 
The application should operate by reading input from req, setting its fields
87
 
accordingly, then writing the output data. The HTTP response status is set by
88
 
one of the fields of the Request. It also provides error and redirection
89
 
functions which halt execution by throwing an exception.
90
 
 
91
 
See the documentation on `dispatch.request` for the details of this object.
92
 
 
93
 
### Help file ###
94
 
 
95
 
Applications with `hashelp` set to True in the database are required to have
96
 
an additional file, "help.html". This file's contents are displayed by the
97
 
Help app.
98
 
 
99
 
This is not an ordinary HTML file. It should be a valid XHTML file except
100
 
should not contain html or body tags (its contents should just be the inside
101
 
of a body tag). This is equivalent to the output of an app which has
102
 
`write_html_head_foot` set to True. Note that this means it is not a valid XML
103
 
file, but it will be valid once rendered by the Help app.
104
 
 
105
 
The help file will be styled by IVLE's default style sheet. Please use h2 for
106
 
headings (h1 will be used for the main page heading). Use other HTML elements
107
 
in a natural way and they will be styled accordingly.
108
 
 
109
 
Important notes
110
 
---------------
111
 
 
112
 
* The settings of the Request object can only be set before any writing takes
113
 
  place. This is necessary to ensure the correct HTTP and HTML headers can be
114
 
  written before the first actual piece of data is written. Any settings which
115
 
  are set after the first write will be ignored.
116
 
* Similarly, throwing errors or redirects after the first write will not have
117
 
  the intended effects, as the HTTP headers will not be written.
118
 
* Never generate absolute URLs directly (either site-absolute or
119
 
  world-absolute). Applications should not guess where IVLE is located in the
120
 
  site's URL hierarchy. Instead use `common.util.make_path`, and supply it
121
 
  with a path relative to the IVLE site root.
122
 
* All HTML pages generated by the app should set `req.write_html_head_foot` to
123
 
  True (which will decorate the page in the IVLE theme and interface). All
124
 
  non-HTML pages should set it to False or the output will be corrupted by
125
 
  HTML headers. An exception to this rule is an app such as "serve" which
126
 
  serves user applications which should not be decorated by the IVLE
127
 
  interface.
128
 
* Applications which wish to access the student's file system or subversion
129
 
  dynamically (using Ajax) can do so through the `fileservice` app. This will
130
 
  be described in detail in another document. See the `files` app for an
131
 
  example.
132
 
 
133
63
Example Application
134
64
-------------------
135
65
 
143
73
    def handle(req):
144
74
        req.content_type = "text/html"
145
75
        req.write_html_head_foot = True
146
 
        req.write("<div id="ivle_padding">\n")
147
 
        req.write("  <p>Hello, IVLE!</p>\n")
148
 
        req.write("</div>\n")
 
76
        req.write("<p>Hello, IVLE!</p>\n")
149
77
 
150
78
Now, edit the file `conf/apps.py`, and add the following lines:
151
79
 
155
83
    app_hello.requireauth = False
156
84
    app_hello.hashelp = False
157
85
 
158
 
Add `"hello" : app\_hello,` to the app\_url dictionary. Add `"hello"` to the
159
 
apps\_in\_tabs list.
 
86
Add `"hello" : app_hello,` to the app_url dictionary. Add `"hello"` to the
 
87
apps_in_tabs list.
160
88
 
161
89
Now restart the web server, and the "Hello World" tab should appear. Click
162
90
the tab to call your new app.
167
95
XHTML body element. The final output will be valid XHTML 1.0 Strict if the
168
96
application's output is.
169
97
 
170
 
Note that by default, there is no padding around the application's HTML
171
 
output. This is because more complex apps (most of ours) don't work properly
172
 
with padding. Simpler apps (which simply write HTML paragraph content) look
173
 
better with padding.  Apps can wrap all of their output in a
174
 
'<div id="ivle_padding">' element (as shown above) to get padding.
175
 
 
176
98
### Making a file dump ###
177
99
 
178
100
You can modify the application to dump files from the students directories