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

FreeBSD Manual Pages

  
 
  

home | help
Text::MicroTemplate::EUserdContributed Perl DoText::MicroTemplate::Extended(3)

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:

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

       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.

   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.

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

NAME | SYNOPSIS | DESCRIPTION | EXTENDED FEATURES | METHODS | INTERNAL METHODS | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Text::MicroTemplate::Extended&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help