Mercurial > cgi-bin > hgweb.cgi > tincan
annotate code_behind.html @ 18:e88ab99914cf draft
More improvements to the error reportage.
| author | David Barts <n5jrn@me.com> |
|---|---|
| date | Mon, 20 May 2019 08:40:56 -0700 |
| parents | 8037bad7d5a8 |
| children |
| rev | line source |
|---|---|
| 10 | 1 <!DOCTYPE html> |
| 2 <html> | |
| 3 <head> | |
| 4 <meta http-equiv="content-type" content="text/html; charset=UTF-8"> | |
| 5 <title>Code-Behind Files</title> | |
| 6 <style type="text/css"> | |
| 7 var { font-family: monospace; font-style: normal; } | |
| 8 </style> | |
| 9 </head> | |
| 10 <body> | |
| 11 <h1>Code-Behind Files</h1> | |
| 12 <h2>Introduction</h2> | |
| 13 <p> In the main webapp tree (i.e. not in <var>WEB-INF</var>), files ending | |
| 14 in a <var>.py</var> extension contain code-behind logic. By default, the | |
| 15 file names match while only the extensions differ; e.g. <var>foo.py</var> | |
| 16 will contain the code-behind logic associated with <var>foo.pspx</var>. | |
| 17 Use of the <code>#python</code> and/or <code>#template</code> header | |
|
11
8037bad7d5a8
Update documentation, fix some #forward bugs.
David Barts <n5jrn@me.com>
parents:
10
diff
changeset
|
18 directives can of course change this default association.</p> |
| 10 | 19 <p>Pretty much anything can be in the code-behind files, with one |
| 20 restriction. There must be one and only one instance of a subclass of | |
| 21 either <var>Page</var> (normal pages) or <var>ErrorPage</var> (error | |
| 22 pages).</p> | |
| 23 <h2>BasePage Objects</h2> | |
| 24 <p>Both <var>Page</var> and <var>ErrorPage</var> objects are subclasses of | |
| 25 <var>BasePage</var>, and share a similar structure. Creating class | |
| 26 instances is lightweight and doesn't do much. The main processing logic | |
| 27 happens in the <var>handle</var> method, which accepts no arguments. When | |
| 28 processing is complete, the <var>export</var> method is called to export | |
| 29 template variables; it should return a dictionary or dictionary-like | |
| 30 object.</p> | |
| 31 <p>Because the constructors of both <var>Page</var> and <var>ErrorPage</var> | |
| 32 are intended to be called by TinCan itself, they should not be overridden. | |
| 33 Override <var>handle</var> and if necessary <var>export</var>, and | |
| 34 define additional methods and instance variables to your heart's content. | |
| 35 Anything not callable that does not start with underscore will | |
| 36 automatically be available as a template variable by default.</p> | |
| 37 <p>Having no or multiple instances <var>Page</var> or <var>ErrorPage</var> | |
| 38 classes is an error and will cause the corresponding page to fail to | |
| 39 launch. Aside from this one restriction, you are free to import modules | |
| 40 and define classes as you see fit in the code-behind.</p> | |
| 41 <p>Note that it is not normally necessary to override the <var>export</var> | |
| 42 method; the default behavior as described in the <em>Default Template | |
| 43 Variables</em> section of the template documentation is normally | |
| 44 sufficient.</p> | |
|
11
8037bad7d5a8
Update documentation, fix some #forward bugs.
David Barts <n5jrn@me.com>
parents:
10
diff
changeset
|
45 <h3>Page Objects</h3> |
|
8037bad7d5a8
Update documentation, fix some #forward bugs.
David Barts <n5jrn@me.com>
parents:
10
diff
changeset
|
46 <p>These contain the code-behind for normal pages. When the <var>handle</var> |
|
8037bad7d5a8
Update documentation, fix some #forward bugs.
David Barts <n5jrn@me.com>
parents:
10
diff
changeset
|
47 method begins executing, they contain two instance variables: <var>request</var> |
|
8037bad7d5a8
Update documentation, fix some #forward bugs.
David Barts <n5jrn@me.com>
parents:
10
diff
changeset
|
48 (a <var>bottle.Request</var> object) and <var>response</var> (a <var>bottle.Response</var> |
|
8037bad7d5a8
Update documentation, fix some #forward bugs.
David Barts <n5jrn@me.com>
parents:
10
diff
changeset
|
49 object). </p> |
|
8037bad7d5a8
Update documentation, fix some #forward bugs.
David Barts <n5jrn@me.com>
parents:
10
diff
changeset
|
50 <h3>ErrorPage Objects</h3> |
|
8037bad7d5a8
Update documentation, fix some #forward bugs.
David Barts <n5jrn@me.com>
parents:
10
diff
changeset
|
51 <p>These contain the code-behind for error pages. When the <var>handle</var> |
|
8037bad7d5a8
Update documentation, fix some #forward bugs.
David Barts <n5jrn@me.com>
parents:
10
diff
changeset
|
52 method begins executing, they contain two instance variables: <var>request</var> |
|
8037bad7d5a8
Update documentation, fix some #forward bugs.
David Barts <n5jrn@me.com>
parents:
10
diff
changeset
|
53 (a <var>bottle.Request</var> object) and <var>error</var> (a <var>bottle.HTTPError</var> |
|
8037bad7d5a8
Update documentation, fix some #forward bugs.
David Barts <n5jrn@me.com>
parents:
10
diff
changeset
|
54 object). </p> |
|
8037bad7d5a8
Update documentation, fix some #forward bugs.
David Barts <n5jrn@me.com>
parents:
10
diff
changeset
|
55 <h3>The Application Context</h3> |
|
8037bad7d5a8
Update documentation, fix some #forward bugs.
David Barts <n5jrn@me.com>
parents:
10
diff
changeset
|
56 <p>There is no separate standard instance variable in either <var>Page</var> |
|
8037bad7d5a8
Update documentation, fix some #forward bugs.
David Barts <n5jrn@me.com>
parents:
10
diff
changeset
|
57 or <var>ErrorPage</var> that provides such, because it is available via |
|
8037bad7d5a8
Update documentation, fix some #forward bugs.
David Barts <n5jrn@me.com>
parents:
10
diff
changeset
|
58 <var> request.app</var>. See the Bottle documentation for more |
|
8037bad7d5a8
Update documentation, fix some #forward bugs.
David Barts <n5jrn@me.com>
parents:
10
diff
changeset
|
59 information.</p> |
| 10 | 60 <h2>Code-Behind is Optional</h2> |
| 61 <p>If you define a template with no code-behind file, TinCan will use either | |
| 62 <var>Page</var> or <var>ErrorPage</var> as appropriate, which will | |
| 63 present the standard, minimal set of variables to your template.</p> | |
| 64 <h2>Code-Behind Files Are Not Standard Modules</h2> | |
| 65 <p>Code-behind files are compiled and loaded programmatically via low-level | |
| 66 Python library calls. The normal Python module subsystem and its cache is | |
| 67 not used. Directories in the tree served by a TinCan webapp are <em>not</em> | |
| 68 part of <var>sys.path</var>. Attempts by one code-behind file to <code>import</code> | |
| 69 another will fail.</p> | |
| 70 <p>If you have webapp-specific logic which is used in rendering multiple | |
| 71 pages, it belongs in <var>WEB-INF/lib</var>, which is automatically added | |
| 72 to <var>sys.path</var>; thus files therein are importable via the | |
| 73 standard mechanisms.</p> | |
| 74 </body> | |
| 75 </html> |