Scott Wiersdorf > Template-Trivial-0.08 > Template::Trivial

Download:
Template-Trivial-0.08.tar.gz

Dependencies

Annotate this POD (1)

CPAN RT

New  2
Open  0
View/Report Bugs
Module Version: 0.08   Source  

NAME ^

Template::Trivial - Simple (yet powerful) and fast substitution templates

SYNOPSIS ^

  use Template::Trivial;

  my $tmpl = new Template::Trivial( templates => '/path/to/templates' );
  $tmpl->define( main => 'main.tmpl',
                 list => 'list.tmpl' );
  $tmpl->define_from_string( item => '<li>{ITEM}' );

  for $i ( 1 .. 3 ) {
      $tmpl->assign( ITEM    => "Thingy $_" );
      $tmpl->parse( '.ITEMS' => 'item' );
  }

  $tmpl->parse(LIST => 'list' );
  $tmpl->parse(MAIN => 'main' );

  ## print out
  print $tmpl->to_string('MAIN');

DESCRIPTION ^

Template::Trivial is heavily inspired by the excellent and stable CGI::FastTemplate written by Jason Moore. We introduce a slightly modified syntax, fewer features, and a slight execution improvment over CGI::FastTemplate.

Philosophy

The design goals of Template::Trivial were:

Quick Start

For those wanting to dig in, here is an absolute barebones reference. The rest of the document is just details.

That's Template::Trivial in a nutshell. Here is a complete example:

Write some templates and put them in files:

main.tmpl
    <html>
    {HEAD}
    {BODY}
    </html>
head.tmpl
    <head>
    <title>{TITLE}</title>
    </head>
body.tmpl
    <body>
    <h2>{TITLE}</h2>
    This is a {TEST}.
    </body>

Now, write the program to use the templates:

    use Template::Trivial;

    my $tmpl = new Template::Trivial;
    $tmpl->define( main => 'main.tmpl',
                   head => 'head.tmpl',
                   body => 'body.tmpl' );
    $tmpl->assign(TITLE => "This is the title");
    $tmpl->assign(TEST  => "Testing 1 2 3...");
    $tmpl->parse(HEAD => 'head');
    $tmpl->parse(BODY => 'body');
    $tmpl->parse(MAIN => 'main');
    print $tmpl->to_string('MAIN');

That's it. Here's a play-by-play:

Core Methods

The following methods are specified in order of how they might appear in a real program (i.e., in the order you might use them).

new

Create a new template object.

    my $tmpl = new Template::Trivial;

new optionally takes the following arguments:

    strict => 0
    templates => '/path/to/templates'
templates

Tells the template object where to look for templates you define in from_file.

    $tmpl->templates('/path/to/templates');

This may also be set in the constructor. The default value is the empty string ''.

strict

Will emit a warning when any of the following conditions occur:

  - a template alias in 'define' does not match the lowercase regular
    expression pattern: /^[a-z][a-z0-9_-]*?$/
  - a file in a 'define' statement is not a regular file or character
    special device
  - a variable in 'assign' does not match the uppercase regular
    expression pattern: /^[A-Z][A-Z0-9_-]*?$/
  - a variable in 'assign_from_file' does not match the uppercase
    regular expression pattern: /^[A-Z][A-Z0-9_-]*?$/
  - a file in an 'assign_from_file' statement is not a regular file
    or character special device
  - a variable in 'append' does not match the uppercase regular
    expression pattern: /^[A-Z][A-Z0-9_-]*?$/
  - an undefined variable is encountered in a template during 'parse'
  - an undefined variable is encountered in 'to_string'

Example:

    $tmpl->strict(0);

The strict option may be set in the constructor. It defaults to '1'.

define

Defines a mapping of template aliases to filenames.

    $tmpl->define( main => 'main.tmpl',
                   head => '/usr/opt/tmpl/head.tmpl',
                   body => 'body.tmpl', );

The path specified by templates will be prepended to the filenames specified in define, except when the filename begins with a slash '/', in which case the absolute path will be used.

define_from_string

Defines a mapping of template names to the contents of a string.

    $tmpl->define_from_string( footer => "created on ${DATE}" );

This is a quick way for a programmer to make a template without writing one to file. Useful for testing or "locking away" parts of a template set. See "Philosophy".

assign

Assigns the specified string to the specified template variable.

    $tmpl->assign( FOO => 'this is foo' );

or using a "here" document:

    $tmpl->assign( FOO => <<_BLECH_ );
    This is a longer foo
    with multiple lines.
    _BLECH_

Subsequent assignments to the same template will override previous assignments.

You can make multiple assignments in one call:

    $tmpl->assign( FOO => 'foo string',
                   BAR => 'bar string' );

You can also append a string to an existing variable by prepending a dot to the variable:

    $tmpl->assign('.FOO' => ' and more foo');

but this is accomplished more cleanly with the append method (below). This usage is deprecated and is included chiefly for CGI::FastTemplate compatibility (and partly for nostalgia).

assign_from_file

Assigns the contents of a specified file to the specified variable. Paths are relative to the value of the templates method. from_file may be used multiple times, or may take several list arguments:

    $tmpl->assign_from_file( FOO => 'foo.txt',
                             BAR => 'bar.txt' );

is the same as:

    $tmpl->assign_from_file( FOO => 'foo.txt' );
    $tmpl->assign_from_file( BAR => 'bar.txt' );

If the filename begins with a slash, the value of templates will not be prepended:

    $tmpl->assign_from_file( MAH => '/path/to/mah.txt' );
parse

Parses the specified template and saves its results in the specified variable.

    $tmpl->parse( MAIN => 'main' );

Multiple variable/alias pairs may be specified:

    $tmpl->parse( JOE => 'joe',
                  BOB => 'bob_file');

but the templates are not guaranteed to be parsed in the order specified. Because of this, you should not put codependent templates in the same parse statement.

to_string

Returns the contents of a template variable as a string. Useful for assignment or printing.

    print $tmpl->to_string('FOO');

That concludes this example.

TO DO ^

We'd like to be as complete as CGI::FastTemplate sometime, but we wanted to get this out the door. Here are some features to look for around Q1 or Q2 of 2004.

SEE ALSO ^

CGI::FastTemplate(3).

AUTHOR ^

Scott Wiersdorf, <scott@perlcode.org>

COPYRIGHT AND LICENSE ^

Copyright (C) 2007 by Scott Wiersdorf

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.

syntax highlighting: