NAME

Text::MicroMason::HTMLTemplate - Alternate Syntax like HTML::Template

SYNOPSIS

HTML::Template provides a syntax to embed values into a text template:

    <TMPL_IF NAME="user_is_dave">
      I'm sorry <TMPLVAR NAME="name">, I'm afraid I can't do that right now.
    <TMPL_ELSE>
      <TMPL_IF NAME="daytime_is_morning">
        Good morning, <TMPLVAR NAME="name">!
      <TMPL_ELSE>
        Good afternoon, <TMPLVAR NAME="name">!
      </TMPL_IF>
    </TMPL_IF>

Instead of using this class directly, pass its name to be mixed in:

    use Text::MicroMason;
    my $mason = Text::MicroMason->new( -HTMLTemplate );

You can compile and execute templates using the standard MicroMason methods:

    print $mason->execute( file => 'simple.tmpl', %arguments );

    $coderef = $mason->compile( file => 'simple.tmpl' );
    print $coderef->( %arguments );

Or use HTML::Template's calling conventions:

    $template = Text::MicroMason->new( -HTMLTemplate, filename=>'simple.tmpl' );
    $template->param( %arguments );
    print $template->output();

DESCRIPTION

This mixin class overrides several methods to allow MicroMason to emulate the template syntax and some of the other features of HTML::Template.

Compatibility with HTML::Template

This is not a drop-in replacement for HTML::Template, as the implementation is quite different, but it should be able to process most existing templates without major changes.

This should allow current HTML::Template users to take advantage of MicroMason's one-time compilation feature, which in theory could be faster than HTML::Template's run-time interpretation. (No benchmarking yet.)

The following features of HTML::Template are not supported yet:

The loop_context_vars attribute (Add to assemble_tmpl_loop() method.)
Search path for files. (Candidate for separate mixin class or addition to TemplateDir.)
Many HTML::Template options are either unsupported or have different names and need to be mapped to equivalent sets of attributes. (Transform these in the new() method or croak if they're unsupported.)

The following features of HTML::Template will likely never be supported due to fundamental differences in implementation:

query() method

Contributed patches to more closely support the behavior of HTML::Template would be welcomed by the author.

Template Syntax

The following elements are recognized by the HTMLTemplate lexer:

literal_text
Anything not specifically parsed by the below rule is interpreted as literal text.
<TMPL_tagname>
A template tag with no attributes.
<TMPL_tagname varname>
A template tag with a name attribute.
<TMPL_tagname NAME=varname option=value ...>
A template tag with one or more attributes.
</TMPL_tagname>
A closing template tag.

The following tags are supported by the HTMLTemplate assembler:

tmpl_var: <tmpl_var name=... ( default=... ) ( escape=... ) >
tmpl_include: <tmpl_include name=... >
tmpl_if: <tmpl_if name=... > ... </tmpl_if>
tmpl_unless: <tmpl_unless name=...> ... </tmpl_unless>
tmpl_else: <tmpl_else>
tmpl_loop: <tmpl_loop name=...> ... </tmpl_loop>

Supported Attributes

global_vars: Don't hide external parameters inside a loop scope.

Public Methods

new()

Creates a new Mason object. If a filename parameter is supplied, the corresponding file is compiled.

param()

Gets and sets parameter arguments.

compile()

Caches a reference to the most-recently compiled subroutine in the Mason object.

output()

Executes the most-recently compiled template and returns the results.

Optionally accepts a filehandle to print the results to.

  $template->output( print_to => *STDOUT );

Private Methods

lex_token

  ( $type, $value ) = $mason->lex_token();

Lexer for <TMPL_x> tags.

Attempts to parse a token from the template text stored in the global $_ and returns a token type and value. Returns an empty list if unable to parse further due to an error.

parse_args()

Lexer for arguments within a tag.

assembler_rules()

Adds initialization for param() at the begining of each subroutine to be compiled.

assemble_tmpl_*()