---
name: "Text::MicroMason::HTMLTemplate"
section: "3pm"
platform: "linux"
package: "libtext-micromason-perl"
version: "2.23-5"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Text::MicroMason::HTMLTemplate"
---

# Text::MicroMason::HTMLTemplate(3pm)

Alternate Syntax like HTML::Template

## NAME

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

## SYNOPSIS

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

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

Use the standard compile and execute methods to parse and evaluate templates:

```
  print $mason->compile( text=>$template )->( @%args );
  print $mason->execute( text=>$template, @args );
```

Or use HTML::Template's calling conventions:

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

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>
```

## DESCRIPTION

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

This class automatically includes the following other mixins: TemplateDir, HasParams, and StoreOne.

### 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:

- •

  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

- associate

  Optional reference to a CGI parameter object or other object with a similar **param()** method.

- loop\_global\_vars (HTML::Template's "global\_vars")

  If set to true, don't hide external parameters inside a loop scope.

- loop\_context\_vars

  If set to true, defines additional variables within each \<TMPL\_LOOP\>: \_\_counter\_\_, which specifies the row index, and four boolean flags, \_\_odd\_\_, \_\_first\_\_, \_\_inner\_\_, and \_\_last\_\_.

### 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. Similar to the **param()** method provied by HTML::Template and the CGI module.

- **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.

- assemble\_tmpl\_\*()

  These methods define the mapping from the template tags to the equivalent Perl code.

- **filter()**

  Used to implement the escape option for tmpl\_var.

## SEE ALSO

The interface being emulated is described in HTML::Template.

For an overview of this templating framework, see Text::MicroMason.

This is a mixin class intended for use with Text::MicroMason::Base.

For distribution, installation, support, copyright and license  information, see Text::MicroMason::Docs::ReadMe.