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

FreeBSD Manual Pages

  
 
  

home | help
Template::Service(3)  User Contributed Perl Documentation Template::Service(3)

NAME
       Template::Service - General purpose template processing service

SYNOPSIS
	   use Template::Service;

	   my $service = Template::Service->new({
	       PRE_PROCESS  => [ 'config', 'header' ],
	       POST_PROCESS => 'footer',
	       ERROR	    => {
		   user	    => 'user/index.html',
		   dbi	    => 'error/database',
		   default  => 'error/default',
	       },
	   });

	   my $output =	$service->process($template_name, \%replace)
	       || die $service->error(), "\n";

DESCRIPTION
       The "Template::Service" module implements an object class for providing
       a consistent template processing	service.

       Standard	header (PRE_PROCESS) and footer	(POST_PROCESS) templates may
       be specified which are prepended	and appended to	all templates
       processed by the	service	(but not any other templates or	blocks
       "INCLUDE"d or "PROCESS"ed from within). An ERROR	hash may be specified
       which redirects the service to an alternate template file in the	case
       of uncaught exceptions being thrown. This allows	errors to be
       automatically handled by	the service and	a guaranteed valid response to
       be generated regardless of any processing problems encountered.

       A default "Template::Service" object is created by the Template module.
       Any "Template::Service" options may be passed to	the Template new()
       constructor method and will be forwarded	to the Template::Service
       constructor.

	   use Template;

	   my $template	= Template->new({
	       PRE_PROCESS  => 'header',
	       POST_PROCESS => 'footer',
	   });

       Similarly, the "Template::Service" constructor will forward all
       configuration parameters	onto other default objects (e.g.
       Template::Context) that it may need to instantiate.

       A "Template::Service" object (or	subclass) can be explicitly
       instantiated and	passed to the Template new() constructor method	as the
       SERVICE item.

	   use Template;
	   use Template::Service;

	   my $service = Template::Service->new({
	       PRE_PROCESS  => 'header',
	       POST_PROCESS => 'footer',
	   });

	   my $template	= Template->new({
	       SERVICE => $service,
	   });

       The "Template::Service" module can be sub-classed to create custom
       service handlers.

	   use Template;
	   use MyOrg::Template::Service;

	   my $service = MyOrg::Template::Service->new({
	       PRE_PROCESS  => 'header',
	       POST_PROCESS => 'footer',
	       COOL_OPTION  => 'enabled	in spades',
	   });

	   my $template	= Template->new({
	       SERVICE => $service,
	   });

       The Template module uses	the Template::Config service() factory method
       to create a default service object when required. The
       $Template::Config::SERVICE package variable may be set to specify an
       alternate service module. This will be loaded automatically and its
       new() constructor method	called by the service()	factory	method when a
       default service object is required. Thus	the previous example could be
       written as:

	   use Template;

	   $Template::Config::SERVICE =	'MyOrg::Template::Service';

	   my $template	= Template->new({
	       PRE_PROCESS  => 'header',
	       POST_PROCESS => 'footer',
	       COOL_OPTION  => 'enabled	in spades',
	   });

METHODS
   new(\%config)
       The "new()" constructor method is called	to instantiate a
       "Template::Service" object.  Configuration parameters may be specified
       as a HASH reference or as a list	of "name => value" pairs.

	   my $service1	= Template::Service->new({
	       PRE_PROCESS  => 'header',
	       POST_PROCESS => 'footer',
	   });

	   my $service2	= Template::Service->new( ERROR	=> 'error.html'	);

       The "new()" method returns a "Template::Service"	object or "undef" on
       error. In the latter case, a relevant error message can be retrieved by
       the error() class method	or directly from the $Template::Service::ERROR
       package variable.

	   my $service = Template::Service->new(\%config)
	       || die Template::Service->error();

	   my $service = Template::Service->new(\%config)
	       || die $Template::Service::ERROR;

   process($input, \%replace)
       The "process()" method is called	to process a template specified	as the
       first parameter,	$input.	This may be a file name, file handle (e.g.
       "GLOB" or "IO::Handle") or a reference to a text	string containing the
       template	text. An additional hash reference may be passed containing
       template	variable definitions.

       The method processes the	template, adding any PRE_PROCESS or
       POST_PROCESS templates defined, and returns the output text. An
       uncaught	exception thrown by the	template will be handled by a relevant
       ERROR handler if	defined. Errors	that occur in the PRE_PROCESS or
       POST_PROCESS templates, or those	that occur in the main input template
       and aren't handled, cause the method to return "undef" to indicate
       failure.	The appropriate	error message can be retrieved via the error()
       method.

	   $service->process('myfile.html', { title => 'My Test	File' })
	       || die $service->error();

   context()
       Returns a reference to the internal context object which	is, by
       default,	an instance of the Template::Context class.

CONFIGURATION OPTIONS
       The following list summarises the configuration options that can	be
       provided	to the "Template::Service" new() constructor. Please consult
       Template::Manual::Config	for further details and	examples of each
       configuration option in use.

   PRE_PROCESS,	POST_PROCESS
       The PRE_PROCESS and POST_PROCESS	options	may be set to contain the
       name(s) of template files which should be processed immediately before
       and/or after each template. These do not	get added to templates
       processed into a	document via directives	such as	"INCLUDE" "PROCESS",
       "WRAPPER", etc.

	   my $service = Template::Service->new({
	       PRE_PROCESS  => 'header',
	       POST_PROCESS => 'footer',
	   };

       Multiple	templates may be specified as a	reference to a list.  Each is
       processed in the	order defined.

	   my $service = Template::Service->new({
	       PRE_PROCESS  => [ 'config', 'header' ],
	       POST_PROCESS => 'footer',
	   };

   PROCESS
       The PROCESS option may be set to	contain	the name(s) of template	files
       which should be processed instead of the	main template passed to	the
       "Template::Service" process() method. This can be used to apply
       consistent wrappers around all templates, similar to the	use of
       PRE_PROCESS and POST_PROCESS templates.

	   my $service = Template::Service->new({
	       PROCESS	=> 'content',
	   };

	   # processes 'content' instead of 'foo.html'
	   $service->process('foo.html');

       A reference to the original template is available in the	"template"
       variable.  Metadata items can be	inspected and the template can be
       processed by specifying it as a variable	reference (i.e.	prefixed by
       '"$"') to an "INCLUDE", "PROCESS" or "WRAPPER" directive.

       Example "PROCESS" template:

	   <html>
	     <head>
	       <title>[% template.title	%]</title>
	     </head>
	     <body>
	     [%	PROCESS	$template %]
	     </body>
	   </html>

   ERROR
       The ERROR (or "ERRORS" if you prefer) configuration item	can be used to
       name a single template or specify a hash	array mapping exception	types
       to templates which should be used for error handling. If	an uncaught
       exception is raised from	within a template then the appropriate error
       template	will instead be	processed.

       If specified as a single	value then that	template will be processed for
       all uncaught exceptions.

	   my $service = Template::Service->new({
	       ERROR =>	'error.html'
	   });

       If the ERROR or ERRORS item is a	hash reference the keys	are assumed to
       be exception types and the relevant template for	a given	exception will
       be selected. A "default"	template may be	provided for the general case.

	   my $service = Template::Service->new({
	       ERRORS => {
		   user	    => 'user/index.html',
		   dbi	    => 'error/database',
		   default  => 'error/default',
	       },
	   });

   AUTO_RESET
       The AUTO_RESET option is	set by default and causes the local "BLOCKS"
       cache for the Template::Context object to be reset on each call to the
       Template	process() method.  This	ensures	that any "BLOCK"s defined
       within a	template will only persist until that template is finished
       processing.

   DEBUG
       The DEBUG option	can be used to enable debugging	messages from the
       "Template::Service" module by setting it	to include the "DEBUG_SERVICE"
       value.

	   use Template::Constants qw( :debug );

	   my $template	= Template->new({
	       DEBUG =>	DEBUG_SERVICE,
	   });

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

COPYRIGHT
       Copyright (C) 1996-2007 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::Context

perl v5.24.1			  2014-04-23		  Template::Service(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | CONFIGURATION OPTIONS | AUTHOR | COPYRIGHT | SEE ALSO

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

home | help