Mercurial > cgi-bin > hgweb.cgi > tincan

diff pspx.html @ 9:75e375b1976a draft

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Error pages now can have code-behind.
author David Barts <n5jrn@me.com>
date Mon, 13 May 2019 20:47:51 -0700
parents a3823da7bb45
children 8037bad7d5a8
line wrap: on
line diff
--- a/pspx.html	Mon May 13 16:27:05 2019 -0700
+++ b/pspx.html	Mon May 13 20:47:51 2019 -0700
@@ -4,14 +4,14 @@
     <meta http-equiv="content-type" content="text/html; charset=UTF-8">
     <title>.pspx Template Files</title>
     <style type="text/css">
-      .kbd { font-family: monospace; }
+      var { font-family: monospace; font-style: normal; }
     </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>
+    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
@@ -19,20 +19,19 @@
     <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>
+        languages where lines often start with <var>#</var>, 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>
+      <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 <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>
+        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>
@@ -43,13 +42,13 @@
       <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>
+        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 <span class="kbd">.pspx</span>.
-        Any headers in the referred template file are ignored.</dd>
+        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>
@@ -57,22 +56,22 @@
       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. <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>
+      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>
       and has the exact same syntax that the templates are in for this webapp.
@@ -84,5 +83,26 @@
       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>