Mercurial > cgi-bin > hgweb.cgi > tincan
annotate pspx.html @ 60:682cd33e564c draft
Documentation (incomplete).
| author | David Barts <n5jrn@me.com> |
|---|---|
| date | Sat, 08 Jun 2019 07:43:15 -0700 |
| parents | 336bc2f622e4 |
| children |
| rev | line source |
|---|---|
| 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"> | |
|
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 | 8 </style> |
| 9 </head> | |
| 10 <body> | |
| 11 <h1>.pspx Template Files</h1> | |
| 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 | 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> |
|
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 | 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 | 28 <dt><code>#forward</code></dt> |
| 29 <dd>Ignore everything else in this template (and any code-behind | |
| 30 associated with it), using the specified route to serve it instead. The | |
| 31 route specified with <code>#forward</code> may itself contain a <code>#forward</code>, | |
| 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 | 37 <dt><code>#hidden</code></dt> |
| 38 <dd>This is a hidden page; do not create a route for it. The page can only | |
| 39 be displayed by a forward.</dd> | |
|
38
336bc2f622e4
Preliminary revisions to some draft documentation.
David Barts <n5jrn@me.com>
parents:
11
diff
changeset
|
40 <dt><code>#load</code></dt> |
|
336bc2f622e4
Preliminary revisions to some draft documentation.
David Barts <n5jrn@me.com>
parents:
11
diff
changeset
|
41 <dd>Load the specified Chameleon template file and make the loaded |
|
336bc2f622e4
Preliminary revisions to some draft documentation.
David Barts <n5jrn@me.com>
parents:
11
diff
changeset
|
42 template available as a template variable. Useful for importing and |
|
336bc2f622e4
Preliminary revisions to some draft documentation.
David Barts <n5jrn@me.com>
parents:
11
diff
changeset
|
43 invoking macros. See the section on this directive below for more |
|
336bc2f622e4
Preliminary revisions to some draft documentation.
David Barts <n5jrn@me.com>
parents:
11
diff
changeset
|
44 information.</dd> |
| 2 | 45 <dt><code>#methods</code></dt> |
| 5 | 46 <dd>A list of HTTP request methods, separated by whitespace, follows. The |
| 47 route will allow all specified methods. Not specifying this line is | |
| 48 equivalent to specifying <code>#methods GET</code>.</dd> | |
| 2 | 49 <dt><code>#python</code></dt> |
| 50 <dd>What follows is the name of the Python file containing the code-behind | |
| 51 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
|
52 the same name but an extension of <var>.py</var>.</dd> |
| 2 | 53 <dt><code>#rem</code></dt> |
| 54 <dd>The rest of the line is treated as a remark (comment) and is ignored.</dd> | |
| 55 <dt><code>#template</code></dt> | |
| 56 <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
|
57 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
|
58 in the referred template file are ignored.</dd> |
| 2 | 59 </dl> |
| 60 <p>It is possible to include whitespace and special characters in arguments | |
| 61 to the <code>#forward</code>, <code>#python</code>, and <code>#template</code> | |
| 62 headers by using standard Python string quoting and escaping methods. For | |
| 63 example, <code>#python "space case.py"</code>.</p> | |
| 6 | 64 <p>Header directives that don't take arguments as a rule simply ignore them. |
| 65 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
|
66 </p> |
| 2 | 67 <h3>Error Pages</h3> |
| 68 <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
|
69 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
|
70 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
|
71 (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
|
72 normal routes created for them).</p> |
| 3 | 73 <p>The <code>#errors</code> directive takes a list of numeric error codes |
| 5 | 74 (values from 400 to 599 are allowed); the page is created to handle the |
| 75 specified errors. If no error codes are specified, the page will handle | |
| 76 all errors. The behavior of specifying multiple error pages for the same | |
| 77 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
|
78 <h3>Templates with No Code-Behind</h3> |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
79 <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
|
80 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
|
81 class as appropriate. </p> |
|
38
336bc2f622e4
Preliminary revisions to some draft documentation.
David Barts <n5jrn@me.com>
parents:
11
diff
changeset
|
82 <h3>Loading Templates</h3> |
|
336bc2f622e4
Preliminary revisions to some draft documentation.
David Barts <n5jrn@me.com>
parents:
11
diff
changeset
|
83 <p>The <code>#load</code> directive may be used to load additional |
|
336bc2f622e4
Preliminary revisions to some draft documentation.
David Barts <n5jrn@me.com>
parents:
11
diff
changeset
|
84 templates, e.g. ones containing macro definitions. Note that the loaded |
|
336bc2f622e4
Preliminary revisions to some draft documentation.
David Barts <n5jrn@me.com>
parents:
11
diff
changeset
|
85 files are standard Chameleon templates and <em>not</em> TinCan <code>.pspx</code> |
|
336bc2f622e4
Preliminary revisions to some draft documentation.
David Barts <n5jrn@me.com>
parents:
11
diff
changeset
|
86 files (i.e. they cannot contain any header directives); as such, loaded |
|
336bc2f622e4
Preliminary revisions to some draft documentation.
David Barts <n5jrn@me.com>
parents:
11
diff
changeset
|
87 files must have the standard <var>.pt</var> extension for Chameleon |
|
336bc2f622e4
Preliminary revisions to some draft documentation.
David Barts <n5jrn@me.com>
parents:
11
diff
changeset
|
88 template files.</p> |
|
336bc2f622e4
Preliminary revisions to some draft documentation.
David Barts <n5jrn@me.com>
parents:
11
diff
changeset
|
89 <p>In the normal case, typing <code>#load foo.pt</code> will load a file |
|
336bc2f622e4
Preliminary revisions to some draft documentation.
David Barts <n5jrn@me.com>
parents:
11
diff
changeset
|
90 relative to the same directory as the page containing the <code>#load</code> |
|
336bc2f622e4
Preliminary revisions to some draft documentation.
David Barts <n5jrn@me.com>
parents:
11
diff
changeset
|
91 directive itself. The loaded template object will be made available as a |
|
336bc2f622e4
Preliminary revisions to some draft documentation.
David Barts <n5jrn@me.com>
parents:
11
diff
changeset
|
92 template variable matching the file name sans extension (in this case, <samp>foo</samp>). |
|
336bc2f622e4
Preliminary revisions to some draft documentation.
David Barts <n5jrn@me.com>
parents:
11
diff
changeset
|
93 One can change the name of the variable created by prefixing the file |
|
336bc2f622e4
Preliminary revisions to some draft documentation.
David Barts <n5jrn@me.com>
parents:
11
diff
changeset
|
94 specification with a variable name followed by an equals sign, |
|
336bc2f622e4
Preliminary revisions to some draft documentation.
David Barts <n5jrn@me.com>
parents:
11
diff
changeset
|
95 e.g. <code>#load t=foo.pt</code>. If one places the specification inside |
|
336bc2f622e4
Preliminary revisions to some draft documentation.
David Barts <n5jrn@me.com>
parents:
11
diff
changeset
|
96 angle brackets (e.g. <code>#load <t=foo.pt></code>), loaded files |
|
336bc2f622e4
Preliminary revisions to some draft documentation.
David Barts <n5jrn@me.com>
parents:
11
diff
changeset
|
97 are searched for in <code>WEB-INF/tlib</code> instead.</p> |
|
336bc2f622e4
Preliminary revisions to some draft documentation.
David Barts <n5jrn@me.com>
parents:
11
diff
changeset
|
98 <p>Finally, as is allowed for all arguments to header directives, one may |
|
336bc2f622e4
Preliminary revisions to some draft documentation.
David Barts <n5jrn@me.com>
parents:
11
diff
changeset
|
99 enclose the argument to #load inside single or double quotes and use the |
|
336bc2f622e4
Preliminary revisions to some draft documentation.
David Barts <n5jrn@me.com>
parents:
11
diff
changeset
|
100 normal Python backslash escaping.</p> |
|
336bc2f622e4
Preliminary revisions to some draft documentation.
David Barts <n5jrn@me.com>
parents:
11
diff
changeset
|
101 <h3>Using Loaded Macros</h3> |
|
336bc2f622e4
Preliminary revisions to some draft documentation.
David Barts <n5jrn@me.com>
parents:
11
diff
changeset
|
102 <p>Once a template has been loaded, it will be available as a sub-attribute |
|
336bc2f622e4
Preliminary revisions to some draft documentation.
David Barts <n5jrn@me.com>
parents:
11
diff
changeset
|
103 of the <var>macros</var> attribute of the associated template object. |
|
336bc2f622e4
Preliminary revisions to some draft documentation.
David Barts <n5jrn@me.com>
parents:
11
diff
changeset
|
104 E.g.:</p> |
|
336bc2f622e4
Preliminary revisions to some draft documentation.
David Barts <n5jrn@me.com>
parents:
11
diff
changeset
|
105 <pre>#load foo.pt<br><!DOCTYPE html><br><html><br> <head><br> <title>Macro Example</title><br> </head><body><br> <p metal:use-macro="foo.macros.bar"></p><br> </body><br></html></pre> |
| 2 | 106 <h2>The Body</h2> |
| 107 <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
|
108 (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
|
109 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
|
110 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
|
111 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
|
112 webapp was launched to use them. (Only one template style per webapp is |
| 2 | 113 supported.)</p> |
| 114 <p>In order to make line numbers match file line numbers for reported | |
| 115 errors, the template engine will be passed a blank line for each header | |
| 116 line encountered. TinCan will strip out all leading blank lines when | |
| 117 rendering its responses.</p> | |
|
9
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
118 <h3>Default Template Variables</h3> |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
119 <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
|
120 <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
|
121 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
|
122 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
|
123 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
|
124 respectively.</p> |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
125 <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
|
126 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
|
127 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
|
128 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
|
129 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
|
130 <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
|
131 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
|
132 <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
|
133 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
|
134 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
|
135 if desired by overriding that method.</p> |
|
75e375b1976a
Error pages now can have code-behind.
David Barts <n5jrn@me.com>
parents:
6
diff
changeset
|
136 <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
|
137 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
|
138 <p></p> |
| 2 | 139 </body> |
| 140 </html> |