annotate pspx.html @ 31:443a0001d841 draft header-includes

Improve the #include syntax a bit.
author David Barts <n5jrn@me.com>
date Mon, 27 May 2019 15:17:25 -0700
parents 8037bad7d5a8
children 336bc2f622e4
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">
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
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>
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
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>
5
31bb8400e6e3 Add #end header, fix #errors.
David Barts <n5jrn@me.com>
parents: 3
diff changeset
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
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
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
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
28 <dt><code>#forward</code></dt>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
29 <dd>Ignore everything else in this template (and any code-behind
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
30 associated with it), using the specified route to serve it instead. The
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
31 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
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
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
37 <dt><code>#hidden</code></dt>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
38 <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
39 be displayed by a forward.</dd>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
40 <dt><code>#methods</code></dt>
5
31bb8400e6e3 Add #end header, fix #errors.
David Barts <n5jrn@me.com>
parents: 3
diff changeset
41 <dd>A list of HTTP request methods, separated by whitespace, follows. The
31bb8400e6e3 Add #end header, fix #errors.
David Barts <n5jrn@me.com>
parents: 3
diff changeset
42 route will allow all specified methods. Not specifying this line is
31bb8400e6e3 Add #end header, fix #errors.
David Barts <n5jrn@me.com>
parents: 3
diff changeset
43 equivalent to specifying <code>#methods GET</code>.</dd>
2
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
44 <dt><code>#python</code></dt>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
45 <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
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
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
48 <dt><code>#rem</code></dt>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
49 <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
50 <dt><code>#template</code></dt>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
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
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
54 </dl>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
55 <p>It is possible to include whitespace and special characters in arguments
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
56 to the <code>#forward</code>, <code>#python</code>, and <code>#template</code>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
57 headers by using standard Python string quoting and escaping methods. For
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
58 example, <code>#python "space case.py"</code>.</p>
6
a3823da7bb45 Minor tweaks.
David Barts <n5jrn@me.com>
parents: 5
diff changeset
59 <p>Header directives that don't take arguments as a rule simply ignore them.
a3823da7bb45 Minor tweaks.
David Barts <n5jrn@me.com>
parents: 5
diff changeset
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
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
62 <h3>Error Pages</h3>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
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
c6902cded64d Corrections and reorg.
David Barts <n5jrn@me.com>
parents: 2
diff changeset
68 <p>The <code>#errors</code> directive takes a list of numeric error codes
5
31bb8400e6e3 Add #end header, fix #errors.
David Barts <n5jrn@me.com>
parents: 3
diff changeset
69 (values from 400 to 599 are allowed); the page is created to handle the
31bb8400e6e3 Add #end header, fix #errors.
David Barts <n5jrn@me.com>
parents: 3
diff changeset
70 specified errors. If no error codes are specified, the page will handle
31bb8400e6e3 Add #end header, fix #errors.
David Barts <n5jrn@me.com>
parents: 3
diff changeset
71 all errors. The behavior of specifying multiple error pages for the same
31bb8400e6e3 Add #end header, fix #errors.
David Barts <n5jrn@me.com>
parents: 3
diff changeset
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
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
77 <h2>The Body</h2>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
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
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
84 supported.)</p>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
85 <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
86 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
87 line encountered. TinCan will strip out all leading blank lines when
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
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
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
110 </body>
ca6f8ca38cf2 Another backup commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
111 </html>