Unix/Linux Go Back    


CentOS 7.0 - man page for template::document (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


Template::Document(3)	       User Contributed Perl Documentation	    Template::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 susequently
       "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-2012 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.16.3				    2012-01-25			    Template::Document(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 01:09 PM.