Mercurial > cgi-bin > hgweb.cgi > tincan

comparison pspx.html @ 9:75e375b1976a draft

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