Mercurial > cgi-bin > hgweb.cgi > tincan

<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8">
    <title>.pspx Template Files</title>
    <style type="text/css">
      .kbd { font-family: monospace; }
    </style>
  </head>
  <body>
    <h1>.pspx Template Files</h1>
    <h2>Introduction</h2>
    Files ending in a <span class="kbd">.pspx</span> 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>#errors</code></dt>
      <dd>Ignore other headers and make 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 <span class="kbd">TinCanError</span> 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>#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 <span class="kbd">.py</span>.</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 <span class="kbd">.pspx</span>.
        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>
    <h3>Error Pages</h3>
    <p>Error pages supersede the standard Bottle error handling, and are created
      by using the <code>#errors</code> page header. <em>Error pages have no
        associated code-behind;</em> they consist of templates only. Error page
      templates are provided with two variables when rendering:</p>
    <dl>
      <dt><code>e</code></dt>
      <dd>The <code>bottle.HTTPError</code> object associated with this error.</dd>
      <dt><code>request</code></dt>
      <dd>The <code>bottle.Request</code> object associated with this error.</dd>
    </dl>
    <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>
    <h2>The Body</h2>
    <p>The body begins with the first line that <em>does not</em> start with <code>#</code>
      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>
  </body>
</html>
author	David Barts <n5jrn@me.com>
date	Mon, 13 May 2019 12:38:26 -0700
parents	c6902cded64d
children	31bb8400e6e3