/ 
Text-MicroTemplate-Extended-0.17
River stage one • 4 direct dependents • 4 total dependents
/ Text::MicroTemplate::Extended

NAME

Text::MicroTemplate::Extended - Extended MicroTemplate

SYNOPSIS

use Text::MicroTemplate::Extended;

my $mt = Text::MicroTemplate::Extended->new(
    include_path  => ['/path/to/document_root'],
    template_args => { c => $c, stash => $c->stash, },
);

$mt->render('content'); # render file: /path/to/document_root/content.mt

DESCRIPTION

Text::MicroTemplate::Extended is an extended template engine based on Text::MicroTemplate::File.

EXTENDED FEATURES

Template inheritance

Most notable point of this extended module is Template inheritance. This concept is used in Python's Django framework.

Template inheritance allows you to build a base "skeleton" template that contains all the common elements of your site and defines blocks that child templates can override.

It's easiest to understand template inheritance by starting with an example:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <link rel="stylesheet" href="style.css" />
    <title><? block title => sub { ?>My amazing site<? } ?></title>
</head>

<body>
    <div id="sidebar">
        <? block sidebar => sub { ?>
        <ul>
            <li><a href="/">Home</a></li>
            <li><a href="/blog/">Blog</a></li>
        </ul>
        <? } ?>
    </div>

    <div id="content">
        <? block content => sub {} ?>
    </div>
</body>
</html>

This template, which we'll call base.mt, defines a simple HTML skeleton document that you might use for a simple two-column page. It's the job of "child" templates to fill the empty blocks with content.

In this example, the <? block ?> tag defines three blocks that child templates can fill in. All the block tag does is to tell the template engine that a child template may override those portions of the template.

A child template might look like this:

? extends 'base'

<? block title => sub { ?>My amazing blog<? } ?>

? block content => sub {
? for my $entry (@$blog_entries) {
    <h2><?= $entry->title ?></h2>
    <p><?= $entry->body ?></p>
? } # endfor
? } # endblock

The <? extends ?> tag is the key here. It tells the template engine that this template "extends" another template. When the template system evaluates this template, first it locates the parent -- in this case, "base.mt".

At that point, the template engine will notice the three <? block ?> tags in base.mt and replace those blocks with the contents of the child template. Depending on the value of blog_entries, the output might look like:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <link rel="stylesheet" href="style.css" />
    <title>My amazing blog</title>
</head>

<body>
    <div id="sidebar">
        <ul>
            <li><a href="/">Home</a></li>
            <li><a href="/blog/">Blog</a></li>
        </ul>
    </div>

    <div id="content">
        <h2>Entry one</h2>
        <p>This is my first entry.</p>

        <h2>Entry two</h2>
        <p>This is my second entry.</p>
    </div>
</body>
</html>

Note that since the child template didn't define the sidebar block, the value from the parent template is used instead. Content within a <? block ?> tag in a parent template is always used as a fallback.

You can use as many levels of inheritance as needed. One common way of using inheritance is the following three-level approach:

  1. Create a base.mt template that holds the main look-and-feel of your site.

  2. Create a base_SECTIONNAME.mt template for each "section" of your site. For example, base_news.mt, base_sports.mt. These templates all extend base.mt and include section-specific styles/design.

  3. Create individual templates for each type of page, such as a news article or blog entry. These templates extend the appropriate section template.

This approach maximizes code reuse and makes it easy to add items to shared content areas, such as section-wide navigation.

Here are some tips for working with inheritance:

  • If you use <? extends ?> in a template, it must be the first template tag in that template. Template inheritance won't work, otherwise.

  • More <? block ?> tags in your base templates are better. Remember, child templates don't have to define all parent blocks, so you can fill in reasonable defaults in a number of blocks, then only define the ones you need later. It's better to have more hooks than fewer hooks.

  • If you find yourself duplicating content in a number of templates, it probably means you should move that content to a <? block ?> in a parent template.

  • If you need to get the content of the block from the parent template, the <?= super() ?> variable will do the trick. This is useful if you want to add to the contents of a parent block instead of completely overriding it. Data inserted using <?= super() ?> will not be automatically escaped, since it was already escaped, if necessary, in the parent template.

  • For extra readability, you can optionally give a name to your <? } # endblock ?> tag. For example:

    <? block content => sub { ?>
...
<? } # endblock content ?>

    In larger templates, this technique helps you see which <? block ?> tags are being closed.

Finally, note that you can't define multiple <? block ?> tags with the same name in the same template. This limitation exists because a block tag works in "both" directions. That is, a block tag doesn't just provide a hole to fill -- it also defines the content that fills the hole in the parent. If there were two similarly-named <? block ?> tags in a template, that template's parent wouldn't know which one of the blocks' content to use.

Named template arguments

Text::MicroTemplate::Extended has new template_args option. Using this option, You can pass named template arguments to your tamplate like:

my $mf = Text::MicroTemplate::Extended->new(
    template_args => { foo => 'bar', },
    ...
);

Then in template:

<?= $foo ?>

This template display 'bar'.

template_args also supports CodeRef as its value life below:

my $mf = Text::MicroTemplate::Extended->new(
    template_args => { foo => sub { $self->get_foo() } },
    ...
);

In template, you can <?= $foo ?> to show $foo value. this value is set by calling $self->get_foo in template process time.

This feature is useful to set variable does not exists when template object is created.

Macro

Similar to named arguments, but this feature install your subroutine to template instead of variables.

my $mh = Text::MicroTemplate::Extended->new(
    macro => {
        hello => sub { return 'Hello World!' },
    },
    ...
);

And in template:

<?= hello() ?> # => 'Hello World'

extension option

There is another new option 'extension'. You can specify template file extension.

If this option is set, you don't have to set extension with render method:

$mf->render_file('template'); # render template.mt

Default value is '.mt'.

replace render method

For supporting template inheritance, it is no longer possible to implement original render method. Because extends function requires filename.

So in this module, render method acts same as render_file.

$mf->render('template');
$mf->render_file('template');

METHODS

new (%options)

my $mf = Text::MicroTemplate::Extended->new(
    extension     => '.mt',
    template_args => { c => $c, stash => $c->stash },
);

Create new Text::MicroTemplate::Extended object.

Available options are:

extension

Template file extension. (Default: '.mt')

template_args

Hash Reference of template args.

macro

Hash Reference of macros

See Text::MicroTemplate::File for more options.

render ($template_name, @args)

render_file ($template_name, @args)

Render $template_name and return result.

include ($template_name, @args)

include_file ($template_name, @args)

Render $template_name and return result.

Difference between include and render is that render treats extends and block macros and supports template inheritance but include not. But render method does not work in template.

<?= $self->render('template') ?> # does not work!

Instead of above, use:

<?= $self->include('template') ?>

# or just

<?= include('template') ?>

INTERNAL METHODS

build

eval_builder

template_args

extension

render_context

AUTHOR

Daisuke Murase <typester@cpan.org>

COPYRIGHT AND LICENSE

Copyright (c) 2009 by KAYAC Inc.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.