Bricklayer::Templater - yet another templating system. Pure perl, highly flexible

Bricklayer-Templater documentation Contained in the Bricklayer-Templater distribution.

Index

Code Index:

NAME

Top

Bricklayer::Templater - yet another templating system. Pure perl, highly flexible with very few dependencies.

SYNOPSIS

Top

    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

Top

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

Top

    Jeremy A. Wall <Jeremy@MarzhillStudios.com>

BUGS

Top

    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>

Top

Bricklayer-Templater documentation Contained in the Bricklayer-Templater distribution. 
package Bricklayer::Templater;

use Bricklayer::Templater::Sequencer;
use Carp;


$VERSION='0.9.8';


sub new {
    do {carp($_[0]." Requires a working directory"); return; } unless defined $_[2];
    do {carp($_[0]." Requires a context"); return; } unless defined $_[1];
    my $obj = bless({App => $_[1], WD => $_[2]}, $_[0]);
    
    $obj->ext('txml');
    $obj->start_bracket('<');
    $obj->end_bracket('>');
    $obj->identifier('BK');
    return $obj;
}


sub load_template_file {
    my $self = shift;
    my $filename = shift;
	my $extension = $self->ext();
	my $TemplateFile = $self->WD()."/templates/".$filename;
	$TemplateFile .= ".$extension";
	$TemplateFile =~ s/::/\//g; # use double colon to indicate template directory seperators
	my $TemplateObj;
	my $Template;
	carp("loading $TemplateFile");
    open( TEMPLATE, $TemplateFile )
	  or croak("Cannot open Template File: $TemplateFile ");
	
	while ( read( TEMPLATE, my $line, 1000 ) ) {
		$Template .= $line;
	}
	chomp $Template;
	close TEMPLATE;
	$self->_template($Template);
    return $Template;
}


sub run_templater {
	my $self = shift;
    my $filename = shift;
    my $Params = shift;
    $self->load_template_file($filename)
        or croak('Failed to loadi ['. $filename. '] template');
    $self->run_sequencer($self->_template, $Params);	
	return 1;
}


sub run_sequencer {
    my $self = shift;
	my $Template = shift;
	my $tagID = $self->identifier();
	my $Params = shift;
	my $handler_loc = $self->{WD};
	my $TemplateObj = Bricklayer::Templater::Sequencer->new_sequencer($Template, $tagID, $self->start_bracket, $self->end_bracket);
	my $ParsedPage = $TemplateObj->return_parsed($self, $Params, $handler_loc);
    return;
}


sub publish {
	my $self = shift;
    my $stuff = shift;
	$self->{_page} .= $stuff if defined $stuff;
} 


sub clear {
    $self = shift;
    $self->{_page} = undef;
}


sub start_bracket {
   my $self = shift;
   my $var = shift;
   $self->{start_bracket} = $var if $var;
   return $self->{start_bracket};
}


sub end_bracket {
   my $self = shift;
   my $var = shift;
   $self->{end_bracket} = $var if $var;
   return $self->{end_bracket};
}


sub ext {
   my $self = shift;
   my $var = shift;
   $self->{ext} = $var if $var;
   return $self->{ext};
}


sub identifier {
   my $self = shift;
   my $var = shift;
   $self->{identifier} = $var if $var;
   return $self->{identifier};
}


sub _template {
   my $self = shift;
   my $var = shift;
   $self->{template} = $var if $var;
   return $self->{template};
}


sub _page {
   my $self = shift;
   my $var = shift;
   $self->{_page} = $var if $var;
   return $self->{_page};
}


sub app {
	return $_[0]->{App};
}


sub WD {
	return $_[0]->{WD};	
}

return 1;