• NAME
• SYNOPSIS
• DESCRIPTION
• FILE NAMES
• VARIABLE SUBSTITUTION
• CPP-STYLE DIRECTIVES
• EXPRESSIONS
• EXAMPLE
• PER-METHOD DOCUMENTATION
• SEE ALSO
• COPYRIGHT
• LICENSE
• AUTHOR

NAME

Text::CPPTemplate - CPP-Style Templates

SYNOPSIS

 use Text::CPPTemplate;

 my $templ = new Text::CPPTemplate('/var/web/templates','.html');

 print $templ->template({
        PAGE => 'index',
        ELEMENT => 'header',
        TITLE => 'Test'
 });

DESCRIPTION

CPPTemplate is a templating system using a CPP-style (C Pre-Processor) syntax. CPPTemplate is quite fast so that it can be used in online Applications such as CGI scripts to separate program the code from the HTML. CPPTemplate is not HTML specific, so it can be used for other applications. For performance reasons, the files containing the templates are read only once and are cached for further use. This is especially handy when working with long running scripts which use the same template over and over again. Apache mod_perl is such an environment.

An application can use a large number of templates. They could for example represent different parts of output generated by the aplication. Each template can contain variables and CPP style if-then-else structures. When the template gets activated, all the variables will get substituted and the if-then-else structures will get processed.

FILE NAMES

When you activate a template, you do not specify a file-name, but only variables. Based on the contents of some special variables, CPPTemplate will try to load an apropriate template file from disk. It tries to do this using a number of different file-names. The first one to exist will be used. A directory where the templates reside and a suffix have to be specified with the new method. The following list shows which variables cause CPPTemplate to look for which files:

• PAGE_ELEMENT (PAGE and ELEMENT are variables)
• ELEMENT
• PAGE
• default (as is, not a variable)

In addition, if THEME is specified, the template will be first searched in the subdirectory specified by that variable of the templates directory.

In the example given in SYNOPSIS, the following files will be opened in turn until one is found to exist (in the directory /var/web/templates): index_header.html, header.html, index.html and default.html.

VARIABLE SUBSTITUTION

Variables are marked ##var## in the templates. If no variable is found with that specified name, the ##var## text remains unchanged.

CPP-STYLE DIRECTIVES

``MiniCPP'' directives permit the selection of parts of the template based on some condition. The language is very very basic, it seems to be good-enough for most applications. The following directives are supported:

// comment

The whole line is removed from the output

#ifdef VAR

If variable VAR is defined, the following text will be selected.

#if expr

If the expression expr evaluates to true (see EXPRESSIONS), the following text will be selected. You can use substitutions in the expression with the syntax '##VAR##'.

#elif expr

If the previous #if (or #elif) expression was false, evaluate this expr and if true select the following text.

#else

If the previous #if (or #elif) expression was false, select the following text.

#endif

Ends an #ifdef or an #if.

Note that these elements can be nested.

The newlines will be removed unless two consecutive lines without MiniCPP directives are found. Spaces and tabs will be removed from the beginning and the end of each line. Use '\ ' (backslash space) to insert spaces at the beginning or the end of the line.

EXPRESSIONS

At the moment only the following expressions are supported (don't laugh :-))

A = B

If A is equal to B (the text), then the expression is true.

A ~ B

Match A against the regular expression (perl) B. True if it does match, false otherwise.

EXAMPLE

 <HR>
     <A href="##ADD_URL##">Add</A>
     <A href="##PREV_URL##">Prev</A>
     <A href="##NEXT_URL##">Next</A>
   </P>

PER-METHOD DOCUMENTATION

new($templates_dir, $suffix)

Create a new CPPTemplate object. $templates_dir is the directory where the templates are stored and $suffix is a text to append to the file-names.

template(\%vars)

Return a processed template. \%vars is a hashref containing the variables used for building the file-name, for the substitutions and the CPP-style directives.

SEE ALSO

Text::TagTemplate(3)

COPYRIGHT

Copyright (c) 2000 ETH Zurich, All rights reserved.

LICENSE

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.


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 the
GNU General Public License for more details.


You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

AUTHOR

David Schweikert <dws@ee.ethz.ch>,
Tobi Oetiker <tobi@oetiker.ch>