Text::...mplate(3pm)

💖 NAME 💖

Say hi to Text::MicroMason::HTMLTemplate — it's the alternate syntax that gives you HTML::Template–style vibes. 🦋

(also, quick vibe check: this is a perl 3pm manual page from the User Contributed Perl Documentation, so yeah bestie you're in exactly the right place 💅)

✨ SYNOPSIS ✨

Lowkey important: don't use this class directly!! Pass its name to be mixed in instead. 🙈

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

Then you use the standard compile and execute methods to parse and evaluate templates:

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

Orrr you can use HTML::Template's calling conventions:

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

HTML::Template gives you a whole syntax for embedding values into a text template, and it looks like this:

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

(iconic template honestly, no notes 💀)

🌸 DESCRIPTION 🌸

So this mixin class overrides several methods so that MicroMason can emulate the template syntax of HTML::Template, plus some of its other features too. Main character energy, periodt. 👑

It also automatically includes these other mixins for you, no extra work required: TemplateDir, HasParams, and StoreOne. 🫶

💫 Compatibility with HTML::Template 💫

Heads up bestie: this is not a drop-in replacement for HTML::Template, because the implementation is quite different. But it should be able to process most existing templates without major changes. ✨

The whole point is that current HTML::Template users get 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 though, so don't quote me on that. 😭)

These HTML::Template features are not supported yet:

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

And these HTML::Template features will likely never be supported, because the implementations are just fundamentally different:

• query() method

Contributed patches to more closely support the behavior of HTML::Template would be welcomed by the author. (Be the change you wanna see in the world, fr fr. 🫶)

🦋 Template Syntax 🦋

Here's everything the HTMLTemplate lexer recognizes:

• literal_text — anything not specifically parsed by the rule below 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.

And here's the tag lineup the HTMLTemplate assembler supports:

• 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 — an optional reference to a CGI parameter object, or to any other object with a similar param() method.
• loop_global_vars (that's HTML::Template's "global_vars", iykyk) — if set to true, don't hide external parameters inside a loop scope.
• loop_context_vars — if set to true, it defines extra variables within each <TMPL_LOOP>: __counter__, which specifies the row index, plus four boolean flags: __odd__, __first__, __inner__, and __last__. Obsessed. 🌈

👑 Public Methods 👑

• new() — creates a new Mason object. If a filename parameter is supplied, the corresponding file gets compiled. ✨
• param() — gets and sets parameter arguments. Similar to the param() method provided by HTML::Template and the CGI module.
• output() — executes the most-recently compiled template and returns the results.

Optionally it 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.

It 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 it's 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.

---

and that's the whole page, bestie 💖 this was perl v5.36.0, dated 2023-08-10, straight outta the User Contributed Perl Documentation. slay, bye 🎀🦋✨