GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Text::MicroTemplate::Extended(3) User Contributed Perl Documentation Text::MicroTemplate::Extended(3)

Text::MicroTemplate::Extended - Extended MicroTemplate

    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

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

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.

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.

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'

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

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');

    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 and return result.

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') ?>

Daisuke Murase <typester@cpan.org>

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.

2012-08-16 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.