/ 
Text-Forge-2.15
River stage zero No dependents
/ Text::Forge

NAME

Text::Forge - templating system

SYNOPSIS

use Text::Forge;

my $forge = Text::Forge->new;
$forge->send('/path/to/template');

DESCRIPTION

This module uses templates to create dynamic documents. Templates are normal text files except they have a bit of special syntax that allows you to run perl code inside them.

Templating systems are most often used to create dynamic web pages, but can be used for anything.

Text::Forge has the following goals:

1. Simplicity

The template syntax is minimalistic, consistent, and easy to understand. The entire system is just a few hundred lines of code.

2. Familiarity

We use standard perl syntax wherever possible. There is no mini language to learn.

3. Efficiency

We support real-world, high traffic sites. Version 1.x has run Classmates.com for several years.

4. Extendability

OO design that can easily be subclassed and customized.

5. Specificity

It's a templating system, not a monolithic, all-encompassing framework. Everything that can be delegated to other modules, is.

Template Syntax

Templates are normal text files except for blocks which look like this:

<% %>

The type of block is determined by the character that follows the opening characters:

<%% %> code block 
<%  %> also a code block (any whitespace character)
<%$ %> interpolate string
<%= %> interpolate HTML escaped string
<%? %> interpolate URI escaped string

All blocks are evaluated within the same lexical scope (so my variables declared in one block are visible in subsequent blocks).

Templates are produced on standard output (there is a trap_send() method that let's you capture the output).

Code blocks contain straight perl code. Anything printed to standard output becomes part of the template output.

The string interpolation block evaluates its contents and inserts the result into the template.

The HTML escape block also does interpolation except the result is HTML escaped first. This is used heavily in web pages to prevent cross-site scripting vulnerabilities.

The URI escape block also does interpolation except the result is URI escaped first. You can use this to interpolate values within query strings, for example. Note that there's no need to HTML escape the result of this (the URI escaping also escapes all unsafe HTML characters).

Parts of the template that are outside a block are treated like a double-quoted string in Perl. Which means you can interpolate variables directly into the text if you like (although no escaping happens in this case, of course).

If a block is followed solely by whitespace up to the next newline, that whitespace (including the newline) will be suppressed from the output. If you really wanted a newline, just add another newline after the block. The idea here is that the blocks themselves shouldn't affect the formatting.

Generating Templates

To generate a template, you need to instantiate a Text::Forge object and tell it the template file to send:

my $tf = Text::Forge->new;
$tf->send('my_template');

Every template has access to a $forge object that provides some helpful methods and can be used to pass information around. Really, the $forge object is nothing more than a reference to the Text::Forge object being used to construct the template itself.

So, for example, assume that the 'my_template' file contains this:

<%
   # this is start of code block
   $forge->send_header;
%>
Hello World!

$forge is just a reference to the $tf object. The send_header() method is usually called implicitly when the first byte of output is seen, but here we're calling it explicitly for some unknown reason.

Since the Text::Forge class is subclassible, this mechanism makes it simple to provide a consistent context to all your templates. Suppose that you're making web pages and you want to use the CGI.pm module for handling form data. Subclass Text::Forge and add a cgi() method that returns the CGI.pm object. Now, every template can grab the CGI.pm object by calling $forge->cgi.

You can include a template within another template using the include() method. Here's how we might include a header in our main template.

<% $forge->include('header') %>

Templates are really just Perl subroutines, so you can pass values into them and they can pass values back.

<% my $rv = $forge->include('header', title => 'foo', meta => 'blurgle' ) %>

The send() method generates the template on standard output. If you want to capture the output in a variable, use the trap_send() method instead.

my $tf = Text::Forge->new;
my $doc = $tf->trap_send('my_template');

You can generate a template that's in a scalar (instead of an external file) by passing a reference to it.

my $tf = Text::Forge->new;
$tf->send(\"Hello Word <%= scalar localtime %>");

Error Handling

Exceptions are raised on error. We take pains to make sure the line numbers reported in errors and warnings match the line numbers in the templates themselves.

AUTHOR

Support is available through the Text::Forge source-forge site at http://text-forge.sourceforge.net/

Original code by Maurice Aubrey <maurice@hevanet.com>. Please use the source-forge mailing list to discuss this module.