Mercurial > cgi-bin > hgweb.cgi > tincan
view pspx.html @ 69:c168aad7a731 draft
Fix template error reportage.
| author | David Barts <n5jrn@me.com> |
|---|---|
| date | Mon, 15 Jul 2019 08:13:51 -0700 |
| parents | 336bc2f622e4 |
| children |
line wrap: on
line source
<!DOCTYPE html> <html> <head> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> <title>.pspx Template Files</title> <style type="text/css"> var { font-family: monospace; font-style: normal; } </style> </head> <body> <h1>.pspx Template Files</h1> <h2>Introduction</h2> Files ending in a <var>.pspx</var> extension define both routes and templates. The files have two parts: a header and a body.<br> <h2>The Header</h2> <p>The header is optional and consists of lines starting with an octothorpe (#) character. With the exception of the <code>#rem </code>header, all header lines may appear only once in a given file.</p> <dl> <dt><code>#end</code></dt> <dd>Marks the last line of the headers. Since the end of the header lines is implicitly marked by the first line that does not start with <var>#</var>, this is needed only for templating languages where lines often start with <var>#</var>, such as Cheetah.</dd> <dt><code>#errors</code></dt> <dd>This is an error page which handles the specified HTTP error codes. See the subsection on error pages below. </dd> <dt><code>#forward</code></dt> <dd>Ignore everything else in this template (and any code-behind associated with it), using the specified route to serve it instead. The route specified with <code>#forward</code> may itself contain a <code>#forward</code>, but attempts to create a <code>#forward</code> loop are not allowed and will cause a <var>TinCanError</var> to be raised. Note that unlike calls to <code>app.forward()</code>, the <code>#forward</code> header is resolved at route-creation time; no extra processing will happen at request time.</dd> <dt><code>#hidden</code></dt> <dd>This is a hidden page; do not create a route for it. The page can only be displayed by a forward.</dd> <dt><code>#load</code></dt> <dd>Load the specified Chameleon template file and make the loaded template available as a template variable. Useful for importing and invoking macros. See the section on this directive below for more information.</dd> <dt><code>#methods</code></dt> <dd>A list of HTTP request methods, separated by whitespace, follows. The route will allow all specified methods. Not specifying this line is equivalent to specifying <code>#methods GET</code>.</dd> <dt><code>#python</code></dt> <dd>What follows is the name of the Python file containing the code-behind for this route. If not specified, the code-behind will be in a file with the same name but an extension of <var>.py</var>.</dd> <dt><code>#rem</code></dt> <dd>The rest of the line is treated as a remark (comment) and is ignored.</dd> <dt><code>#template</code></dt> <dd>Ignore the body of this file and instead use the template in the body of the specified file, which must end in <var>.pspx</var>. Any headers in the referred template file are ignored.</dd> </dl> <p>It is possible to include whitespace and special characters in arguments to the <code>#forward</code>, <code>#python</code>, and <code>#template</code> headers by using standard Python string quoting and escaping methods. For example, <code>#python "space case.py"</code>.</p> <p>Header directives that don't take arguments as a rule simply ignore them. For example, <code>#end headers</code> has the same effect as <code>#end</code>. </p> <h3>Error Pages</h3> <p>Error pages supersede the standard Bottle error handling, and are created by using the <code>#errors</code> page header. The <code>#hidden</code> and <code>#method</code> header directives are ignored in error pages (error pages are effectively hidden anyhow, by virtue of never having normal routes created for them).</p> <p>The <code>#errors</code> directive takes a list of numeric error codes (values from 400 to 599 are allowed); the page is created to handle the specified errors. If no error codes are specified, the page will handle all errors. The behavior of specifying multiple error pages for the same error code is undefined; doing so is best avoided.</p> <h3>Templates with No Code-Behind</h3> <p>Code-behind is optional for both normal and error page templates. If code-behind is not provided, TinCan will use the <var>Page</var> or <var>ErrorPage</var> class as appropriate. </p> <h3>Loading Templates</h3> <p>The <code>#load</code> directive may be used to load additional templates, e.g. ones containing macro definitions. Note that the loaded files are standard Chameleon templates and <em>not</em> TinCan <code>.pspx</code> files (i.e. they cannot contain any header directives); as such, loaded files must have the standard <var>.pt</var> extension for Chameleon template files.</p> <p>In the normal case, typing <code>#load foo.pt</code> will load a file relative to the same directory as the page containing the <code>#load</code> directive itself. The loaded template object will be made available as a template variable matching the file name sans extension (in this case, <samp>foo</samp>). One can change the name of the variable created by prefixing the file specification with a variable name followed by an equals sign, e.g. <code>#load t=foo.pt</code>. If one places the specification inside angle brackets (e.g. <code>#load <t=foo.pt></code>), loaded files are searched for in <code>WEB-INF/tlib</code> instead.</p> <p>Finally, as is allowed for all arguments to header directives, one may enclose the argument to #load inside single or double quotes and use the normal Python backslash escaping.</p> <h3>Using Loaded Macros</h3> <p>Once a template has been loaded, it will be available as a sub-attribute of the <var>macros</var> attribute of the associated template object. E.g.:</p> <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> <h2>The Body</h2> <p>The body begins with the first line that <em>does not</em> start with <code>#</code> (or the first line after the <code>#end</code> directive, whichever comes first) and has the exact same syntax that the templates are in for this webapp. By default, Chameleon templates are used. Cheetah, Jinja2, Mako, and Bottle SimpleTemplate templates are also supported, provided the webapp was launched to use them. (Only one template style per webapp is supported.)</p> <p>In order to make line numbers match file line numbers for reported errors, the template engine will be passed a blank line for each header line encountered. TinCan will strip out all leading blank lines when rendering its responses.</p> <h3>Default Template Variables</h3> <p>By default, regular pages will have a single template variable available: <var>page</var>, which refers to the <var>Page</var> class that contains the code-behind logic for this page. The pertinent <var>bottle.Request</var> and <var>bottle.Response</var> objects are available to normal, non-error pages as <var>page.request</var> and <var>page.response</var>, respectively.</p> <p>Error pages have their code-behind logic in an <var>ErrorPage</var> class. In addition to the standard <var>page</var> variable, error pages also have <var>request</var> and <var>error</var> variables available by default, which contain copies of the pertinent <var>bottle.Request</var> and <var>bottle.HTTPError</var> objects respectively.</p> <p>The default behavior of the <var>export</var> method (which exports instance variables to template variables) in both the <var>Page</var> and <var>ErrorPage</var> classes is to export, in addition to the default variables, every user-created instance attribute that is not callable and whose name does not start with an underscore. This behavior can be changed if desired by overriding that method.</p> <p>Note that if for some reason you create an instance variable named <var>page</var>, it will overwrite the standard template variable by the same name.</p> <p></p> </body> </html>