Building a Complete Website using the Template Toolkit - Creating a Project Directory (Page 5 of 15 )
We’ll start by creating a directory for our web site, complete with subdirectories for the source templates for HTML pages (src), a library of reusable template components (lib), and the generated HTML pages (html). We’ll also create a directory for miscellaneous files (etc), including a configuration file for ttree, and another (bin) for any scripts we accrue to assist in building the site and performing maintenance tasks.
$ cd /home/dent
$ mkdir web
$ cd web
$ mkdir src lib html etc bin
ttree Configuration File
Now we need to define a configuration file for ttree. Example 2-10 shows an example of a typical etc/ttree.cfg file.
Example 2-10. etc/ttree.cfg
# directories
src = /home/dent/web/src
lib = /home/dent/web/lib
dest = /home/dent/web/html
# copy images and other binary files
copy = \.(png|gif|jpg)$
# ignore CVS, RCS, and Emacs temporary files
ignore = \b(CVS|RCS)\b
ignore = ^#
# misc options
verbose
recurse
Options can appear in any order in the configuration file. In certain cases (such as lib, copy, and ignore), an option can be repeated any number of times.
The first section defines the three important template directories:
# directories
src = /home/dent/web/src
lib = /home/dent/web/lib
dest = /home/dent/web/html
The src option tells ttree where to look for HTML page templates. The lib option (of which there can be many) tells it where the library of additional template compo nents can be found. Finally, the dest option specifies the destination directory for the generated HTML pages.
The next two sections provide regular expressions that ttree uses to identify files that should be copied rather than processed through the Template Toolkit ( copy ), and to identify files that should be ignored altogether ( ignore ):
# copy images and other binary files
copy = \.(png|gif|jpg)$
# ignore CVS, RCS, and Emacs temporary files
ignore = \b(CVS|RCS)\b
ignore = ^#
In this example, we’re setting the options so that any images with png, gif, or jpg file extensions are copied, and any CVS or temporary files left lying around by our favorite text editor are ignored.
The next section sets two ttree flags:
# misc options
verbose
recurse
The verbose flag causes ttree to print additional information to STDERR about what it’s doing, while it’s doing it. The recurse flag tells it to recurse down into any subdirectories under the src directory.
Running ttree for the First Time
When you run ttree for the first time, it will display the following prompt, which asks if you’d like it to create a default .ttreerc file:
Do you want me to create a sample '.ttreerc' file for you? (file: /home/dent/.ttreerc) [y/n]:
Answer y to have it create the file in your home directory.
This file is used to provide a default configuration for ttree. If you’ve got only one web site to maintain, you can copy the contents of the etc/ttree.cfg file into it and run ttree without any command-line options:
$ ttree
If you’ve got more than one site to maintain, you’ll probably want to keep separate configuration files for each. In that case, you can use the -f command-line option to provide the name of the configuration file when you invoke ttree:
$ ttree -f /home/dent/web/etc/ttree.cfg
Using a Build Script
Rather than providing a command-line configuration option for ttree each time you use it, you may prefer to write a simple build script that does it for you (as in Example 2-11).
Example 2-11. bin/build
ttree -f /home/dent/web/etc/ttree.cfg $@
The $@ at the end of the line passes any command-line arguments on to the ttree program, in addition to the -f option that is provided explicitly.
ttree Confguration Directory
Another alternative is to set the cfg option in the .ttreerc file to denote a default directory for ttree configuration files. You could set this to point to the project directory:
cfg = /home/dent/web/etc
and then invoke ttree with the short name of the configuration file:
$ tpage -f ttree.cfg
If you have many different web sites to maintain, another option is to create one general directory for ttree configuration files and use symbolic links from this directory to the project-specific files. The .ttree directory in your home directory is a common choice. In the .ttreerc file, we specify it like so:
cfg = /home/dent/.ttree
Then we prepare the directory, creating a symbolic link to our project-specific configuration file. We give it a memorable name (e.g., dentweb ) to distinguish it from the various other ttree.cfg files that we may create links to from this directory:
$ cd /home/dent
$ mkdir .ttree
$ cd .ttree
$ ln -s /home/dent/web/etc/ttree.cfg dentweb
With these changes in place, ttree can then be invoked using the -f option to specify the dentweb configuration file:
$ tpage -f dentweb
The settings in the .ttreerc file and the magic of symbolic links result in ttree ending up with the right configuration file without us having to specify the full path to it every time. The other benefit of this approach is that ttree can be invoked from any directory and the correct configuration file will still be located.
Calling ttree Through the Build Script
From now on we’ll assume that the bin/build script invokes ttree with the appropri ate option to locate the configuration file. For the sake of clarity, we’ll use it in the examples that follow whenever we want to build the site content, rather than calling ttree directly. Any other commands that you want performed when the site is built (e.g., copying files, restarting the web server or database) can also be added here.
As we saw in Example 2-11, any command-line options that we provide to the script are forwarded to ttree. One particularly useful option is
-h , which provides a helpful summary of all the different ttree options:
$ bin/build - h
ttree 2.63 (Template Toolkit version 2.10)
usage: ttree [options] [files]
Options:
-a (--all) Process all files, regardless of modification
-r (--recurse) Recurse into sub-directories
-p (--preserve) Preserve file ownership and permission
-n (--nothing) Do nothing, just print summary (enables -v)
-v (--verbose) Verbose mode
-h (--help) This help
-dbg (--debug) Debug mode
-s DIR (--src=DIR) Source directory
-d DIR (--dest=DIR) Destination directory
-c DIR (--cfg=DIR) Location of configuration files
-l DIR (--lib=DIR) Library directory (INCLUDE_PATH) (multiple)
-f FILE (--file=FILE) Read named configuration file (multiple)
File search specifications (all may appear multiple times):
--ignore=REGEX Ignore files matching REGEX
--copy=REGEX Copy files matching REGEX
--accept=REGEX Process only files matching REGEX
Additional options to set Template Toolkit configuration items:
--define var=value Define template variable
--interpolate Interpolate '$var' references in text
--anycase Accept directive keywords in any case.
--pre_chomp Chomp leading whitespace
--post_chomp Chomp trailing whitespace
--trim Trim blank lines around template blocks
--eval_perl Evaluate [% PERL %] ... [% END %] code blocks
--load_perl Load regular Perl modules via USE directive
--pre_process=TEMPLATE Process TEMPLATE before each main template
--post_process=TEMPLATE Process TEMPLATE after each main template
--process=TEMPLATE Process TEMPLATE instead of main template
--wrapper=TEMPLATE Process TEMPLATE wrapper around main template
--default=TEMPLATE Use TEMPLATE as default
--error=TEMPLATE Use TEMPLATE to handle errors
--start_tag=STRING STRING defines start of directive tag
--end_tag=STRING STRING defined end of directive tag
--tag_style=STYLE Use pre-defined tag STYLE
--plugin_base=PACKAGE Base PACKAGE for plugins
--compile_ext=STRING File extension for compiled template files
--compile_dir=DIR Directory for compiled template files
--perl5lib=DIR Specify additional Perl library directories
/ 29 
