Mercurial > cgi-bin > hgweb.cgi > tincan
annotate pspx.html @ 25:e93e5e746cc5 draft header-includes
Preliminary debugging, still not fully tested.
| author | David Barts <n5jrn@me.com> |
|---|---|
| date | Sun, 26 May 2019 11:43:48 -0700 |
| parents | 8037bad7d5a8 |
| children | 336bc2f622e4 |
| rev | line source |
|---|---|
| 2 | 1 <!DOCTYPE html> |
| 2 <html> | |
| 3 <head> | |
| 4 <meta http-equiv="content-type" content="text/html; charset=UTF-8"> | |
| 5 <title>.pspx Template Files</title> | |
| 6 <style type="text/css"> | |
|
9
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
7 var { font-family: monospace; font-style: normal; } |
| 2 | 8 </style> |
| 9 </head> | |
| 10 <body> | |
| 11 <h1>.pspx Template Files</h1> | |
| 12 <h2>Introduction</h2> | |
|
9
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
13 Files ending in a <var>.pspx</var> extension define both routes and |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
14 templates. The files have two parts: a header and a body.<br> |
| 2 | 15 <h2>The Header</h2> |
| 16 <p>The header is optional and consists of lines starting with an octothorpe | |
| 17 (#) character. With the exception of the <code>#rem </code>header, all | |
| 18 header lines may appear only once in a given file.</p> | |
| 19 <dl> | |
| 5 | 20 <dt><code>#end</code></dt> |
|
11
8037bad7d5a8
Update documentation, fix some #forward bugs.
David Barts <n5jrn@me.com>
parents:
9
diff
changeset
|
21 <dd>Marks the last line of the headers. Since the end of the header lines |
|
8037bad7d5a8
Update documentation, fix some #forward bugs.
David Barts <n5jrn@me.com>
parents:
9
diff
changeset
|
22 is implicitly marked by the first line that does not start with <var>#</var>, |
|
8037bad7d5a8
Update documentation, fix some #forward bugs.
David Barts <n5jrn@me.com>
parents:
9
diff
changeset
|
23 this is needed only for templating languages where lines often start |
|
8037bad7d5a8
Update documentation, fix some #forward bugs.
David Barts <n5jrn@me.com>
parents:
9
diff
changeset
|
24 with <var>#</var>, such as Cheetah.</dd> |
| 2 | 25 <dt><code>#errors</code></dt> |
|
9
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
26 <dd>This is an error page which handles the specified HTTP error codes. |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
27 See the subsection on error pages below. </dd> |
| 2 | 28 <dt><code>#forward</code></dt> |
| 29 <dd>Ignore everything else in this template (and any code-behind | |
| 30 associated with it), using the specified route to serve it instead. The | |
| 31 route specified with <code>#forward</code> may itself contain a <code>#forward</code>, | |
| 32 but attempts to create a <code>#forward</code> loop are not allowed and | |
|
9
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
33 will cause a <var>TinCanError</var> to be raised. Note that unlike |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
34 calls to <code>app.forward()</code>, the <code>#forward</code> header |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
35 is resolved at route-creation time; no extra processing will happen at |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
36 request time.</dd> |
| 2 | 37 <dt><code>#hidden</code></dt> |
| 38 <dd>This is a hidden page; do not create a route for it. The page can only | |
| 39 be displayed by a forward.</dd> | |
| 40 <dt><code>#methods</code></dt> | |
| 5 | 41 <dd>A list of HTTP request methods, separated by whitespace, follows. The |
| 42 route will allow all specified methods. Not specifying this line is | |
| 43 equivalent to specifying <code>#methods GET</code>.</dd> | |
| 2 | 44 <dt><code>#python</code></dt> |
| 45 <dd>What follows is the name of the Python file containing the code-behind | |
| 46 for this route. If not specified, the code-behind will be in a file with | |
|
9
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
47 the same name but an extension of <var>.py</var>.</dd> |
| 2 | 48 <dt><code>#rem</code></dt> |
| 49 <dd>The rest of the line is treated as a remark (comment) and is ignored.</dd> | |
| 50 <dt><code>#template</code></dt> | |
| 51 <dd>Ignore the body of this file and instead use the template in the body | |
|
9
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
52 of the specified file, which must end in <var>.pspx</var>. Any headers |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
53 in the referred template file are ignored.</dd> |
| 2 | 54 </dl> |
| 55 <p>It is possible to include whitespace and special characters in arguments | |
| 56 to the <code>#forward</code>, <code>#python</code>, and <code>#template</code> | |
| 57 headers by using standard Python string quoting and escaping methods. For | |
| 58 example, <code>#python "space case.py"</code>.</p> | |
| 6 | 59 <p>Header directives that don't take arguments as a rule simply ignore them. |
| 60 For example, <code>#end headers</code> has the same effect as <code>#end</code>. | |
|
9
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
61 </p> |
| 2 | 62 <h3>Error Pages</h3> |
| 63 <p>Error pages supersede the standard Bottle error handling, and are created | |
|
9
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
64 by using the <code>#errors</code> page header. The <code>#hidden</code> |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
65 and <code>#method</code> header directives are ignored in error pages |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
66 (error pages are effectively hidden anyhow, by virtue of never having |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
67 normal routes created for them).</p> |
| 3 | 68 <p>The <code>#errors</code> directive takes a list of numeric error codes |
| 5 | 69 (values from 400 to 599 are allowed); the page is created to handle the |
| 70 specified errors. If no error codes are specified, the page will handle | |
| 71 all errors. The behavior of specifying multiple error pages for the same | |
| 72 error code is undefined; doing so is best avoided.</p> | |
|
9
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
73 <h3>Templates with No Code-Behind</h3> |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
74 <p>Code-behind is optional for both normal and error page templates. If |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
75 code-behind is not provided, TinCan will use the <var>Page</var> or <var>ErrorPage</var> |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
76 class as appropriate. </p> |
| 2 | 77 <h2>The Body</h2> |
| 78 <p>The body begins with the first line that <em>does not</em> start with <code>#</code> | |
|
11
8037bad7d5a8
Update documentation, fix some #forward bugs.
David Barts <n5jrn@me.com>
parents:
9
diff
changeset
|
79 (or the first line after the <code>#end</code> directive, whichever comes |
|
8037bad7d5a8
Update documentation, fix some #forward bugs.
David Barts <n5jrn@me.com>
parents:
9
diff
changeset
|
80 first) and has the exact same syntax that the templates are in for this |
|
8037bad7d5a8
Update documentation, fix some #forward bugs.
David Barts <n5jrn@me.com>
parents:
9
diff
changeset
|
81 webapp. By default, Chameleon templates are used. Cheetah, Jinja2, Mako, |
|
8037bad7d5a8
Update documentation, fix some #forward bugs.
David Barts <n5jrn@me.com>
parents:
9
diff
changeset
|
82 and Bottle SimpleTemplate templates are also supported, provided the |
|
8037bad7d5a8
Update documentation, fix some #forward bugs.
David Barts <n5jrn@me.com>
parents:
9
diff
changeset
|
83 webapp was launched to use them. (Only one template style per webapp is |
| 2 | 84 supported.)</p> |
| 85 <p>In order to make line numbers match file line numbers for reported | |
| 86 errors, the template engine will be passed a blank line for each header | |
| 87 line encountered. TinCan will strip out all leading blank lines when | |
| 88 rendering its responses.</p> | |
|
9
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
89 <h3>Default Template Variables</h3> |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
90 <p>By default, regular pages will have a single template variable available: |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
91 <var>page</var>, which refers to the <var>Page</var> class that contains |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
92 the code-behind logic for this page. The pertinent <var>bottle.Request</var> |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
93 and <var>bottle.Response</var> objects are available to normal, non-error |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
94 pages as <var>page.request</var> and <var>page.response</var>, |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
95 respectively.</p> |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
96 <p>Error pages have their code-behind logic in an <var>ErrorPage</var> |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
97 class. In addition to the standard <var>page</var> variable, error pages |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
98 also have <var>request</var> and <var>error</var> variables available by |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
99 default, which contain copies of the pertinent <var>bottle.Request</var> |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
100 and <var>bottle.HTTPError</var> objects respectively.</p> |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
101 <p>The default behavior of the <var>export</var> method (which exports |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
102 instance variables to template variables) in both the <var>Page</var> and |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
103 <var>ErrorPage</var> classes is to export, in addition to the default |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
104 variables, every user-created instance attribute that is not callable and |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
105 whose name does not start with an underscore. This behavior can be changed |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
106 if desired by overriding that method.</p> |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
107 <p>Note that if for some reason you create an instance variable named <var>page</var>, |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
108 it will overwrite the standard template variable by the same name.</p> |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
109 <p></p> |
| 2 | 110 </body> |
| 111 </html> |