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 bugs

COPYRIGHT (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

cpanm Bricklayer::Templater

perl -MCPAN -e shell
install Bricklayer::Templater