Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Text::MicroTemplate::EUserdContributed Perl DoText::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/

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

   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

	   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0	Transitional//EN"
	   <html xmlns="" xml:lang="en" lang="en">
	       <link rel="stylesheet" href="style.css" />
	       <title><? block title =>	sub { ?>My amazing site<? } ?></title>

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

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

       This template, which we'll call,	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

       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,

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

	   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0	Transitional//EN"
	   <html xmlns="" xml:lang="en" lang="en">
	       <link rel="stylesheet" href="style.css" />
	       <title>My amazing blog</title>

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

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

       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 template that holds	the main look-and-feel of your

       2.  Create a	template for each "section" of your
	   site. For example,, These templates
	   all extend 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:

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

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

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

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

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

       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

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

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

       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

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


   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:

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

	   Hash	Reference of template args.

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

       Daisuke Murase <>

       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.

perl v5.32.1			  2012-08-16  Text::MicroTemplate::Extended(3)


Want to link to this manual page? Use this URL:

home | help