Mercurial > cgi-bin > hgweb.cgi > tincan
annotate pspx.html @ 10:84998cd4e123 draft
Add more provisional documentation.
| author | David Barts <n5jrn@me.com> |
|---|---|
| date | Mon, 13 May 2019 21:24:48 -0700 |
| parents | 75e375b1976a |
| children | 8037bad7d5a8 |
| 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> |
| 21 <dd>Marks the last line of the headers. Needed only for templating | |
|
9
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
22 languages where lines often start with <var>#</var>, such as Cheetah.</dd> |
| 2 | 23 <dt><code>#errors</code></dt> |
|
9
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
24 <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
|
25 See the subsection on error pages below. </dd> |
| 2 | 26 <dt><code>#forward</code></dt> |
| 27 <dd>Ignore everything else in this template (and any code-behind | |
| 28 associated with it), using the specified route to serve it instead. The | |
| 29 route specified with <code>#forward</code> may itself contain a <code>#forward</code>, | |
| 30 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
|
31 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
|
32 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
|
33 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
|
34 request time.</dd> |
| 2 | 35 <dt><code>#hidden</code></dt> |
| 36 <dd>This is a hidden page; do not create a route for it. The page can only | |
| 37 be displayed by a forward.</dd> | |
| 38 <dt><code>#methods</code></dt> | |
| 5 | 39 <dd>A list of HTTP request methods, separated by whitespace, follows. The |
| 40 route will allow all specified methods. Not specifying this line is | |
| 41 equivalent to specifying <code>#methods GET</code>.</dd> | |
| 2 | 42 <dt><code>#python</code></dt> |
| 43 <dd>What follows is the name of the Python file containing the code-behind | |
| 44 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
|
45 the same name but an extension of <var>.py</var>.</dd> |
| 2 | 46 <dt><code>#rem</code></dt> |
| 47 <dd>The rest of the line is treated as a remark (comment) and is ignored.</dd> | |
| 48 <dt><code>#template</code></dt> | |
| 49 <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
|
50 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
|
51 in the referred template file are ignored.</dd> |
| 2 | 52 </dl> |
| 53 <p>It is possible to include whitespace and special characters in arguments | |
| 54 to the <code>#forward</code>, <code>#python</code>, and <code>#template</code> | |
| 55 headers by using standard Python string quoting and escaping methods. For | |
| 56 example, <code>#python "space case.py"</code>.</p> | |
| 6 | 57 <p>Header directives that don't take arguments as a rule simply ignore them. |
| 58 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
|
59 </p> |
| 2 | 60 <h3>Error Pages</h3> |
| 61 <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
|
62 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
|
63 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
|
64 (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
|
65 normal routes created for them).</p> |
| 3 | 66 <p>The <code>#errors</code> directive takes a list of numeric error codes |
| 5 | 67 (values from 400 to 599 are allowed); the page is created to handle the |
| 68 specified errors. If no error codes are specified, the page will handle | |
| 69 all errors. The behavior of specifying multiple error pages for the same | |
| 70 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
|
71 <h3>Templates with No Code-Behind</h3> |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
72 <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
|
73 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
|
74 class as appropriate. </p> |
| 2 | 75 <h2>The Body</h2> |
| 76 <p>The body begins with the first line that <em>does not</em> start with <code>#</code> | |
| 77 and has the exact same syntax that the templates are in for this webapp. | |
| 78 By default, Chameleon templates are used. Cheetah, Jinja2, Mako, and | |
| 79 Bottle SimpleTemplate templates are also supported, provided the webapp | |
| 80 was launched to use them. (Only one template style per webapp is | |
| 81 supported.)</p> | |
| 82 <p>In order to make line numbers match file line numbers for reported | |
| 83 errors, the template engine will be passed a blank line for each header | |
| 84 line encountered. TinCan will strip out all leading blank lines when | |
| 85 rendering its responses.</p> | |
|
9
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
86 <h3>Default Template Variables</h3> |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
87 <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
|
88 <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
|
89 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
|
90 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
|
91 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
|
92 respectively.</p> |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
93 <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
|
94 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
|
95 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
|
96 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
|
97 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
|
98 <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
|
99 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
|
100 <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
|
101 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
|
102 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
|
103 if desired by overriding that method.</p> |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
104 <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
|
105 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
|
106 <p></p> |
| 2 | 107 </body> |
| 108 </html> |