Templator

31.01.2006 1:23

What is Templator?

Templator is a meta-templating engine. It is a simple Perl script (223 lines of code, of which roughly 23% are comments) that makes one or more (for example HTML) templates out of a meta-template. Basically what it does is that it substitutes a number of different sets of values for a number of variables in a single file and each time writes the result in a different file.

It is a surprisingly useful tool for example when you have a number of very different content management systems (for example: one program or CGI script for news, one for the Wiki, one for the photo gallery, video archive, feed aggregator, etc.) and you want all of them to have the same look. Unfortunately different programs usually use very different templating schemes: one program may want shell-like substitution variables in its templates, the second may want HTML::Template like syntax and the third something completely different. Without some kind of automatization the synchronization of all the different templates soon becomes a nightmare. If you aren't using a sophisticated all-in-one content management system that has some way of synchronizing templates for all of its internal parts a tool like the Templator is absolutely necessary.

If you are looking for Templator utility that is part of the HotelCalifornia XML to Java framework, you ended up on the wrong page. This has nothing to do with Java.

How to install it

Templator is a single Perl script. You can place it in any convenient corner of your file system.

You will need a recent version of Perl and HTML::Template.

How to configure it

Before you even attempt to use Templator, you must be familiar with the different template syntaxes that your software uses. You need this knowledge to make a working meta-template.

You should also be familiar with the HTML::Template mark-up. This is what Templator uses in its meta-template file.

Now you can start writing a meta-template and associated configuration. The easiest way is to start is by modifying the example configuration that is included in the distribution tarball.

Let's have a look at the directory tree of the example configuration:

example
|-- conf
|   |-- bash_template_with_header
|   |   |-- conf
|   |   |-- content
|   |   `-- vars
|   |-- perl_template_without_header
|   |   |-- conf
|   |   |-- content
|   |   `-- vars
|   |-- conf
|   `-- vars
`-- tmpl
    `-- main.tmpl

As you can see all configuration associated with a single meta-template is gathered in a single directory with two sub-directories: tmpl contains the meta-templates (in this case only one - main.tmpl). The meta-template contains a number of variables (<TMPL_VAR ...> tags) that get substituted with different values for each generated templates. Also some templates may contain only a part of the meta-template (because of the <TMPL_IF ...> tags). A typical use would be for example when some programs don't need the HTML header or have a template in form of two files: one for the part of the HTML before the content and one for the part after content.

conf directory contains two files with global configuration: conf file contains path to which all other paths in this configuration are relative (if you want to try out the example configuration, you will have to change these paths or Templator won't work). vars contains the default values of substitution variables. If specific configuration for each generated template doesn't specify the value of a substitution variable, then the value from this global configuration is used. If this variable has no default value defined, it remains undefined (it is substituted by a blank and interpreted as a boolean "false" in "if" tags).

conf directory also contains one directory for each generated template. Each template directory contains another pair of conf and vars files. These two define specific settings for this template: conf specifies the meta-template used and the file name of the output template while vars specifies the values of the substitution variables.

The syntax of these files is quite straightforward and should be obvious from the comments in the example configuration. If you are in doubt about something, don't be afraid to dig into the source. It is also well documented and quite simple.

How to run it

Run Templator without arguments to get a brief help on the recognized arguments.

An example session with example containing the example configuration described above and test being the output directory would look like this:

avian@orion:~/dev/templator$ ls
example  templator.pl  test
avian@orion:~/dev/templator$ pwd
/home/avian/dev/templator
avian@orion:~/dev/templator$ cat example/conf/conf
inputdir: /home/avian/dev/templator/example/tmpl
outputdir: /home/avian/dev/templator/test
avian@orion:~/dev/templator$ ./templator.pl example/conf
main.tmpl -> bash_with_header.txt
main.tmpl -> perl_without_header.txt
Finished
avian@orion:~/dev/templator$

Where to get it

Templator is available under the terms of the GNU General Public License from the following location:

https://www.tablix.org/~avian/templator

History lesson

Templator was originally written in a couple of moments of panic preceding the OpenOffice.org conference in September 2005. I was a part of the team that took care of the media coverage and was in charge of the software that would stand behind the main conference website. We knew that we will need a site that would be easily mirrored and must withstand a slashdot effect.

A dynamic web site was certainly out of the question however I could not find any integrated content management systems that would be capable of producing a set of static HTML pages. Besides, we needed at least a continuously updated page with conference news, a feed aggregator, photo gallery and a media archive.

Fortunately there is free software available for all of these tasks (except for the media archive, for which I developed my own solution. But that is a story to be told at another time). For news we used Nanoblogger, feed aggregator was the well known Planet and the photo gallery was handled by makethumbs. Our resident artist made a wonderful template for the page, but then a problem appeared:

These programs are written in a number of languages: from Bash to Perl and Python and each uses a different way to customize the look of the pages it makes. If I wanted our web page to look consistent, I would have to make a separate template for each program. For example Nanoblogger itself requires no less than 5 templates that use shell-style variables. On the other hand Planet uses the Perl HTML::Template syntax and makethumbs wants two separate files: one for the header and one for the footer.

Because time was running out I first made a separate template for each program by hand. That was quick and easy since I had a finished HTML dummy page available. However after the first few hours of the conference the various templates began to consume more and more of my time. Need a link for another sponsor on the right side of the page? No problem, just change 15 files by hand and then change them again, because you misspelled the URL.

Since I had other things to do than spend the next three days tweaking files by hand I wrote I horrible hack that was the first version of the Templator. It had no documentation and no error checking, but fortunately it reduced a previously twenty minutes long task of adding a new link to the sidebar to a 30 second vi session.

Since it worked so well for the OpenOffice.org conference, I rewrote the code a bit, added a some comments and began using it for other web sites that use an amalgam of different software. Current examples are the Tablix web site and Cyberpipe's video archive.