annotate code_behind.html @ 47:879ec681f7e3 draft

Add --compile option.
author David Barts <n5jrn@me.com>
date Thu, 30 May 2019 20:14:14 -0700
parents 8037bad7d5a8
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
10
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
1 <!DOCTYPE html>
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
2 <html>
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
3 <head>
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
4 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
5 <title>Code-Behind Files</title>
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
6 <style type="text/css">
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
7 var { font-family: monospace; font-style: normal; }
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
8 </style>
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
9 </head>
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
10 <body>
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
11 <h1>Code-Behind Files</h1>
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
12 <h2>Introduction</h2>
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
13 <p> In the main webapp tree (i.e. not in <var>WEB-INF</var>), files ending
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
14 in a <var>.py</var> extension contain code-behind logic. By default, the
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
15 file names match while only the extensions differ; e.g. <var>foo.py</var>
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
16 will contain the code-behind logic associated with <var>foo.pspx</var>.
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
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
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
19 <p>Pretty much anything can be in the code-behind files, with one
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
20 restriction. There must be one and only one instance of a subclass of
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
21 either <var>Page</var> (normal pages) or <var>ErrorPage</var> (error
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
22 pages).</p>
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
23 <h2>BasePage Objects</h2>
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
24 <p>Both <var>Page</var> and <var>ErrorPage</var> objects are subclasses of
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
25 <var>BasePage</var>, and share a similar structure. Creating class
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
26 instances is lightweight and doesn't do much. The main processing logic
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
27 happens in the <var>handle</var> method, which accepts no arguments. When
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
28 processing is complete, the <var>export</var> method is called to export
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
29 template variables; it should return a dictionary or dictionary-like
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
30 object.</p>
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
31 <p>Because the constructors of both <var>Page</var> and <var>ErrorPage</var>
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
32 are intended to be called by TinCan itself, they should not be overridden.
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
33 Override <var>handle</var> and if necessary <var>export</var>, and
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
34 define additional methods and instance variables to your heart's content.
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
35 Anything not callable that does not start with underscore will
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
36 automatically be available as a template variable by default.</p>
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
37 <p>Having no or multiple instances <var>Page</var> or <var>ErrorPage</var>
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
38 classes is an error and will cause the corresponding page to fail to
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
39 launch. Aside from this one restriction, you are free to import modules
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
40 and define classes as you see fit in the code-behind.</p>
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
41 <p>Note that it is not normally necessary to override the <var>export</var>
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
42 method; the default behavior as described in the <em>Default Template
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
43 Variables</em> section of the template documentation is normally
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
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.&nbsp; 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
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
60 <h2>Code-Behind is Optional</h2>
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
61 <p>If you define a template with no code-behind file, TinCan will use either
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
62 <var>Page</var> or <var>ErrorPage</var> as appropriate, which will
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
63 present the standard, minimal set of variables to your template.</p>
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
64 <h2>Code-Behind Files Are Not Standard Modules</h2>
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
65 <p>Code-behind files are compiled and loaded programmatically via low-level
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
66 Python library calls. The normal Python module subsystem and its cache is
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
67 not used. Directories in the tree served by a TinCan webapp are <em>not</em>
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
68 part of <var>sys.path</var>. Attempts by one code-behind file to <code>import</code>
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
69 another will fail.</p>
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
70 <p>If you have webapp-specific logic which is used in rendering multiple
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
71 pages, it belongs in <var>WEB-INF/lib</var>, which is automatically added
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
72 to <var>sys.path</var>; thus files therein are importable via the
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
73 standard mechanisms.</p>
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
74 </body>
84998cd4e123 Add more provisional documentation.
David Barts <n5jrn@me.com>
parents:
diff changeset
75 </html>