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

FreeBSD Manual Pages

  
 
  

home | help
Template::Document(3) User Contributed Perl DocumentationTemplate::Document(3)

NAME
       Template::Document - Compiled template document object

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

DESCRIPTION
       This module defines an object class whose instances represent compiled
       template	documents.  The	Template::Parser module	creates	a
       "Template::Document" instance to	encapsulate a template as it is
       compiled	into Perl code.

       The constructor method, new(), expects a	reference to a hash array
       containing the "BLOCK", "DEFBLOCKS" and "METADATA" items.

       The "BLOCK" item	should contain a reference to a	Perl subroutine	or a
       textual representation of Perl code, as generated by the
       Template::Parser	module.	 This is then evaluated	into a subroutine
       reference using "eval()".

       The "DEFLOCKS" item should reference a hash array containing further
       named "BLOCK"s which may	be defined in the template. The	keys represent
       "BLOCK" names and the values should be subroutine references or text
       strings of Perl code as per the main "BLOCK" item.

       The "METADATA" item should reference a hash array of metadata items
       relevant	to the document.

       The process() method can	then be	called on the instantiated
       "Template::Document" object, passing a reference	to a Template::Context
       object as the first parameter. This will	install	any locally defined
       blocks ("DEFBLOCKS") in the "BLOCKS" cache in the context (via a	call
       to visit()) so that they	may be subsequently resolved by	the context.
       The main	"BLOCK"	subroutine is then executed, passing the context
       reference on as a parameter. The	text returned from the template
       subroutine is then returned by the process() method, after calling the
       context leave() method to permit	cleanup	and de-registration of named
       "BLOCKS"	previously installed.

       An "AUTOLOAD" method provides access to the "METADATA" items for	the
       document. The Template::Service module installs a reference to the main
       "Template::Document" object in the stash	as the "template" variable.
       This allows metadata items to be	accessed from within templates,
       including "PRE_PROCESS" templates.

       header:

	   <html>
	   <head>
	   <title>[% template.title %]
	   </head>
	   ...

       "Template::Document" objects are	usually	created	by the
       Template::Parser	but can	be manually instantiated or sub-classed	to
       provide custom template components.

METHODS
   new(\%config)
       Constructor method which	accept a reference to a	hash array containing
       the structure as	shown in this example:

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

       "BLOCK" and "DEFBLOCKS" items may be expressed as references to Perl
       subroutines or as text strings containing Perl subroutine definitions,
       as is generated by the Template::Parser module.	These are evaluated
       into subroutine references using	"eval()".

       Returns a new "Template::Document" object or "undef" on error. The
       error() class method can	be called, or the $ERROR package variable
       inspected to retrieve the relevant error	message.

   process($context)
       Main processing routine for the compiled	template document. A reference
       to a Template::Context object should be passed as the first parameter.
       The method installs any locally defined blocks via a call to the
       context visit() method, processes its own template, (passing the
       context reference as a parameter) and then calls	leave()	in the context
       to allow	cleanup.

	   print $doc->process($context);

       Returns a text string representing the generated	output for the
       template.  Errors are thrown via	"die()".

   block()
       Returns a reference to the main "BLOCK" subroutine.

   blocks()
       Returns a reference to the hash array of	named "DEFBLOCKS" subroutines.

   variables()
       Returns a reference to a	hash of	variables used in the template.	 This
       requires	the TRACE_VARS option to be enabled.

   AUTOLOAD
       An autoload method returns "METADATA" items.

	   print $doc->author();

CLASS METHODS
       These methods are used internally.

   as_perl($content)
       This method generate a Perl representation of the template.

	   my $perl = Template::Document->as_perl({
	       BLOCK	 => $main_block,
	       DEFBLOCKS => {
		   foo	 => $foo_block,
		   bar	 => $bar_block,
	       },
	       METADATA	 => {
		   name	 => 'my_template',
	       }
	   });

   write_perl_file(\%config)
       This method is used to write compiled Perl templates to disk.  If the
       "COMPILE_EXT" option (to	indicate a file	extension for saving compiled
       templates) then the Template::Parser module calls this subroutine
       before calling the new()	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 subsequently	"require()" the	file and have Perl parse and
       compile it into a "Template::Document".	Thus we	have persistence of
       compiled	templates.

INTERNAL FUNCTIONS
   catch_warnings()
       This is a simple	handler	used to	catch any errors that arise when the
       compiled	Perl template is first evaluated (that is, evaluated by	Perl
       to create a template subroutine at compile, rather than the template
       being processed at runtime).

   is_utf8()
       This is mapped to "utf8::is_utf8" for versions of Perl that have	it (>
       5.008) or to "Encode::is_utf8" for Perl 5.008.  Earlier versions	of
       Perl are	not supported.

AUTHOR
       Andy Wardley <abw@wardley.org> <http://wardley.org/>

COPYRIGHT
       Copyright (C) 1996-2013 Andy Wardley.  All Rights Reserved.

       This module is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

SEE ALSO
       Template, Template::Parser

perl v5.32.1			  2020-07-13		 Template::Document(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | CLASS METHODS | INTERNAL FUNCTIONS | AUTHOR | COPYRIGHT | SEE ALSO

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

home | help