|
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">
|
|
|
7 .kbd { font-family: monospace; }
|
|
|
8 </style>
|
|
|
9 </head>
|
|
|
10 <body>
|
|
|
11 <h1>.pspx Template Files</h1>
|
|
|
12 <h2>Introduction</h2>
|
|
|
13 Files ending in a <span class="kbd">.pspx</span> extension define both
|
|
|
14 routes and templates. The files have two parts: a header and a body.<br>
|
|
|
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
|
|
|
22 languages where lines often start with <span class="kbd">#</span>, such
|
|
|
23 as Cheetah.</dd>
|
|
2
|
24 <dt><code>#errors</code></dt>
|
|
5
|
25 <dd>Ignore other headers and make this is an error page which handles the
|
|
|
26 specified HTTP error codes. See the subsection on error pages below. </dd>
|
|
2
|
27 <dt><code>#forward</code></dt>
|
|
|
28 <dd>Ignore everything else in this template (and any code-behind
|
|
|
29 associated with it), using the specified route to serve it instead. The
|
|
|
30 route specified with <code>#forward</code> may itself contain a <code>#forward</code>,
|
|
|
31 but attempts to create a <code>#forward</code> loop are not allowed and
|
|
|
32 will cause a <span class="kbd">TinCanError</span> to be raised. Note
|
|
|
33 that unlike calls to <code>app.forward()</code>, the <code>#forward</code>
|
|
|
34 header is resolved at route-creation time; no extra processing will
|
|
|
35 happen at request time.</dd>
|
|
|
36 <dt><code>#hidden</code></dt>
|
|
|
37 <dd>This is a hidden page; do not create a route for it. The page can only
|
|
|
38 be displayed by a forward.</dd>
|
|
|
39 <dt><code>#methods</code></dt>
|
|
5
|
40 <dd>A list of HTTP request methods, separated by whitespace, follows. The
|
|
|
41 route will allow all specified methods. Not specifying this line is
|
|
|
42 equivalent to specifying <code>#methods GET</code>.</dd>
|
|
2
|
43 <dt><code>#python</code></dt>
|
|
|
44 <dd>What follows is the name of the Python file containing the code-behind
|
|
|
45 for this route. If not specified, the code-behind will be in a file with
|
|
|
46 the same name but an extension of <span class="kbd">.py</span>.</dd>
|
|
|
47 <dt><code>#rem</code></dt>
|
|
|
48 <dd>The rest of the line is treated as a remark (comment) and is ignored.</dd>
|
|
|
49 <dt><code>#template</code></dt>
|
|
|
50 <dd>Ignore the body of this file and instead use the template in the body
|
|
3
|
51 of the specified file, which must end in <span class="kbd">.pspx</span>.
|
|
|
52 Any headers in the referred template file are ignored.</dd>
|
|
2
|
53 </dl>
|
|
|
54 <p>It is possible to include whitespace and special characters in arguments
|
|
|
55 to the <code>#forward</code>, <code>#python</code>, and <code>#template</code>
|
|
|
56 headers by using standard Python string quoting and escaping methods. For
|
|
|
57 example, <code>#python "space case.py"</code>.</p>
|
|
6
|
58 <p>Header directives that don't take arguments as a rule simply ignore them.
|
|
|
59 For example, <code>#end headers</code> has the same effect as <code>#end</code>.
|
|
2
|
60 <h3>Error Pages</h3>
|
|
|
61 <p>Error pages supersede the standard Bottle error handling, and are created
|
|
3
|
62 by using the <code>#errors</code> page header. <em>Error pages have no
|
|
2
|
63 associated code-behind;</em> they consist of templates only. Error page
|
|
|
64 templates are provided with two variables when rendering:</p>
|
|
|
65 <dl>
|
|
5
|
66 <dt><code>error</code></dt>
|
|
2
|
67 <dd>The <code>bottle.HTTPError</code> object associated with this error.</dd>
|
|
|
68 <dt><code>request</code></dt>
|
|
|
69 <dd>The <code>bottle.Request</code> object associated with this error.</dd>
|
|
|
70 </dl>
|
|
3
|
71 <p>The <code>#errors</code> directive takes a list of numeric error codes
|
|
5
|
72 (values from 400 to 599 are allowed); the page is created to handle the
|
|
|
73 specified errors. If no error codes are specified, the page will handle
|
|
|
74 all errors. The behavior of specifying multiple error pages for the same
|
|
|
75 error code is undefined; doing so is best avoided.</p>
|
|
2
|
76 <h2>The Body</h2>
|
|
|
77 <p>The body begins with the first line that <em>does not</em> start with <code>#</code>
|
|
|
78 and has the exact same syntax that the templates are in for this webapp.
|
|
|
79 By default, Chameleon templates are used. Cheetah, Jinja2, Mako, and
|
|
|
80 Bottle SimpleTemplate templates are also supported, provided the webapp
|
|
|
81 was launched to use them. (Only one template style per webapp is
|
|
|
82 supported.)</p>
|
|
|
83 <p>In order to make line numbers match file line numbers for reported
|
|
|
84 errors, the template engine will be passed a blank line for each header
|
|
|
85 line encountered. TinCan will strip out all leading blank lines when
|
|
|
86 rendering its responses.</p>
|
|
|
87 </body>
|
|
|
88 </html>
|
