annotate pspx.html @ 3:c6902cded64d draft

Corrections and reorg.
author David Barts <n5jrn@me.com>
date Mon, 13 May 2019 06:53:08 -0700
parents ca6f8ca38cf2
children 31bb8400e6e3
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
2
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
1 <!DOCTYPE html>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
2 <html>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
3 <head>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
4 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
5 <title>.pspx Template Files</title>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
6 <style type="text/css">
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
7 .kbd { font-family: monospace; }
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
8 </style>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
9 </head>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
10 <body>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
11 <h1>.pspx Template Files</h1>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
12 <h2>Introduction</h2>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
13 Files ending in a <span class="kbd">.pspx</span> extension define both
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
14 routes and templates. The files have two parts: a header and a body.<br>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
15 <h2>The Header</h2>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
16 <p>The header is optional and consists of lines starting with an octothorpe
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
17 (#) character. With the exception of the <code>#rem </code>header, all
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
18 header lines may appear only once in a given file.</p>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
19 <dl>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
20 <dt><code>#errors</code></dt>
3
c6902cded64d Corrections and reorg.
David Barts <n5jrn@me.com>
parents: 2
diff changeset
21 <dd>Ignore other headers and make this is an error page which handles
c6902cded64d Corrections and reorg.
David Barts <n5jrn@me.com>
parents: 2
diff changeset
22 the specified HTTP error codes. See the subsection on error pages below.
c6902cded64d Corrections and reorg.
David Barts <n5jrn@me.com>
parents: 2
diff changeset
23 </dd>
2
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
24 <dt><code>#forward</code></dt>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
25 <dd>Ignore everything else in this template (and any code-behind
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
26 associated with it), using the specified route to serve it instead. The
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
27 route specified with <code>#forward</code> may itself contain a <code>#forward</code>,
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
28 but attempts to create a <code>#forward</code> loop are not allowed and
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
29 will cause a <span class="kbd">TinCanError</span> to be raised. Note
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
30 that unlike calls to <code>app.forward()</code>, the <code>#forward</code>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
31 header is resolved at route-creation time; no extra processing will
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
32 happen at request time.</dd>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
33 <dt><code>#hidden</code></dt>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
34 <dd>This is a hidden page; do not create a route for it. The page can only
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
35 be displayed by a forward.</dd>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
36 <dt><code>#methods</code></dt>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
37 <dd>A list of HTTP request methods, separated by whitespace, follows. The route will
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
38 allow all specified methods. Not specifying this line is equivalent to
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
39 specifying <code>#methods GET</code>.</dd>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
40 <dt><code>#python</code></dt>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
41 <dd>What follows is the name of the Python file containing the code-behind
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
42 for this route. If not specified, the code-behind will be in a file with
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
43 the same name but an extension of <span class="kbd">.py</span>.</dd>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
44 <dt><code>#rem</code></dt>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
45 <dd>The rest of the line is treated as a remark (comment) and is ignored.</dd>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
46 <dt><code>#template</code></dt>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
47 <dd>Ignore the body of this file and instead use the template in the body
3
c6902cded64d Corrections and reorg.
David Barts <n5jrn@me.com>
parents: 2
diff changeset
48 of the specified file, which must end in <span class="kbd">.pspx</span>.
c6902cded64d Corrections and reorg.
David Barts <n5jrn@me.com>
parents: 2
diff changeset
49 Any headers in the referred template file are ignored.</dd>
2
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
50 </dl>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
51 <p>It is possible to include whitespace and special characters in arguments
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
52 to the <code>#forward</code>, <code>#python</code>, and <code>#template</code>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
53 headers by using standard Python string quoting and escaping methods. For
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
54 example, <code>#python "space case.py"</code>.</p>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
55 <h3>Error Pages</h3>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
56 <p>Error pages supersede the standard Bottle error handling, and are created
3
c6902cded64d Corrections and reorg.
David Barts <n5jrn@me.com>
parents: 2
diff changeset
57 by using the <code>#errors</code> page header. <em>Error pages have no
2
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
58 associated code-behind;</em> they consist of templates only. Error page
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
59 templates are provided with two variables when rendering:</p>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
60 <dl>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
61 <dt><code>e</code></dt>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
62 <dd>The <code>bottle.HTTPError</code> object associated with this error.</dd>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
63 <dt><code>request</code></dt>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
64 <dd>The <code>bottle.Request</code> object associated with this error.</dd>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
65 </dl>
3
c6902cded64d Corrections and reorg.
David Barts <n5jrn@me.com>
parents: 2
diff changeset
66 <p>The <code>#errors</code> directive takes a list of numeric error codes
c6902cded64d Corrections and reorg.
David Barts <n5jrn@me.com>
parents: 2
diff changeset
67 (values from 400 to 599 are allowed); the page is created to handle the
c6902cded64d Corrections and reorg.
David Barts <n5jrn@me.com>
parents: 2
diff changeset
68 specified errors. If no error codes are specified, the page will handle all
c6902cded64d Corrections and reorg.
David Barts <n5jrn@me.com>
parents: 2
diff changeset
69 errors. The behavior of specifying multiple error pages for the same error code
2
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
70 is undefined; doing so is best avoided.</p>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
71 <h2>The Body</h2>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
72 <p>The body begins with the first line that <em>does not</em> start with <code>#</code>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
73 and has the exact same syntax that the templates are in for this webapp.
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
74 By default, Chameleon templates are used. Cheetah, Jinja2, Mako, and
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
75 Bottle SimpleTemplate templates are also supported, provided the webapp
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
76 was launched to use them. (Only one template style per webapp is
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
77 supported.)</p>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
78 <p>In order to make line numbers match file line numbers for reported
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
79 errors, the template engine will be passed a blank line for each header
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
80 line encountered. TinCan will strip out all leading blank lines when
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
81 rendering its responses.</p>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
82 </body>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
83 </html>