Mercurial > cgi-bin > hgweb.cgi > tincan

diff pspx.html @ 2:ca6f8ca38cf2 draft

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Another backup commit.
author David Barts <n5jrn@me.com>
date Sun, 12 May 2019 22:51:34 -0700
parents
children c6902cded64d
line wrap: on
line diff
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/pspx.html	Sun May 12 22:51:34 2019 -0700
@@ -0,0 +1,80 @@
+<!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>This is an error page which handles the specified HTTP error codes.
+        The codes are specified in numeric form, separated by whitespace. If no
+        error codes are specified, this page handles all possible HTTP error
+        codes.</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>.</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>#error</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 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>