view release on metacpan or  search on metacpan

FastTemplate.pm  view on Meta::CPAN

B<Efficiency>

FastTemplate functions accept and return references whenever possible, which saves
needless copying of arguments (hashes, scalars, etc).

B<Flexibility>

The API is robust and flexible, and allows you to build very complex HTML
documents or HTML interfaces.  It is 100% perl and works on Unix or NT.
Also, it isn't restricted to building HTML documents -- it could be used
to build any ascii based document (e.g. postscript, XML, email).

The similar modules on CPAN are: 

  Module          HTML::Template  (S/SA/SAMTREGAR/HTML-Template-0.04.tar.gz)
  Module          Taco::Template  (KWILLIAMS/Taco-0.04.tar.gz)
  Module          Text::BasicTemplate (D/DC/DCARRAWAY/Text-BasicTemplate-0.9.8.tar.gz)
  Module          Text::Template  (MJD/Text-Template-1.20.tar.gz)
  Module          HTML::Mason     (J/JS/JSWARTZ/HTML-Mason-0.5.1.tar.gz)


=head2 What are the steps to use FastTemplate?

The main steps are:

    1. define
    2. assign 
    3. parse
    4. print

These are outlined in detail in CORE METHODS below.

=head1 CORE METHODS

=head2 define(HASH)

The method define() maps a template filename to a (usually shorter) name. e.g.

    my $tpl = new FastTemplate();
    $tpl->define(   main   => "main.tpl",
                    footer   => "footer.tpl",
                    );

This new name is the name that you will use to refer to the templates.  Filenames
should not appear in any place other than a define().

(Note: This is a required step!  This may seem like an annoying extra
step when you are dealing with a trivial example like the one above,
but when you are dealing with dozens of templates, it is very handy to
refer to templates with names that are indepandant of filenames.)

TIP: Since define() does not actually load the templates, it is faster
and more legible to define all the templates with one call to define().

=head2 define_nofile(HASH)   alias: define_raw(HASH)

Sometimes it is desireable to not have to create a separate template file
for each template (though in the long run it is usually better to do so).
The method define_nofile() allows you to do this.  For example, if you
were writing a news tool where you wanted to bold an item if it was
"new" you could do something like the following:

    my $tpl = new FastTemplate();

    $tpl->define_nofile(    new   => '<b>$ITEM_NAME</b> <BR>',
                            old   => '$ITEM_NAME <BR>');

    if ($new)
    {
        $tpl->parse($ITEM   => "new");
    }
    else
    {
        $tpl->parse($ITEM   => "old");
    }

Of course, now you, the programmer has to update how new items are
displayed, whereas if it was in a template, you could offload that task
to someone else.


=head2 define_nofile(HASH REF)   alias: define_raw(HASH REF)

A more efficient way of passing your arguments than using a real hash.
Just pass in a hash reference instead of a real hash.


=head2 assign(HASH) 

The method assign() assigns values for variables.  In order for a variable
in a template to be interpolated it must be assigned.  There are two forms
which have some important differences.  The simple form, is to accept
a hash and copy all the key/value pairs into a hash in FastTemplate.
There is only one hash in FastTemplate, so assigning a value for the
same key will overwrite that key.

    e.g.

    $tpl->assign(TITLE   => "king kong");
    $tpl->assign(TITLE   => "godzilla");    ## overwrites "king kong"

=head2 assign(HASH REF)

A much more efficient way to pass in values is to pass in a hash
reference.  (This is particularly nice if you get back a hash or hash
reference from a database query.)  Passing a hash reference doesn't copy
the data, but simply keeps the reference in an array.  During parsing if
the value for a variable cannot be found in the main FastTemplate hash,
it starts to look through the array of hash references for the value.
As soon as it finds the value it stops.  It is important to remember to
remove hash references when they are no longer needed.

    e.g.

    my %foo = ("TITLE" => "king kong");
    my %bar = ("TITLE" => "godzilla");

    $tpl->assign(\%foo);   ## TITLE resolves to "king kong"
    $tpl->clear_href(1);   ## remove last hash ref assignment (\%foo)
    $tpl->assign(\%bar);   ## TITLE resolves to "godzilla"