changeset 38:336bc2f622e4 draft header-includes

Preliminary revisions to some draft documentation.
author David Barts <n5jrn@me.com>
date Tue, 28 May 2019 20:17:10 -0700
parents ce67eac10fc7
children ee19984ba31d
files pspx.html
diffstat 1 files changed, 29 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- a/pspx.html	Tue May 28 17:08:36 2019 -0700
+++ b/pspx.html	Tue May 28 20:17:10 2019 -0700
@@ -37,6 +37,11 @@
       <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>#load</code></dt>
+      <dd>Load the specified Chameleon template file and make the loaded
+        template available as a template variable. Useful for importing and
+        invoking macros. See the section on this directive below for more
+        information.</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
@@ -74,6 +79,30 @@
     <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>
+    <h3>Loading Templates</h3>
+    <p>The <code>#load</code> directive may be used to load additional
+      templates, e.g. ones containing macro definitions. Note that the loaded
+      files are standard Chameleon templates and <em>not</em> TinCan <code>.pspx</code>
+      files (i.e. they cannot contain any header directives); as such, loaded
+      files must have the standard <var>.pt</var> extension for Chameleon
+      template files.</p>
+    <p>In the normal case, typing <code>#load foo.pt</code> will load a file
+      relative to the same directory as the page containing the <code>#load</code>
+      directive itself. The loaded template object will be made available as a
+      template variable matching the file name sans extension (in this case, <samp>foo</samp>).
+      One can change the name of the variable created by prefixing the file
+      specification with a variable name followed by an equals sign,
+      e.g. <code>#load t=foo.pt</code>. If one places the specification inside
+      angle brackets (e.g. <code>#load &lt;t=foo.pt&gt;</code>), loaded files
+      are searched for in <code>WEB-INF/tlib</code> instead.</p>
+    <p>Finally, as is allowed for all arguments to header directives, one may
+      enclose the argument to #load inside single or double quotes and use the
+      normal Python backslash escaping.</p>
+    <h3>Using Loaded Macros</h3>
+    <p>Once a template has been loaded, it will be available as a sub-attribute
+      of the <var>macros</var> attribute of the associated template object.
+      E.g.:</p>
+    <pre>#load foo.pt<br>&lt;!DOCTYPE html&gt;<br>&lt;html&gt;<br>  &lt;head&gt;<br>    &lt;title&gt;Macro Example&lt;/title&gt;<br>  &lt;/head&gt;&lt;body&gt;<br>    &lt;p metal:use-macro="foo.macros.bar"&gt;&lt;/p&gt;<br>  &lt;/body&gt;<br>&lt;/html&gt;</pre>
     <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