NAME
Bricklayer::Templater - yet another templating system. Pure perl, highly flexible with very few dependencies.
SYNOPSIS
use Bricklayer::Templater;
use Cwd;
my $cwd = cwd();
# create a new templater with a context object and a working directory
my $t = Bricklayer::Templater->new($context, $cwd);
# run the templater on a named template
$t->run_templater('name_of_template');
# retrieve the page after running templater on it.
my $page = $t->_page();DESCRIPTION
Bricklayer::Templater began as a way to make a simple easy to use flexible templating engine. It has evolved over time but still retains that flexibility, simplicity, and ease of use.
It is based on template tags and is completely configurable as far as how those tags are identified. The default is <BKtagname attrib="something" ></BKtagname> you can specify different start and end brackets and identifiers (the BK in the above tags)
Configuring Templater options
Changing start_bracket for the template objects tags $t->start_bracket('['); #default is <
Change the end_bracket for the template objects tags $t->end_bracket(']'); #default is >
Change the identifier for the templater objects tags $t->identifier('?'); #default is BK
Change the template extension $t->ext('tmpl'); #default is txml
There are two primary purposes for this configurability. One is to for aesthetic reasons, the other is for multipass templating. Multipass templating is possible by running the template once for one configuration of tags then again on the results with a different configuration of tags.
Running a Template
There are two ways you can run a template. The first and easiest is to call $t->run_templater('template_name'); This will look in your working directory for a template by that name and with the configured extension and then run it.
The template will be stored in $t->_page() or be published with the publish hook provided by you if you sub classed the engine.
The publish method.
There is one method you probably want to override if you subclass this engine. publish() This method will be called by handlers with their results. If you don't override it then the default is to append those results to the _page attribute of the template object.
The rest of the API
new
Initializes a Templater object. Requires a context and working directory as the first two arguments.
load_template_file
my $file = $t->load_template_file('template_name') loads a template file from the working directory there are two ways to specify the template name.
path/name syntax
$t->load_template_file('relative/path/template_name')
name::space syntax (perl like)
$t->load_template_file('name::space::template_name')
$t->run_templater($file, $params)
run_templater runs the sequencer on the text in $filename. The results of the template run will be stored wherever publish() puts it.
$t->run_sequencer($text, $params)
run_sequencer runs the sequencer on the text in $text. The results of the template run will be stored wherever publish() puts it.
publish
default publish callback. You'll probably be overriding this but if you don't then the handlers will use this method to store the result of the parsed page in the $templater->{_page} attribute.
clear
$t->clear() Clears the contents of _page() it's a convenience method. If you override the publish method you might want to override this one too if you need it.
start_bracket
sets and returns the start_bracket attribute for the templater template tags
end_bracket
sets and returns the end_bracket attribute for the templater template tags
ext
sets and returns the ext attribute for the templater otherwise known as the template file extension
identifier
sets and returns the identifier attribute for the templater otherwise known as the tag identifier
_template
sets and returns the _template attribute for the templater a sort of scratchpad that the templater uses to store templates
_page
sets and returns the _page attribute for the templater where the default publish callback stores the return
app
sets and returns the app attribute for the templater otherwise known as the context
WD
sets and returns the WD attribute for the templater otherwise known as the working directory
Authors
Jeremy A. Wall <Jeremy@MarzhillStudios.com>BUGS
Like any Module of sufficient complexity there are probably some things I missed.
See http://rt.cpan.org to report and view bugsCOPYRIGHT (C) Copyright 2007 Jeremy Wall <Jeremy@Marzhillstudios.com>
This program is free software you can redistribute it and/or modify it under the same terms as Perl itself.
See http://www.Perl.com/perl/misc/Artistic.html