phpman > perldoc > HTML::Template::Expr(3pm)

NAME
    HTML::Template::Expr - HTML::Template extension adding expression support

SYNOPSIS
      use HTML::Template::Expr;

      my $template = HTML::Template::Expr->new(filename => 'foo.tmpl');
      $template->param(banana_count => 10);
      print $template->output();

DESCRIPTION
    This module provides an extension to HTML::Template which allows expressions in the template
    syntax. This is purely an addition - all the normal HTML::Template options, syntax and behaviors
    will still work. See HTML::Template for details.

    Expression support includes comparisons, math operations, string operations and a mechanism to
    allow you add your own functions at runtime. The basic syntax is:

       <TMPL_IF EXPR="banana_count > 10">
         I've got a lot of bananas.
       </TMPL_IF>

    This will output "I've got a lot of bananas" if you call:

       $template->param(banana_count => 100);

    In your script. <TMPL_VAR>s also work with expressions:

       I'd like to have <TMPL_VAR EXPR="banana_count * 2"> bananas.

    This will output "I'd like to have 200 bananas." with the same param() call as above.

MOTIVATION
    Some of you may wonder if I've been replaced by a pod person. Just for the record, I still think
    this sort of thing should be avoided. However, I realize that there are some situations where
    allowing the template author some programmatic leeway can be invaluable.

    If you don't like it, don't use this module. Keep using plain ol' HTML::Template - I know I
    will! However, if you find yourself needing a little programming in your template, for whatever
    reason, then this module may just save you from HTML::Mason.

BASIC SYNTAX
    Variables are unquoted alphanumeric strings with the same restrictions as variable names in
    HTML::Template. Their values are set through param(), just like normal HTML::Template variables.
    For example, these two lines are equivalent:

       <TMPL_VAR EXPR="foo">

       <TMPL_VAR NAME="foo">

    Numbers are unquoted strings of numbers and may have a single "." to indicate a floating point
    number. For example:

       <TMPL_VAR EXPR="10 + 20.5">

    String constants must be enclosed in quotes, single or double. For example:

       <TMPL_VAR EXPR="sprintf('%d', foo)">

    You can string together operators to produce complex booleans:

      <TMPL_IF EXPR="(foo || bar || baz || (bif && bing) || (bananas > 10))">
          I'm in a complex situation.
      </TMPL_IF>

    The parser is pretty simple, so you may need to use parenthesis to get the desired precedence.

COMPARISON
    Here's a list of supported comparison operators:

    *   Numeric Comparisons

        *   <

        *   >

        *   ==

        *   !=

        *   >=

        *   <=

        *   <=>

    *   String Comparisons

        *   gt

        *   lt

        *   eq

        *   ne

        *   ge

        *   le

        *   cmp

MATHEMATICS
    The basic operators are supported:

    *   +

    *   -

    *   *

    *   /

    *   %

    There are also some mathy functions. See the FUNCTIONS section below.

LOGIC
    Boolean logic is available:

    *   && (synonym: and)

    *   || (synonym: or)

FUNCTIONS
    The following functions are available to be used in expressions. See perldoc perlfunc for
    details.

    *   sprintf

    *   substr (2 and 3 arg versions only)

    *   lc

    *   lcfirst

    *   uc

    *   ucfirst

    *   length

    *   defined

    *   abs

    *   atan2

    *   cos

    *   exp

    *   hex

    *   int

    *   log

    *   oct

    *   rand

    *   sin

    *   sqrt

    *   srand

    All functions must be called using full parenthesis. For example, this is a syntax error:

       <TMPL_IF expr="defined foo">

    But this is good:

       <TMPL_IF expr="defined(foo)">

DEFINING NEW FUNCTIONS
    To define a new function, pass a "functions" option to new:

      $t = HTML::Template::Expr->new(filename => 'foo.tmpl',
                                     functions =>
                                       { func_name => \&func_handler });

    Or, you can use "register_function" class method to register the function globally:

      HTML::Template::Expr->register_function(func_name => \&func_handler);

    You provide a subroutine reference that will be called during output. It will receive as
    arguments the parameters specified in the template. For example, here's a function that checks
    if a directory exists:

      sub directory_exists {
        my $dir_name = shift;
        return 1 if -d $dir_name;
        return 0;
      }

    If you call HTML::Template::Expr->new() with a "functions" arg:

      $t = HTML::Template::Expr->new(filename => 'foo.tmpl',
                                     functions => {
                                        directory_exists => \&directory_exists
                                     });

    Then you can use it in your template:

      <tmpl_if expr="directory_exists('/home/sam')">

    This can be abused in ways that make my teeth hurt.

MOD_PERL TIP
    "register_function" class method can be called in mod_perl's startup.pl to define widely used
    common functions to HTML::Template::Expr. Add something like this to your startup.pl:

      use HTML::Template::Expr;

      HTML::Template::Expr->register_function(foozicate => sub { ... });
      HTML::Template::Expr->register_function(barify    => sub { ... });
      HTML::Template::Expr->register_function(baznate   => sub { ... });

    You might also want to pre-compile some commonly used templates and cache them. See
    HTML::Template's FAQ for instructions.

CAVEATS
    Currently the module forces the HTML::Template global_vars option to be set. This will hopefully
    go away in a future version, so if you need global_vars in your templates then you should set it
    explicitly.

    The module won't work with HTML::Template's file_cache or shared_cache modes, but normal memory
    caching should work. I hope to address this is a future version.

    The module is inefficient, both in parsing and evaluation. I'll be working on this for future
    versions and patches are always welcome.

BUGS
    I am aware of no bugs - if you find one, join the mailing list and tell us about it. You can
    join the HTML::Template mailing-list by visiting:

      http://lists.sourceforge.net/lists/listinfo/html-template-users

    Of course, you can still email me directly (sam AT tregar.com) with bugs, but I reserve the right
    to forward bug reports to the mailing list.

    When submitting bug reports, be sure to include full details, including the VERSION of the
    module, a test script and a test template demonstrating the problem!

CREDITS
    The following people have generously submitted bug reports, patches and ideas:

       Peter Leonard
       Tatsuhiko Miyagawa
       Don Brodale

    Thanks!

AUTHOR
    Sam Tregar <sam AT tregar.com>

LICENSE
    HTML::Template::Expr : HTML::Template extension adding expression support

    Copyright (C) 2001 Sam Tregar (sam AT tregar.com)

    This module is free software; you can redistribute it and/or modify it under the terms of
    either:

    a) the GNU General Public License as published by the Free Software Foundation; either version
    1, or (at your option) any later version, or

    b) the "Artistic License" which comes with this module.

    This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
    without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
    either the GNU General Public License or the Artistic License for more details.

    You should have received a copy of the Artistic License with this module, in the file ARTISTIC.
    If not, I'll be glad to provide one.

    You should have received a copy of the GNU General Public License along with this program; if
    not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
    02111-1307 USA