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">
      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>#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>
    <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>
author	David Barts <n5jrn@me.com>
date	Wed, 15 May 2019 00:00:45 -0700
parents	75e375b1976a
children	336bc2f622e4