/ 
Template-TT2Site-0.21
River stage zero No dependents
/ Template::TT2Site

NAME

Template::TT2Site - Create standard web sites with the Template Toolkit

SYNOPSIS

$ mkdir NewSite
$ cd NewSite
$ tt2site setup
... make your pages ...
$ tt2site build
... point your browser at html/index.html ...

DESCRIPTION

Template::TT2Site is a framework to create web sites using the Template Toolkit.

The technical structure of the site is patterned after the method described in The Badger Book. The structure has been slightly simplified for ease of use, and a couple of neat features are added:

  • The resultant site is position independent, i.e., it only uses relative URLs to the extent possible. This makes it easy to build partial sites, and to relocate the contents.

  • The necessary means are provided to create multi-language sites, where each page gets a link to its translations.

  • The 'site.map' hash, required for site navigation, is created automatically using minimal, position independent, directions.

Structure

A TT2Site site is configured to take templates from two sources: from the local directory, and from the TT2SITE_LIB. The templates in the TT2SITE_LIB directory provide (almost) all the necessary information to create the site (except for the contents, of course), the library templates can be overruled locally to customize a particular site.

The library templates reside in the lib directory. Its major subdirectories are config (configuration data), page (page formatting), and util (utility functions).

For the time being, the contents of the files need to be taken as a guide how to write your own. Here is a short description of some files:

site/main

This file controls which other files from the site directory are taken into account.

site/config

The site data like title and subject. This file must be overridden with actual data.

site/images

The definition of images to be used with the util/image template function.

site/lang

The definition of the languages to be used by this site.

page/wrapper

This fike controls what templates are applied when processing user files.

page/html

This template provides the general HTML structure of the generated pages.

page/layout

This template defines the structure of the generated pages. It uses the familiar table approach with cells containing the logo, header, menu, contents, footer, and so on.

Getting Started

Template::TT2Site needs to be installed before it can be used. You can do this by unpacking the kit it in an arbitrary location, and issue the following commands:

perl Build.PL
Build
Build install

(To see what gets installed, and where, use the target fakeinstall instead of install).

Alternatively, you can use the CPAN or CPANPLUS tools to install tt2site for you.

Note that the last command requires write access to your local Perl installtion.

To set up a new TT2Site site, create a new directory. In this directory, issue the following command:

$ tt2site setup

This will populate the directory with the necessary files and directories to create the web site. You can now use the tt2site program with the following subcommands:

  • build (default)

    Run the ttree application to update all site data.

  • rebuild

    Run ttree to completely rebuild all site data.

  • clean

    Cleanup the generated data (and some other things, like editor backup files).

  • realclean

    Cleanup the generated data and the files originally installed with the setup. If you modified any of them, you'll lose your changes.

Almost for certain, you'll have to create in the lib directory, the templates config/site and config/images. If you want to make a multi-language site you need to create an appropriate config/lang. But in many cases this will be all you need to get started creating your web pages.

Most web sites use a menu to navigate. Template::TT2Site automatically creates the menu, using .map files placed in the directories to navigate. The avantage of .map files is that they can easily be maintained with the directory data, and directories can be moved to another location taking the map data with them.

The .map files contain lines as follows:

menu "Title" target

The target will appear in the menu as "Title". The target can be an HTML page (if the file target.html exists), a directory (if it exists, introducing a new level of navigation), otherwise it will be taken to be an arbitrary URL.

In addition, the top level .map must contain an entry

title "Menu Title"

Multi-language Sites

To create a multi-language site, specify the supported languages in the site.lang variable (file config/lang) using standard ISO codes for the languages, e.g.,

site.languages = [ 'en', 'nl' ]

Consult the supplied config/lang for details.

A multi-language site contains one top-level index.html, and sub-trees of information in directories named after the language code. When set up this way, each page, e.g., en/product/desc.html will be automatically linked to nl/product/desc.html, and vice versa.

EXAMPLE SITES

Two example sites are included in the distribution. sample0 is a simple site basically containing this documentation. sample1 is the same site in multi-language form. To use either site, change to the appropriate directory, and issue the commands:

$ tt2site setup
$ tt2site build
... point your browser at html/index.html ...
$ tt2site realclean

DEPENDENCIES

Template::TT2Site requires the following Perl modules, all available on CPAN:

  • Template::Toolkit, version 2.13 (preferrably 2.14) or later.

    Template::TT2Site uses the ttree tool, which is assumed to be available in your execution path as a Perl script.

  • AppConfig. This is used by the ttree tool.

BUGS AND PROBLEMS

This product is better than this documentation.

AUTHOR AND CREDITS

Johan Vromans (jvromans@squirrel.nl) wrote this software.

Many things were borrowed and adapted from the Template Toolkit materials and the Badger book.

Web site: http://www.squirrel.nl/people/jvromans/tt2site/index.html.

COPYRIGHT AND DISCLAIMER

This software is Copyright 2004 by Squirrel Consultancy. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of either: a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or b) the "Artistic License" which comes with Perl.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details.