Mercurial > cgi-bin > hgweb.cgi > tincan

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/code_behind.html	Mon May 13 21:24:48 2019 -0700
@@ -0,0 +1,60 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta http-equiv="content-type" content="text/html; charset=UTF-8">
+    <title>Code-Behind Files</title>
+    <style type="text/css">
+      var { font-family: monospace; font-style: normal; }
+    </style>
+  </head>
+  <body>
+    <h1>Code-Behind Files</h1>
+    <h2>Introduction</h2>
+    <p> In the main webapp tree (i.e. not in <var>WEB-INF</var>), files ending
+      in a <var>.py</var> extension contain code-behind logic. By default, the
+      file names match while only the extensions differ; e.g. <var>foo.py</var>
+      will contain the code-behind logic associated with <var>foo.pspx</var>.
+      Use of the <code>#python</code> and/or <code>#template</code> header
+      directives will of course change this default association.</p>
+    <p>Pretty much anything can be in the code-behind files, with one
+      restriction. There must be one and only one instance of a subclass of
+      either <var>Page</var> (normal pages) or <var>ErrorPage</var> (error
+      pages).</p>
+    <h2>BasePage Objects</h2>
+    <p>Both <var>Page</var> and <var>ErrorPage</var> objects are subclasses of
+      <var>BasePage</var>, and share a similar structure. Creating class
+      instances is lightweight and doesn't do much. The main processing logic
+      happens in the <var>handle</var> method, which accepts no arguments. When
+      processing is complete, the <var>export</var> method is called to export
+      template variables; it should return a dictionary or dictionary-like
+      object.</p>
+    <p>Because the constructors of both <var>Page</var> and <var>ErrorPage</var>
+      are intended to be called by TinCan itself, they should not be overridden.
+      Override <var>handle</var> and if necessary <var>export</var>, and
+      define additional methods and instance variables to your heart's content.
+      Anything not callable that does not start with underscore will
+      automatically be available as a template variable by default.</p>
+    <p>Having no or multiple instances <var>Page</var> or <var>ErrorPage</var>
+      classes is an error and will cause the corresponding page to fail to
+      launch. Aside from this one restriction, you are free to import modules
+      and define classes as you see fit in the code-behind.</p>
+    <p>Note that it is not normally necessary to override the <var>export</var>
+      method; the default behavior as described in the <em>Default Template
+        Variables</em> section of the template documentation is normally
+      sufficient.</p>
+    <h2>Code-Behind is Optional</h2>
+    <p>If you define a template with no code-behind file, TinCan will use either
+      <var>Page</var> or <var>ErrorPage</var> as appropriate, which will
+      present the standard, minimal set of variables to your template.</p>
+    <h2>Code-Behind Files Are Not Standard Modules</h2>
+    <p>Code-behind files are compiled and loaded programmatically via low-level
+      Python library calls. The normal Python module subsystem and its cache is
+      not used. Directories in the tree served by a TinCan webapp are <em>not</em>
+      part of <var>sys.path</var>. Attempts by one code-behind file to <code>import</code>
+      another will fail.</p>
+    <p>If you have webapp-specific logic which is used in rendering multiple
+      pages, it belongs in <var>WEB-INF/lib</var>, which is automatically added
+      to <var>sys.path</var>; thus files therein are importable via the
+      standard mechanisms.</p>
+  </body>
+</html>