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

FreeBSD Manual Pages

  
 
  

home | help
Template::Manual::IntrUser Contributed Perl DocumentTemplate::Manual::Intro(3)

NAME
       Template::Manual::Intro - Introduction to the Template Toolkit

Introduction
       The Template Toolkit is a collection of Perl modules which implement a
       fast, flexible, powerful	and extensible template	processing system.  It
       is most often used for generating dynamic web content, although it can
       be used equally well for	processing any kind of text documents.

       At the simplest level it	provides an easy way to	process	template
       files, filling in embedded variable references with their equivalent
       values.	Here's an example of a template.

	   Dear	[% name	%],

	   It has come to our attention	that your account is in
	   arrears to the sum of [% debt %].

	   Please settle your account before [%	deadline %] or we
	   will	be forced to revoke your Licence to Thrill.

	   The Management.

       By default, template directives are embedded within the character
       sequences "[%" ... "%]" but you can change these	and various other
       options to configure how	the Template Toolkit looks, feels and works.
       You can set the "INTERPOLATE" option, for example, if you prefer	to
       embed your variables in Perl style:

	   Dear	$name,

	   It has come to our attention	that your account is in
	   arrears to the sum of $debt.

	   ...etc...

The Template Perl Module
       The Template Perl module	is the front end to the	Template Toolkit for
       Perl programmers, providing access to the full range of functionality
       through a single	module with a simple interface.	It loads the other
       modules as required and instantiates a default set of objects to	handle
       subsequent template processing requests.	Configuration parameters may
       be passed to the	Template constructor method, new(), which are then
       used to configure the generate object.

	   use Template;

	   my $tt = Template->new({
	       INCLUDE_PATH => '/usr/local/templates',
	       INTERPOLATE  => 1,
	   }) || die "$Template::ERROR\n";

       The Template object implements a	process() method for processing
       template	files or text. The name	of the input template (or various
       other sources) is passed	as the first argument, followed	by a reference
       to a hash array of variable definitions for substitution	in the
       template.

	   my $vars = {
	       name	=> 'Count Edward van Halen',
	       debt	=> '3 riffs and	a solo',
	       deadline	=> 'the	next chorus',
	   };

	   $tt->process('letters/overdrawn', $vars)
	       || die $tt->error(), "\n";

       The process() method returns a true value (1) on	success	and prints the
       template	output to "STDOUT", by default.	On error, the process()	method
       returns a false value ("undef").	 The error() method can	then be	called
       to retrieve details of the error.

Component Based	Content	Construction
       A number	of special directives are provided, such as "INSERT",
       "INCLUDE" and "PROCESS",	which allow content to be built	up from
       smaller template	components. This permits a modular approach to
       building	a web site or other content repository,	promoting reusability,
       cross-site consistency, ease of construction and	subsequent
       maintenance. Common elements such as headers, footers, menu bars,
       tables, and so on, can be created as separate template files which can
       then be processed into other documents as required. All defined
       variables are inherited by these	templates along	with any additional
       "local" values specified.

	   [% PROCESS header
		title =	"The Cat Sat on	the Mat"
	   %]

	   [% PROCESS menu %]

	   The location	of the missing feline has now been established.
	   Thank you for your assistance.

	   [% INSERT legal/disclaimer %]

	   [% PROCESS footer %]

       You can also define a template as a BLOCK within	the same file and
       PROCESS it just like any	other template file.  This can be invaluable
       for building up repetitive elements such	as tables, menus, etc.

	   [% BLOCK tabrow %]
	      <tr><td>[% name %]</td><td>[% email %]</td></tr>
	   [% END %]

	   <table>
	   [% PROCESS tabrow name="tom"	  email="tom@here.org"	  %]
	   [% PROCESS tabrow name="dick"  email="disk@there.org"  %]
	   [% PROCESS tabrow name="larry" email="larry@where.org" %]
	   </table>

Data and Code Binding
       One of the key features that sets the Template Toolkit apart from other
       template	processors is the ability to bind template variables to	any
       kind of Perl data: scalars, lists, hash arrays, sub-routines and
       objects.

	   my $vars = {
	       root   => 'http://here.com/there',
	       menu   => [ 'modules', 'authors', 'scripts' ],
	       client => {
		   name	=> 'Doctor Joseph von Satriani',
		   id	=> 'JVSAT',
	       },
	       checkout	=> sub { my $total = shift; ...; return	$something },
	       shopcart	=> My::Cool::Shopping::Cart->new(),
	   };

       The Template Toolkit will automatically Do The Right Thing to access
       the data	in an appropriate manner to return some	value which can	then
       be output. The dot operator '"."' is used to access into	lists and
       hashes or to call object	methods. The "FOREACH" directive is provided
       for iterating through lists, and	various	logical	tests are available
       using directives	such as	"IF", "UNLESS",	"ELSIF", "ELSE", "SWITCH",
       "CASE", etc.

	   [% FOREACH section =	menu %]
	      <a href="[% root %]/[% section %]/index.html">[% section %]</a>
	   [% END %]

	   <b>Client</b>: [% client.name %] (id: [% client.id %])

	   [% IF shopcart.nitems %]
	      Your shopping cart contains the following	items:
	      <ul>
	      [% FOREACH item =	shopcart.contents %]
		<li>[% item.name %] : [% item.qty %] @ [% item.price %]
	      [% END %]
	      </ul>

	      [% checkout(shopcart.total) %]

	   [% ELSE %]
	      No items currently in shopping cart.
	   [% END %]

Advanced Features: Filters, Macros, Exceptions,	Plugins
       The Template Toolkit also provides a number of additional directives
       for advanced processing and programmatical functionality.  It supports
       output filters (FILTER),	allows custom macros to	be defined (MACRO),
       has a fully-featured exception handling system (TRY, THROW, CATCH,
       FINAL) and supports a plugin architecture (USE) which allows special
       plugin modules and even regular Perl modules to be loaded and used with
       the minimum of fuss.  The Template Toolkit is "just" a template
       processor but you can trivially extend it to incorporate	the
       functionality of	any Perl module	you can	get your hands on.  Thus, it
       is also a scalable and extensible template framework, ideally suited
       for managing the	presentation layer for application servers, content
       management systems and other web	applications.

Separating Presentation	and Application	Logic
       Rather than embedding Perl code or some other scripting language
       directly	into template documents, it encourages you to keep functional
       components (i.e.	Perl code) separate from presentation components (e.g.
       HTML templates).	 The template variables	provide	the interface between
       the two layers, allowing	data to	be generated in	code and then passed
       to a template component for displaying (pipeline	model) or for sub-
       routine or object references to be bound	to variables which can then be
       called from the template	as and when required (callback model).

       The directives that the Template	Toolkit	provide	implement their	own
       mini programming	language, but they're not really designed for serious,
       general purpose programming.  Perl is a far more	appropriate language
       for that.  If you embed application logic (e.g. Perl or other scripting
       language	fragments) in HTML templates then you risk losing the clear
       separation of concerns between functionality and	presentation.  It
       becomes harder to maintain the two elements in isolation	and more
       difficult, if not impossible, to	reuse code or presentation elements by
       themselves.  It is far better to	write your application code in
       separate	Perl modules, libraries	or scripts and then use	templates to
       control how the resulting data is presented as output.  Thus you	should
       think of	the Template Toolkit language as a set of layout directives
       for displaying data, not	calculating it.

       Having said that, the Template Toolkit doesn't force you	into one
       approach	or the other.  It attempts to be pragmatic rather than
       dogmatic	in allowing you	to do whatever best gets the job done.	Thus,
       if you enable the EVAL_PERL option then you can happily embed real Perl
       code in your templates within PERL ... END directives.

Performance
       The Template Toolkit uses a fast	YACC-like parser which compiles
       templates into Perl code	for maximum runtime efficiency.	 It also has
       an advanced caching mechanism which manages in-memory and on-disk (i.e.
       persistent) versions of compiled	templates.  The	modules	that comprise
       the toolkit are highly configurable and the architecture	around which
       they're built is	designed to be extensible.  The	Template Toolkit
       provides	a powerful framework around which content creation and
       delivery	systems	can be built while also	providing a simple interface
       through the Template front-end module for general use.

perl v5.32.1			  2020-03-30	    Template::Manual::Intro(3)

NAME | Introduction | The Template Perl Module | Component Based Content Construction | Data and Code Binding | Advanced Features: Filters, Macros, Exceptions, Plugins | Separating Presentation and Application Logic | Performance

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

home | help