What is a template?

  Hello $NAME.  How are you?

When are templates useful?

There are other templating modules on CPAN, what makes FastTemplate different?

Speed

FastTemplate doesn't use eval, and parses with a single regular expression. It just does simple variable interpolation (i.e. there is no logic that you can add to templates - you keep the logic in the code). That's why it's has 'Fast' in it's name!

Efficiency

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

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)

What are the steps to use FastTemplate?

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

These are outlined in detail in CORE METHODS below.

define(HASH)

    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().

define_nofile(HASH) alias: define_raw(HASH)

    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.

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

assign(HASH)

    e.g.

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

assign(HASH REF)

    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"

    $tpl->clear_href();    ## remove all hash ref assignments

    $tpl->assign(\%foo);   ## TITLE resolves to "king kong"
    $tpl->assign(\%bar);   ## TITLE _still_ resolves to "king kong"

parse(HASH)

    $tpl->parse(MAIN => "main");                ## regular

    $tpl->parse(MAIN => ["table", "main"]);     ## compound

    $tpl->parse(MAIN => ".row");                ## append

In the regular version, the template named "main" is loaded if it hasn't been already, all the variables are interpolated, and the result is then stored in FastTemplate as the value MAIN. If the variable '$MAIN' shows up in a later template, it will be interpolated to be the value of the parsed "main" template. This allows you to easily nest templates, which brings us to the compound style.

The compound style is designed to make it easier to nest templates. The following are equivalent:

    $tpl->parse(MAIN => "table");      
    $tpl->parse(MAIN => "main");

    ## is the same as:

    $tpl->parse(MAIN => ["table", "main"]);     ## this form saves function calls
                                                ## (and makes your code cleaner)

It is important to note that when you are using the compound form, each template after the first, must contain the variable that you are parsing the results into. In the above example, 'main' must contain the variable '$MAIN', as that is where the parsed results of 'table' is stored. If 'main' does not contain the variable '$MAIN' then the parsed results of 'table' will be lost.

The append style is a bit of a kludge, but it allows you to append the parsed results to the target variable. This is most useful when building tables that have an dynamic number of rows - such as data from a database query.

strict()

   [CGI::FastTemplate] Warning: no value found for variable: SOME_VARIABLE

Also, new as of version 1.04 the variables will be left in the output document. This was done for two reasons: to allow for parsing to be done in stages (i.e. multiple passes), and to make it easier to identify undefined variables since they appear in the parsed output. If you have been using an earlier version of FastTemplate and you want the old behavior of replacing unknown variables with an empty string, see: no_strict().

Note: version 1.07 adds support for two styles of variables, so that the following are equivalent: $VAR and ${VAR} However, when using strict(), variables with curly brackets that are not resolved are outputted as plain variables. e.g. if ${VAR} has no value assigned to it, it would appear in the output as $VAR. This is a slight inconsistency -- ideally the unresolved variable would remain unchanged.

Note: STDERR output should be captured and logged by the webserver so you can just tail the error log to see the output.

    e.g.

    tail -f /etc/httpd/logs/error_log

no_strict()

   CGI::FastTemplate::no_strict;        ## no 
   
   my $tpl = CGI::FastTemplate;
   $tpl->no_strict;                     ## yes

print(SCALAR)

    e.g.

    $tpl->parse(MAIN => "main");
    $tpl->print();         ## prints value of MAIN
    $tpl->print("MAIN");   ## same

This method is provided for convenience.

If you need to print other than STDOUT (e.g. socket, file handle) see fetch().

fetch(SCALAR)

    $tpl->parse(CONTENT   => "main");
    my $content = $tpl->fetch("CONTENT");   

    print $$content;        ## print to STDOUT
    print FILE $$content;   ## print to filehandle or pipe

clear()

Clears the internal hash that stores data passed from calls to assign() and parse().

Often clear() is at the end of a mod_perl script:

    $tpl->print();
    $tpl->clear();

clear(ARRAY)

  e.g. 

  $tpl->assign(TITLE => "Welcome"); 
  $tpl->clear("TITLE");                 ## title is now empty

Another way of achieving the same effect of clearnign variables is to just assign an empty string.

  e.g.

  $tpl->assign(TITLE => '');           ## same as: $tpl->clear("TITLE");

clear_parse()

clear_href(NUMBER)

    $tpl->assign(HASH REF);

If called with no arguments, it removes all hash references from the array. This is often used for database queries where each row from the query is a hash or hash reference.

e.g.

    while($hash_row = $sth->fetchrow_hashref)
    {
        $tpl->assign($hash_row);
        $tpl->parse(ROW => ".row");
        $tpl->clear_href(1);
    }

clear_define()

    $tpl->define();

Note: The hash that holds the loaded templates is not touched with this method. See: clear_tpl

clear_tpl() clear_tpl(NAME)

clear_all()

    $tpl->clear_define();
    $tpl->clear_href();
    $tpl->clear_tpl();
    $tpl->clear_parse();

Variables

    $[A-Z0-9][A-Z0-9_]+

This means, that a variable must begin with a dollar sign '$'. The second character must be an uppercase letter or digit 'A-Z0-9'. Remaining characters can include an underscore.

As of version 1.07 variables can also be delimited by curly brackets.

    ${[A-Z0-9][A-Z0-9_]+}

For example, the following are valid variables:

    $FOO
    $F123F
    $TOP_OF_PAGE
    ${NEW_STYLE}

Variable Interpolation (Template Parsing)

If a variable cannot be resolved to a value then there are two possibilities. If strict() has been called (it is on by default) then the variable remains and a warning is printed to STDERR. If no_strict() has been called then the variables is converted to an empty string [''].

See strict() and no_strict() for more info.

Some examples will make this clearer.

    Assume:

    $FOO = "foo";
    $BAR = "bar";
    $ONE = "1";
    $TWO = "2";   
    $UND = "_";
   
    Variable        Interpolated/Parsed
    ------------------------------------------------
    $FOO            foo   
    $FOO-$BAR       foo-bar
    $ONE_$TWO       2             ## $ONE_ is undefined!
    $ONE_$TWO       $ONE_2        ## assume: strict()
    $ONE$UND$TWO    1_2           ## kludge!
    ${ONE}_$TWO     1_2           ## much better
    $$FOO           $foo
    $25,000         $25,000

FULL EXAMPLE

Below are the templates. (Pretend each one is in a separate file.)

  <!-- NAME: main.tpl -->
  <html>
  <head><title>$TITLE</title>
  </head>
  <body>
  $MAIN
  </body>
  </html>
  <!-- END: main.tpl -->
 
 
  <!-- NAME: table.tpl -->
  <table>
  $ROWS
  </table>
  <!-- END: table.tpl -->
 
 
  <!-- NAME: row.tpl -->
  <tr>
  <td>$NUMBER</td>
  <td>$BIG_NUMBER</td>
  </tr>
  <!-- END: row.tpl -->

Now we can start coding...

  ## START ##

  use CGI::FastTemplate;
  my $tpl = new CGI::FastTemplate("/path/to/template/files");
 
  $tpl->define(     main    => "main.tpl",
                    table   => "table.tpl",
                    row     => "row.tpl",
                    );

  $tpl->assign(TITLE => "FastTemplate Test");

  for $n (1..3) 
  {
        $tpl->assign(   NUMBER      => $n,   
        BIG_NUMBER   => $n*10);
        $tpl->parse(ROWS   => ".row"); 
  }

  $tpl->parse(MAIN => ["table", "main"]); 
  $tpl->print();

  ## END ##
 
  When run it returns:

  <!-- NAME: main.tpl -->
  <html>
  <head><title>FastTemplate Test</title>
  </head>
  <body>
  <!-- NAME: table.tpl -->
  <table>
  <!-- NAME: row.tpl -->
  <tr>
  <td>1</td>
  <td>10</td>
  </tr>
  <!-- END: row.tpl -->
  <!-- NAME: row.tpl -->
  <tr>
  <td>2</td>
  <td>20</td>
  </tr>
  <!-- END: row.tpl -->
  <!-- NAME: row.tpl -->
  <tr>
  <td>3</td>
  <td>30</td>
  </tr>
  <!-- END: row.tpl -->
  
  </table>
  <!-- END: table.tpl -->

  </body>
  </html>
  <!-- END: main.tpl -->

If you're thinking you could have done the same thing in a few lines of plain perl, well yes you probably could. But, how would a graphic designer tweak the resulting HTML? How would you have a designer editing the HTML while you're editing another part of the code? How would you save the output to a file, or pipe it to another application (e.g. sendmail)? How would you make your application multi-lingual? How would you build an application that has options for high graphics, or text-only? FastTemplate really starts to shine when you are building mid to large scale web applications, simply because it begins to separate the application's generic logic from the specific implementation.