Web Site Templates

admin/templates.shtml

    [% META title       = 'Web Site Templates'
            author      = 'Andy Wardley'
            description = 'Information about the templates used to generate this web site'
    -%]
    
    <h2>Build Script</h2>
    
    <p>
      We use <code>ttree</code> to generate the pages in the web site.
      This is a standard tool distributed with the Template Toolkit.  For
      simplicity, we have a <code>bin/build</code> script which runs
      <code>ttree</code> for us, providing it with the name of our
      configuration file (<code>etc/ttree.cfg</code>) because we're lazy and 
      don't want to have to type it out each time.
    </p>
    
    <p>
      You can pass any of the regular <code>ttree</code> options to the
      build script.
    </p>
    
    <div class="border">
     <h3 class="caption">Build Script Examples</h3>
      <pre>
    $ bin/build                # build any pages that have changed
    $ bin/build -a             # build all pages regardless
    $ bin/build index.html     # build the index.html page
      </pre>
    </div>
    
    
    <h2>Directories</h2>
    
    <p>
      The <code>src</code> directory contains the source templates for
      each page in the site.  The <code>lib</code> directory contains
      other library templates used in the site (e.g. header, footer, menu,
      etc).  The <code>html</code> directory is where the processed
      template output gets written to, ready to be served by our web
      server.  We also have an <code>images</code> directory for all our
      images.  There's a symbolic link to the <code>images</code>
      directory from the <code>html</code> directory.
    </p>
    
    
    <h2>Master Templates</h2>
    
    <p>
      A number of master templates control the whole process.  The
      <code>config/main</code> template (i.e. the
      <code>lib/config/main</code> file) is defined as a
      <b>PRE_PROCESS</b> template (via the <code>pre_process</code> option
      in the <code>etc/ttree.cfg</code> configuration file).  This goes on
      to process a bunch of other <code>config/*</code> templates which
      perform various configuration tasks.  Of particular interest is the
      <code>config/page</code> template which generates a
      <code>page</code> data structure containing information relevant to
      the current page template.
    </p>
    
    <div class="border">
     <h3 class="caption">config/main template</h3>
     <pre>
    [% INSERT config/main %]
     </pre>
    </div>
    
    <p>
      The <code>site/wrapper</code> template is defined as a
      <b>WRAPPER</b> template via the <code>wrapper</code> option in the
      <code>etc/ttree.cfg</code> configuration file.  This uses the value
      of the <code>page.type</code> variable (set in the
      <code>config/page</code> template we mentioned above) to Do The
      Right Thing to apply any further filters, wrappers, or other actions
      required for the page type.
    </p>
    
    <div class="border">
     <h3 class="caption">site/wrapper template</h3>
     <pre>
    [% INSERT site/wrapper %]
     </pre>
    </div>
    
    <p>
      For example, a CSS or Javascript page would have
      <code>page.type</code> set to <code>text</code>.  In this case, the
      template output (stored in the <code>content</code> variable) gets
      passed through unaltered.  HTML pages (the default) get the
      <code>site/html</code> and <code>site/layout</code> wrapper
      templates applied to the template content.  XML pages also get
      transmogrified using the <code>site/xmlpage</code> template.
    </p>
    
    
    
    <h2>Page Templates</h2>
    
    <p>
      The page templates live in the <code>src</code> directory.  They can
      define various bits of useful metadata using the <code>META</code>
      tag.  For example, the <code>META</code> tags are defined in this
      template like so:
    </p>
    
    [%- TAGS star -%]
    
    <div class="border">
     <h3 class="caption">Example page template</h3>
     <pre>
    [% META title       = 'Web Site Templates'
            author      = 'Andy Wardley'
            description = 'Information about the templates used to generate this web site'
    -%]
     </pre>
    </div>