%PDF-
%PDF-
Mini Shell
Mini Shell
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Strict//EN">
<html>
<head>
<title>Template::Document</title>
<link rel="stylesheet" type="text/css" href="../../css/blue.css" title="Clear Blue">
<link rel="alternate stylesheet" type="text/css" href="../../css/orange.css" title="Clear Orange">
<link rel="alternate stylesheet" type="text/css" href="../../css/green.css" title="Clear Green">
<link rel="alternate stylesheet" type="text/css" href="../../css/purple.css" title="Clear Purple">
<link rel="alternate stylesheet" type="text/css" href="../../css/grey.css" title="Clear Grey">
<!--[if IE 6]>
<link rel="stylesheet" type="text/css" href="../../css/ie6.css" />
<![endif]-->
<link rel="stylesheet" type="text/css" href="/css/print.css" media="print">
<script type="text/javascript" src="../../js/tt2.js"></script>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
<meta name="author" content="Andy Wardley">
</head>
<body id="body">
<div id="layout">
<div id="header">
<a href="../../index.html" id="logo" alt="" title="Click for the Home Page"><span class="alt">TT2 Home Page</span></a>
<ul id="trail">
<li><a href="../../modules/index.html">Modules</a></li>
<li><a href="../../modules/Template/index.html">Template::*</a></li>
<li class="last"><a href="../../modules/Template/Document.html">Document.pm</a></li>
</ul>
<div class="controls">
<a href="#" class="menu show" onclick="widescreen_off(); return false" title="Show Menu">
<span class="about">Click to view the menu. It's very nice.</span>
</a>
<a href="#" class="menu hide" onclick="widescreen_on(); return false" title="Hide Menu">
<span class="about">Click to hide the menu and go all widescreen!</span>
</a>
<div class="pager">
<a href="../../modules/Template/Directive.html" title="Template::Directive" class="go back">Back<span class="about"><h4>Template::Directive</h4>Perl code generator for template directives</span></a>
<a href="../../modules/Template/index.html" title="Template::* Modules" class="go up">Up<span class="about"><h4>Template::* Modules</h4></span></a>
<a href="../../modules/Template/Exception.html" title="Template::Exception" class="go next">Next<span class="about"><h4>Template::Exception</h4>Exception handling class module</span></a>
</div>
</div>
<h1 class="headline">Template::Document</h1>
<h2 class="subhead">Compiled template document object</h1>
</div>
<div id="page">
<div id="sidebar">
<a href="../../index.html" id="logo"></a>
<div id="menu">
<ul class="menu">
<li class="l0 first"><a href="../../manual/index.html">Manual</a></li>
<li class="l0"><a href="../../modules/index.html" class="warm">Modules</a></li>
<li class="l1"><a href="../../modules/Template.html">Template.pm</a></li>
<li class="l1"><a href="../../modules/Template/index.html" class="warm">Template::*</a></li>
<li class="l2"><a href="../../modules/Template/Base.html">Base.pm</a></li>
<li class="l2"><a href="../../modules/Template/Config.html">Config.pm</a></li>
<li class="l2"><a href="../../modules/Template/Constants.html">Constants.pm</a></li>
<li class="l2"><a href="../../modules/Template/Context.html">Context.pm</a></li>
<li class="l2"><a href="../../modules/Template/Directive.html">Directive.pm</a></li>
<li class="l2"><a href="../../modules/Template/Document.html" class="warm">Document.pm</a></li>
<li class="l2"><a href="../../modules/Template/Exception.html">Exception.pm</a></li>
<li class="l2"><a href="../../modules/Template/Filters.html">Filters.pm</a></li>
<li class="l2"><a href="../../modules/Template/Grammar.html">Grammar.pm</a></li>
<li class="l2"><a href="../../modules/Template/Iterator.html">Iterator.pm</a></li>
<li class="l2"><a href="../../modules/Template/Namespace/index.html">Namespace::*</a></li>
<li class="l2"><a href="../../modules/Template/Parser.html">Parser.pm</a></li>
<li class="l2"><a href="../../modules/Template/Plugin.html">Plugin.pm</a></li>
<li class="l2"><a href="../../modules/Template/Plugin/index.html">Plugin::*</a></li>
<li class="l2"><a href="../../modules/Template/Plugins.html">Plugins.pm</a></li>
<li class="l2"><a href="../../modules/Template/Provider.html">Provider.pm</a></li>
<li class="l2"><a href="../../modules/Template/Service.html">Service.pm</a></li>
<li class="l2"><a href="../../modules/Template/Stash.html">Stash.pm</a></li>
<li class="l2"><a href="../../modules/Template/Stash/index.html">Stash::*</a></li>
<li class="l2"><a href="../../modules/Template/Test.html">Test.pm</a></li>
<li class="l2"><a href="../../modules/Template/VMethods.html">VMethods.pm</a></li>
<li class="l2"><a href="../../modules/Template/View.html">View.pm</a></li>
<li class="l0"><a href="../../tools/index.html">Tools</a></li>
<li class="l0 last"><a href="../../tutorial/index.html">Tutorial</a></li>
</ul>
<div class="foot"></div>
</div>
</div>
<div id="content">
<div class="section">
<div class="head">
<h1 id="contents" onclick="switch_section(this)" title="Click title to show/hide section content.">Contents</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<ul class="toc">
<li class=""><a href="#SYNOPSIS">SYNOPSIS</a></li>
<li class=""><a href="#DESCRIPTION">DESCRIPTION</a></li>
<li class=""><a href="#METHODS">METHODS</a></li>
<li class="sub"><a href="#method_new">new(\%config)</a></li>
<li class="sub"><a href="#method_process">process($context)</a></li>
<li class="sub"><a href="#method_block">block()</a></li>
<li class="sub"><a href="#method_blocks">blocks()</a></li>
<li class="sub"><a href="#section_AUTOLOAD">AUTOLOAD</a></li>
<li class=""><a href="#PACKAGE_SUB_ROUTINES">PACKAGE SUB-ROUTINES</a></li>
<li class="sub"><a href="#method_write_perl_file">write_perl_file(\%config)</a></li>
<li class=""><a href="#AUTHOR">AUTHOR</a></li>
<li class=""><a href="#COPYRIGHT">COPYRIGHT</a></li>
<li class=""><a href="#SEE_ALSO">SEE ALSO</a></li>
</ul>
</div>
</div>
<div class="pod">
<div class="section">
<div class="head">
<h1 id="SYNOPSIS" onclick="switch_section(this)" title="Click title to show/hide section content.">SYNOPSIS</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<pre>use Template::Document;
$doc = Template::Document->new({
BLOCK => sub { # some perl code; return $some_text },
DEFBLOCKS => {
header => sub { # more perl code; return $some_text },
footer => sub { # blah blah blah; return $some_text },
},
METADATA => {
author => 'Andy Wardley',
version => 3.14,
}
}) || die $Template::Document::ERROR;
print $doc->process($context);</pre>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="DESCRIPTION" onclick="switch_section(this)" title="Click title to show/hide section content.">DESCRIPTION</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
This module defines an object class whose instances represent compiled
template documents. The <a href="../../modules/Template/Parser.html">Template::Parser</a> module creates a
<code>Template::Document</code> instance to encapsulate a template as it
is compiled into Perl code.
</p>
<p>
The constructor method, <a href="#method_new">new()</a>, expects a
reference to a hash array containing the <code>BLOCK</code>,
<code>DEFBLOCKS</code> and <code>METADATA</code> items.
</p>
<p>
The <code>BLOCK</code> item should contain a reference to a Perl
subroutine or a textual representation of Perl code, as generated by the
<a href="../../modules/Template/Parser.html">Template::Parser</a>
module. This is then evaluated into a subroutine reference using
<code>eval()</code>.
</p>
<p>
The <code>DEFLOCKS</code> item should reference a hash array containing
further named <code>BLOCK</code>s which may be defined in the template.
The keys represent <code>BLOCK</code> names and the values should be
subroutine references or text strings of Perl code as per the main
<code>BLOCK</code> item.
</p>
<p>
The <code>METADATA</code> item should reference a hash array of metadata
items relevant to the document.
</p>
<p>
The <a href="#method_process">process()</a> method can then be called on
the instantiated <code>Template::Document</code> object, passing a
reference to a <a href="../../modules/Template/Context.html">Template::Context</a> object as the first parameter. This will
install any locally defined blocks (<code>DEFBLOCKS</code>) in the
<code>BLOCKS</code> cache in the context (via a call to <a href="../../modules/Template/Context.html#method_visit">visit()</a>) so that
they may be subsequently resolved by the context. The main
<code>BLOCK</code> subroutine is then executed, passing the context
reference on as a parameter. The text returned from the template
subroutine is then returned by the <a
href="#method_process">process()</a> method, after calling the context <a
href="../../modules/Template/Context.html#method_leave">leave()</a>
method to permit cleanup and de-registration of named <code>BLOCKS</code>
previously installed.
</p>
<p>
An <code>AUTOLOAD</code> method provides access to the
<code>METADATA</code> items for the document. The <a href="../../modules/Template/Service.html">Template::Service</a> module installs
a reference to the main <code>Template::Document</code> object in the
stash as the <code>template</code> variable. This allows metadata items
to be accessed from within templates, including <code>PRE_PROCESS</code>
templates.
</p>
<p>
header:
</p>
<pre><html>
<head>
<title>[% template.title %]
</head>
...</pre>
<p>
<code>Template::Document</code> objects are usually created by the <a
href="../../modules/Template/Parser.html">Template::Parser</a> but can
be manually instantiated or sub-classed to provide custom template
components.
</p>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="METHODS" onclick="switch_section(this)" title="Click title to show/hide section content.">METHODS</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<div class="subsection">
<div class="head">
<h2 id="method_new" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">new(\%config)</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Constructor method which accept a reference to a hash array containing
the structure as shown in this example:
</p>
<pre>$doc = Template::Document->new({
BLOCK => sub { # some perl code; return $some_text },
DEFBLOCKS => {
header => sub { # more perl code; return $some_text },
footer => sub { # blah blah blah; return $some_text },
},
METADATA => {
author => 'Andy Wardley',
version => 3.14,
}
}) || die $Template::Document::ERROR;</pre>
<p>
<code>BLOCK</code> and <code>DEFBLOCKS</code> items may be expressed as
references to Perl subroutines or as text strings containing Perl
subroutine definitions, as is generated by the <a href="../../modules/Template/Parser.html">Template::Parser</a> module. These are
evaluated into subroutine references using <code>eval()</code>.
</p>
<p>
Returns a new <code>Template::Document</code> object or
<code>undef</code> on error. The <a href="../../modules/Template/Base.html#method_error">error()</a> class method can be called, or the
<code>$ERROR</code> package variable inspected to retrieve the relevant
error message.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="method_process" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">process($context)</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Main processing routine for the compiled template document. A reference
to a <a href="../../modules/Template/Context.html">Template::Context</a> object should be passed as the first
parameter. The method installs any locally defined blocks via a call to
the context <a href="../../modules/Template/Context.html#method_visit">visit()</a> method, processes its own template,
(passing the context reference as a parameter) and then calls <a
href="../../modules/Template/Context.html#method_leave">leave()</a> in
the context to allow cleanup.
</p>
<pre>print $doc->process($context);</pre>
<p>
Returns a text string representing the generated output for the template.
Errors are thrown via <code>die()</code>.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="method_block" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">block()</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Returns a reference to the main <code>BLOCK</code> subroutine.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="method_blocks" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">blocks()</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Returns a reference to the hash array of named <code>DEFBLOCKS</code>
subroutines.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_AUTOLOAD" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">AUTOLOAD</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
An autoload method returns <code>METADATA</code> items.
</p>
<pre>print $doc->author();</pre>
</div>
</div>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="PACKAGE_SUB_ROUTINES" onclick="switch_section(this)" title="Click title to show/hide section content.">PACKAGE SUB-ROUTINES</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<div class="subsection">
<div class="head">
<h2 id="method_write_perl_file" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">write_perl_file(\%config)</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
This package subroutine is provided to effect persistence of compiled
templates. If the <code>COMPILE_EXT</code> option (to indicate a file
extension for saving compiled templates) then the <a href="../../modules/Template/Parser.html">Template::Parser</a> module calls this
subroutine before calling the <a href="#method_new">new()</a>
constructor. At this stage, the parser has a representation of the
template as text strings containing Perl code. We can write that to a
file, enclosed in a small wrapper which will allow us to susequently
<code>require()</code> the file and have Perl parse and compile it into a
<code>Template::Document</code>. Thus we have persistence of compiled
templates.
</p>
</div>
</div>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="AUTHOR" onclick="switch_section(this)" title="Click title to show/hide section content.">AUTHOR</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Andy Wardley <abw@wardley.org> <a
href="http://wardley.org/">http://wardley.org/</a>
</p>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="COPYRIGHT" onclick="switch_section(this)" title="Click title to show/hide section content.">COPYRIGHT</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
</p>
<p>
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
</p>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="SEE_ALSO" onclick="switch_section(this)" title="Click title to show/hide section content.">SEE ALSO</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
<a href="../../modules/Template.html">Template</a>, <a href="../../modules/Template/Parser.html">Template::Parser</a>
</p>
</div>
</div>
</div></div>
<br class="clear" />
<div class="pageinfo">
/modules/Template/Document.html last modified 10:57:47 31-May-2007
</div>
</div>
<div id="footer">
<a href="http://opensource.org/" class="osi"></a>
<div class="controls">
<div class="pager">
<a href="../../modules/Template/Directive.html" title="Template::Directive" class="go back">Back<span class="about"><h4>Template::Directive</h4></span></a>
<a href="../../modules/Template/index.html" title="Template::* Modules" class="go up">Up<span class="about"><h4>Template::* Modules</h4></span></a>
<a href="../../modules/Template/Exception.html" title="Template::Exception" class="go next">Next<span class="about"><h4>Template::Exception</h4></span></a>
</div>
</div>
<div class="copyright">
Copyright © 1996-2007 <a href="http://wardley.org/">Andy Wardley</a>. All Rights Reserved.
</div>
<div class="licence">
The <a href="http://template-toolkit.org/">Template Toolkit</a> is <a href="http://opensource.org/">Open Source</a> software.
You can redistribute and/or modify it under the terms of the <a href="http://www.opensource.org/licenses/gpl-license.php">GNU Public Licence</a>
or the <a href="http://www.opensource.org/licenses/artistic-license.php">Perl Artistic Licence</a>.
</div>
</div>
<div id="palette">
<ul>
<li class="first"><a href="#" class="blue" onclick="set_style('Clear Blue')"></a></li>
<li><a href="#" class="orange" onclick="set_style('Clear Orange')"></a></li>
<li><a href="#" class="green" onclick="set_style('Clear Green')"></a></li>
<li><a href="#" class="purple" onclick="set_style('Clear Purple')"></a></li>
<li><a href="#" class="grey" onclick="set_style('Clear Grey')"></a></li>
</ul>
</div>
</div> </body>
</html>
Zerion Mini Shell 1.0