Mercurial > cgi-bin > hgweb.cgi > tincan
comparison code_behind.html @ 10:84998cd4e123 draft
Add more provisional documentation.
| author | David Barts <n5jrn@me.com> |
|---|---|
| date | Mon, 13 May 2019 21:24:48 -0700 |
| parents | |
| children | 8037bad7d5a8 |
comparison
equal
deleted
inserted
replaced
| 9:75e375b1976a | 10:84998cd4e123 |
|---|---|
| 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 | |
| 18 directives will of course change this default association.</p> | |
| 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> | |
| 45 <h2>Code-Behind is Optional</h2> | |
| 46 <p>If you define a template with no code-behind file, TinCan will use either | |
| 47 <var>Page</var> or <var>ErrorPage</var> as appropriate, which will | |
| 48 present the standard, minimal set of variables to your template.</p> | |
| 49 <h2>Code-Behind Files Are Not Standard Modules</h2> | |
| 50 <p>Code-behind files are compiled and loaded programmatically via low-level | |
| 51 Python library calls. The normal Python module subsystem and its cache is | |
| 52 not used. Directories in the tree served by a TinCan webapp are <em>not</em> | |
| 53 part of <var>sys.path</var>. Attempts by one code-behind file to <code>import</code> | |
| 54 another will fail.</p> | |
| 55 <p>If you have webapp-specific logic which is used in rendering multiple | |
| 56 pages, it belongs in <var>WEB-INF/lib</var>, which is automatically added | |
| 57 to <var>sys.path</var>; thus files therein are importable via the | |
| 58 standard mechanisms.</p> | |
| 59 </body> | |
| 60 </html> |