NAME

CGIBurn::TEMPLATES - A description of the template files used by CGIBurn.

INTRODUCTION

CGIBurn uses a slightly modified version of Jason Moore's (jmoore@sober.com) CGIBurn::FastTemplate library. It is modified to have support for sections, which make template files look more like regular HTML files.

Template files consist of a file with sections, delimited by

  <!-- SECTION: section_name -->

appearing at the beginning of a line. Perl code can display each section by calling

  $tpl->parse(".template_name/section_name")

. Variables which the Perl code sets with

  $tpl->assign(VAR1=>VAL1,VAR2=>VAL2,...)

can be accessed in the template as

  $VAR1 $VAR2 ...

Doing this allows (almost) no HTML code to be embedded in the Perl code, and for somebody who knows no Perl to edit the template files to change the look and feel of the entire package, without fear of breaking any functionality.

Unfortunately, this method of doing things is kinda rigid, and any new templates have to follow the same basic structure as the originals, since sections are always displayed in the same order. This may be fixed in the future; see FUTURE for ideas about fixing this.

There are a couple reasons I chose CGIBurn::FastTemplate over something more elaborate (like HTML::Mason). It is fast and straightforward. You don't have to put any Perl code in the template files, so it provides a clean separation between code and display. No Perl code in templates also means that you don't have to trust your Web designer, since they can't sneak out of the page and execute random Perl code. With my section modifications, template files are legal HTML, so they are easy to write in a Web designer's standard development tools (as long as they can pass along comments easily) (See HINTS for some hints on developing template pages). And when I was looking around for packages, HTML::Mason didn't work properly with Perl's tainting mechanism, which is one of the reasons I write CGI scripts in Perl. Future versions will (probably) provide more elaborate mechanisms for changing the look and feel, which will allow you to use whatever template system you want, so this will become less important.

TEMPLATES

The following components use templates; see their documentation (and the code to their template files) for information about variables and sections.

burn, viewjobs, jobcontrol, watchlog, index, setprogress.

HINTS

Template files are designed to look as much like regular HTML as possible. The special code that FastTemplate uses is either variables that start with a $, which your browser will just display normally, and stuff inside comments, which your browser will ignore.

If you have several mutually exclusive sections (only one of them will be displayed), you can hide one when viewing the template as regular HTML by putting on the first line of the section:

  <!-- $ENDCOMMENT

A Web browser will see the entire section as a comment (assuming there are no other comments in it), since the comment is never ended until the next SECTION command. FastTemplate will replace $ENDCOMMENT with the HTML end comment command, so after it processes the section, the first line will be commented out, but the rest of the block will be outside of the comments. By moving this command around to different sections, you can view what the page will look like when those sections are and aren't displayed.

The special section ignore (started by

  <!-- SECTION: ignore -->

will not be output at all by FastTemplate. That lets you put in additional table items or options besides the ones that will be used by the template, so you can see what it looks like as a standard HTML file.

FUTURE

While this template system is better than having HTML code scattered throughout multiple Perl files, it still leaves a lot to be desired in terms of flexibility. Since the Perl code knows ``set these variables, then display these sections of these templates in this order'', the structure has to be pretty much the same.

In the future, I hope to replace this system with a series of Perl modules for display. Each module will receive all of the information it needs about a particular page, and will be responsible for generating all of the HTML. It will use any templating system it wants (or none at all) internally.

I think that this is the ideal solution, since it gives people creating a new look and feel for CGIBurn a great deal of flexibility, while still allowing a clean separation between code and HTML.

RCS VERSION