/ 
CAM-Template-0.76
River stage one • 3 direct dependents • 6 total dependents
/ CAM::Template

NAME

CAM::Template - Clotho-style search/replace HTML templates

SYNOPSIS

use CAM::Template;
my $tmpl = new CAM::Template($tmpldir . "/main_tmpl.html");
$tmpl->addParams(url => "http://foo.com/",
                 date => localtime(),
                 name => "Carol");
$tmpl->addParams(\%more_params);
$tmpl->setLoop("birthdaylist", name => "Eileen", date => "Sep 12");
$tmpl->addLoop("birthdaylist", name => "Chris",  date => "Oct 13");
$tmpl->addLoop("birthdaylist", [{name => "Dan",   date => "Feb 12"},
                                {name => "Scott", date => "Sep 24"}]);
print "Content-Type: text/html\n\n";
$tmpl->print();

DESCRIPTION

This package is intended to replace Clotho's traditional ::PARAM:: syntax with an object-oriented API. This syntax is overrideable by subclasses.

FUNCTIONS

patterns

This class method returns a series of regular expressions used for template searching and replacing. Modules which subclass CAM::Template can override this method to implement a different template syntax.

new
new FILENAME
new FILENAME, PARAMS

Create a new template object. You can specify the template filename and the replacement dictionary right away, or do it later via methods.

setFileCache 0|1

Indicate whether the template file should be cached in memory. Defaults to 1 (aka true). This can be used either on an object or globally:

my $tmpl = new CAM::Template();
$tmpl->setFileCache(0);

CAM::Template->setFileCache(0);

The global value only affects future template objects, not existing ones.

setIncludeFiles 0|1

Indicate whether the template file should be able to include other template files automatically via the

<!-- #include template="<filename>" -->

directive. Defaults to 1 (aka true). Note that this is recursive, so don't have a file include itself! This method can be used either on an object or globally:

my $tmpl = new CAM::Template();
$tmpl->setIncludeFiles(0);

CAM::Template->setIncludeFiles(0);

The global value only affects future template objects, not existing ones.

setFilename FILENAME

Specify the template file to be used. Returns false if the file does not exist or the object if it does. This loads and preparses the file.

setString STRING

Specify template content to be used. Use this instead of setFilename if you already have the contents in memory. This preparses the string.

addLoop LOOPNAME, HASHREF | KEY => VALUE, ...
addLoop LOOPNAME, ARRAYREF

Add to an iterating portion of the page. This extracts the <cam_loop> from the template, fills it with the specified parameters (and any previously specified with setParams() or addParams()), and appends to the LOOPNAME parameter in the params list.

If the ARRAYREF form of the method is used, it behaves as if you had done:

foreach my $row (@$ARRAYREF) {
   $tmpl->addLoop($LOOPNAME, $row);
}

so, the elements of the ARRAYREF are hashrefs representing a series of rows to be added.

clearLoop LOOPNAME

Blank the contents of the loop accumlator. This is really only useful for nested loops. For example:

foreach my $state (@states) {
   $template->clearLoop("cities");
   foreach my $city (@{$state->{cities}}) {
      $template->addLoop("cities", 
                         city => $city->{name},
                         pop => $city->{population});
   }
   $template->addLoop("state", state => $state->{name});
}
setLoop LOOPNAME, HASHREF | KEY => VALUE, ...

Exactly like addLoop above, except it clears the loop first. This is useful for the first element of a nested loop.

addParams [HASHREF | KEY => VALUE], ...

Specify the search/replace dictionary for the template. The arguments can either be key value pairs, or hash references (it is permitted to mix the two as of v0.71 of this library). For example:

my %hash = (name => "chris", age => 30);
$tmpl1->addParams(%hash);

my $hashref = \%hash;
$tmpl2->addParams($hashref);

Returns false if the hash has an uneven number of arguments, or the argument is not a hash reference. Returns the object otherwise.

Note: this appends to the parameter list. To replace the list, use the setParams method instead.

setParams HASHREF | KEY => VALUE, ...

Exactly like addParams above, except it clears the parameter list first.

toString

Executes the search/replace and returns the content.

print

Sends the replaced content to the currently selected output (usually STDOUT) or the supplied filehandle.

AUTHOR

Chris Dolan, Clotho Advanced Media, chris@clotho.com