Web Site Templates

Build Script

We use ttree to generate the pages in the web site. This is a standard tool distributed with the Template Toolkit. For simplicity, we have a bin/build script which runs ttree for us, providing it with the name of our configuration file (etc/ttree.cfg) because we're lazy and don't want to have to type it out each time.

You can pass any of the regular ttree options to the build script.

    $ bin/build                # build any pages that have changed
    $ bin/build -a             # build all pages regardless
    $ bin/build index.html     # build the index.html page
      

Directories

The src directory contains the source templates for each page in the site. The lib directory contains other library templates used in the site (e.g. header, footer, menu, etc). The html directory is where the processed template output gets written to, ready to be served by our web server. We also have an images directory for all our images. There's a symbolic link to the images directory from the html directory.

Master Templates

A number of master templates control the whole process. The config/main template (i.e. the lib/config/main file) is defined as a PRE_PROCESS template (via the pre_process option in the etc/ttree.cfg configuration file). This goes on to process a bunch of other config/* templates which perform various configuration tasks. Of particular interest is the config/page template which generates a page data structure containing information relevant to the current page template.

    [% # main configuration template which is processed before each page 
       # template (it's defined as the pre_process option in etc/ttree.cfg)
       #
       # add any site-wide configuration items/actions here 
    
       USE Date;
    
       PROCESS config/debug
             + config/root
             + config/site
             + config/page
             + config/url
             + config/style
             + config/macros;
    
    -%]
     

The site/wrapper template is defined as a WRAPPER template via the wrapper option in the etc/ttree.cfg configuration file. This uses the value of the page.type variable (set in the config/page template we mentioned above) to Do The Right Thing to apply any further filters, wrappers, or other actions required for the page type.

    [% # main site wrapper which applies the right filters, wrappers and
       # other template magic to the processed template output
    
       SWITCH page.type;
    
         CASE 'text';
           # pass text-based pages (e.g. css, js) through unaltered
           debug_msg('text page: passing through');
           content;
    
         CASE 'shtml';
           # HTML pages get the page layout wrapper and the standard HTML blurb
           debug_msg('SHTML page: applying standard page layout');
           FILTER redirect(template.name.replace('\.shtml$', '.html'));
           content WRAPPER site/html 
                         + site/layout; 
           END;
           content;
    
         CASE 'xml';
           # XML pages get transmogrified into HTML and get treated as above
           debug_msg('XML page: transmogrifying into HTML');
           # generate .html page                                             
           FILTER redirect(template.name.replace('\.xml$', '.html'));        
           content WRAPPER site/html
                         + site/layout
                         + site/xmlpage;
           END;
    
    
           # pass through XML content to .xml page                           
           content;
    
    
    
         CASE;
           THROW page "Invalid page type: $page.type";
    
       END;
    
       # now generate the source page
       PROCESS site/source FILTER redirect("source/$template.name");
    
    -%]
    
     

For example, a CSS or Javascript page would have page.type set to text. In this case, the template output (stored in the content variable) gets passed through unaltered. HTML pages (the default) get the site/html and site/layout wrapper templates applied to the template content. XML pages also get transmogrified using the site/xmlpage template.

Page Templates

The page templates live in the src directory. They can define various bits of useful metadata using the META tag. For example, the META tags are defined in this template like so:

    [% META title       = 'Web Site Templates'
            author      = 'Andy Wardley'
            description = 'Information about the templates used to generate this web site'
    -%]