Mercurial > cgi-bin > hgweb.cgi > tincan

<!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 can 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>
    <h3>Page Objects</h3>
    <p>These contain the code-behind for normal pages. When the <var>handle</var>
      method begins executing, they contain two instance variables: <var>request</var>
      (a <var>bottle.Request</var> object) and <var>response</var> (a <var>bottle.Response</var>
      object). </p>
    <h3>ErrorPage Objects</h3>
    <p>These contain the code-behind for error pages.&nbsp; When the <var>handle</var>
      method begins executing, they contain two instance variables: <var>request</var>
      (a <var>bottle.Request</var> object) and <var>error</var> (a <var>bottle.HTTPError</var>
      object). </p>
    <h3>The Application Context</h3>
    <p>There is no separate standard instance variable in either <var>Page</var>
      or <var>ErrorPage</var> that provides such, because it is available via
      <var> request.app</var>. See the Bottle documentation for more
      information.</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>
author	David Barts <n5jrn@me.com>
date	Tue, 21 May 2019 18:01:44 -0700
parents	8037bad7d5a8
children