Mercurial > cgi-bin > hgweb.cgi > tincan
comparison pspx.html @ 2:ca6f8ca38cf2 draft
Another backup commit.
| author | David Barts <n5jrn@me.com> |
|---|---|
| date | Sun, 12 May 2019 22:51:34 -0700 |
| parents | |
| children | c6902cded64d |
comparison
equal
deleted
inserted
replaced
| 1:94b36e721500 | 2:ca6f8ca38cf2 |
|---|---|
| 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> | |
| 20 <dt><code>#errors</code></dt> | |
| 21 <dd>This is an error page which handles the specified HTTP error codes. | |
| 22 The codes are specified in numeric form, separated by whitespace. If no | |
| 23 error codes are specified, this page handles all possible HTTP error | |
| 24 codes.</dd> | |
| 25 <dt><code>#forward</code></dt> | |
| 26 <dd>Ignore everything else in this template (and any code-behind | |
| 27 associated with it), using the specified route to serve it instead. The | |
| 28 route specified with <code>#forward</code> may itself contain a <code>#forward</code>, | |
| 29 but attempts to create a <code>#forward</code> loop are not allowed and | |
| 30 will cause a <span class="kbd">TinCanError</span> to be raised. Note | |
| 31 that unlike calls to <code>app.forward()</code>, the <code>#forward</code> | |
| 32 header is resolved at route-creation time; no extra processing will | |
| 33 happen at request time.</dd> | |
| 34 <dt><code>#hidden</code></dt> | |
| 35 <dd>This is a hidden page; do not create a route for it. The page can only | |
| 36 be displayed by a forward.</dd> | |
| 37 <dt><code>#methods</code></dt> | |
| 38 <dd>A list of HTTP request methods, separated by whitespace, follows. The route will | |
| 39 allow all specified methods. Not specifying this line is equivalent to | |
| 40 specifying <code>#methods GET</code>.</dd> | |
| 41 <dt><code>#python</code></dt> | |
| 42 <dd>What follows is the name of the Python file containing the code-behind | |
| 43 for this route. If not specified, the code-behind will be in a file with | |
| 44 the same name but an extension of <span class="kbd">.py</span>.</dd> | |
| 45 <dt><code>#rem</code></dt> | |
| 46 <dd>The rest of the line is treated as a remark (comment) and is ignored.</dd> | |
| 47 <dt><code>#template</code></dt> | |
| 48 <dd>Ignore the body of this file and instead use the template in the body | |
| 49 of the specified file, which must end in <span class="kbd">.pspx</span>.</dd> | |
| 50 </dl> | |
| 51 <p>It is possible to include whitespace and special characters in arguments | |
| 52 to the <code>#forward</code>, <code>#python</code>, and <code>#template</code> | |
| 53 headers by using standard Python string quoting and escaping methods. For | |
| 54 example, <code>#python "space case.py"</code>.</p> | |
| 55 <h3>Error Pages</h3> | |
| 56 <p>Error pages supersede the standard Bottle error handling, and are created | |
| 57 by using the <code>#error</code> page header. <em>Error pages have no | |
| 58 associated code-behind;</em> they consist of templates only. Error page | |
| 59 templates are provided with two variables when rendering:</p> | |
| 60 <dl> | |
| 61 <dt><code>e</code></dt> | |
| 62 <dd>The <code>bottle.HTTPError</code> object associated with this error.</dd> | |
| 63 <dt><code>request</code></dt> | |
| 64 <dd>The <code>bottle.Request</code> object associated with this error.</dd> | |
| 65 </dl> | |
| 66 <p>The behavior of specifying multiple error pages for the same error code | |
| 67 is undefined; doing so is best avoided.</p> | |
| 68 <h2>The Body</h2> | |
| 69 <p>The body begins with the first line that <em>does not</em> start with <code>#</code> | |
| 70 and has the exact same syntax that the templates are in for this webapp. | |
| 71 By default, Chameleon templates are used. Cheetah, Jinja2, Mako, and | |
| 72 Bottle SimpleTemplate templates are also supported, provided the webapp | |
| 73 was launched to use them. (Only one template style per webapp is | |
| 74 supported.)</p> | |
| 75 <p>In order to make line numbers match file line numbers for reported | |
| 76 errors, the template engine will be passed a blank line for each header | |
| 77 line encountered. TinCan will strip out all leading blank lines when | |
| 78 rendering its responses.</p> | |
| 79 </body> | |
| 80 </html> |