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>#end</code></dt>
      <dd>Marks the last line of the headers. Needed only for templating
        languages where lines often start with <span class="kbd">#</span>, such
        as Cheetah.</dd>
      <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>
    <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>.
    <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>error</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 16:00:11 -0700
parents	a3823da7bb45
children	75e375b1976a