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

FreeBSD Manual Pages

  
 
  

home | help
CGI::Application::PlugUserAContributedCPI::Application::Plugin::AnyTemplate(3)

NAME
       CGI::Application::Plugin::AnyTemplate - Use any templating system from
       within CGI::Application using a unified interface

VERSION
       Version 0.18

SYNOPSIS
       In your CGI::Application-based webapp:

	   use base 'CGI::Application';
	   use CGI::Application::Plugin::AnyTemplate;

	   sub cgiapp_init {
	       my $self	= shift;

	       # Set template options
	       $self->template->config(
		   default_type	=> 'TemplateToolkit',
	       );
	   }

       Later on, in a runmode:

	   sub my_runmode {
	       my $self	= shift;

	       my %template_params = (
		   name	    => 'Winston	Churchill',
		   age	    => 7,
	       );

	       $self->template->fill('some_template', \%template_params);
	   }

DESCRIPTION
   Template-Independence
       "CGI::Application::Plugin::AnyTemplate" allows you to use any supported
       Perl templating system using a single consistent	interface.

       Currently supported templating systems include HTML::Template,
       HTML::Template::Expr, HTML::Template::Pluggable,	Template::Toolkit and
       Petal.

       You can access any of these templating systems using the	same
       interface.  In this way,	you can	use the	same code and switch
       templating systems on the fly.

       This approach has many uses.  For instance, it can be useful in
       migrating your application from one templating system to	another.

   Embedded Components
       In addition to template abstraction, "AnyTemplate" also provides	a
       embedded	component mechanism.  For instance, you	might include a	header
       component at the	top of every page and a	footer component at the	bottom
       of every	page.

       These components	are actually full CGI::Application run modes, and can
       do anything normal run mode can do, including processing	form
       parameters and filling in their own templates.  See below under
       "EMBEDDED COMPONENTS" for details.

   Multiple Named Template Configurations
       You can set up multiple named template configurations and select
       between them at run time.

	   sub cgiapp_init {
	       my $self	= shift;

	       # Can't use Template::Toolkit any more -
	       # The boss wants	everything has to be XML,
	       # so we switch to Petal

	       # Set old-style template	options	(legacy	scripts)
	       $self->template('oldstyle')->config(
		   default_type	=> 'TemplateToolkit',
		   TemplateToolkit => {
		       POST_CHOMP => 1,
		   }
	       );
	       # Set new-style template	options	as default
	       $self->template->config(
		   default_type	=> 'Petal',
		   auto_add_template_extension => 0,
	       );
	   }

	   sub old_style_runmode {
	       my $self	= shift;

	       # ...

	       # use TemplateToolkit to	fill template edit_user.tmpl
	       $self->template('oldstyle')->fill('edit_user', \%params);

	   }

	   sub new_style_runmode {
	       my $self	= shift;

	       # ...

	       # use Petal to fill template edit_user.xhml
	       $self->template->fill('edit_user.xhtml',	\%params);

	   }

   Flexible Syntax
       The syntax is pretty flexible.  Pick a style that's most	comfortable
       for you.

       CGI::Application::Plugin::TT style syntax

	   $self->template->process('edit_user', \%params);

       or (with	slightly less typing):

	   $self->template->fill('edit_user', \%params);

       CGI::Application	load_tmpl style	syntax

	   my $template	= $self->template->load('edit_user');
	   $template->param('foo' => 'bar');
	   $template->output;

       Verbose syntax (for complete control)

	   my $template	= $self->template('named_config')->load(
	       file		 => 'edit_user'
	       type		 => 'TemplateToolkit'
	       add_include_paths => '.',
	   );

	   $template->param('foo' => 'bar');
	   $template->output;

       See also	below under "CHANGING THE NAME OF THE 'template' METHOD".

METHODS
   config
       Initialize the "AnyTemplate" system and provide the default
       configuration.

	   $self->template->config(
	       default_type => 'HTMLTemplate',
	   );

       You can keep multiple configurations handy at the same time by passing
       a value to "template":

	   $self->template('oldstyle')->config(
	       default_type => 'HTML::Template',
	   );
	   $self->template('newstyle')->config(
	       default_type => 'HTML::Template::Expr',
	   );

       Then in a runmode you can mix and match configurations:

	   $self->template('oldstyle')->load  #	loads an HTML::Template	driver object
	   $self->template('newstyle')->load  #	loads an HTML::Template::Expr driver object

       The configuration passed	to "config" is divided into three areas:
       plugin configuration, driver configuration, and native configuration:

	   Config Type	     What it Configures
	   -----------	     ------------------
	   Plugin Config     AnyTemplate itself
	   Driver Config     AnyTemplate Driver	(e.g. HTMLTemplate)
	   Native Config     Actual template module (e.g. HTML::Template)

       These are described in more detail below.

       Plugin Configuration

       These configuration params are specific to the
       "CGI::Application::Plugin::AnyTemplate" itself.	They are included at
       the top level of	the configuration hash passed to "config".  For
       instance:

	   $self->template->config(
	       default_type		   => 'HTMLTemplate',
	       auto_add_template_extension => 0,
	   );

       The plugin configuration	parameters and their defaults are as follows:

       default_type
       type
	   The default type of template	for this named configuration.  Should
	   be the name of a driver in the
	   "CGI::Application::Plugin::AnyTemplate::Driver" namespace:

	       Type		   Driver
	       ----		   ------
	       HTMLTemplate	   CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplate
	       HTMLTemplateExpr	   CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplateExpr
	       TemplateToolkit	   CGI::Application::Plugin::AnyTemplate::Driver::TemplateToolkit
	       Petal		   CGI::Application::Plugin::AnyTemplate::Driver::Petal

       include_paths
	   Include Paths (sometimes called search paths) are used by the
	   various template backends to	find filenames that aren't fully
	   qualified by	an absolute path.  Each	directory is searched in turn
	   until the template file is found.

	   Can be a single string or a reference to a list.

       auto_add_template_extension
	   Add a template-system specific extension to template	filenames.

	   So, if this feature is enabled and you provide the filename
	   "myfile", then the actual filename will depend on the current
	   template driver:

	       Driver		      Template
	       ------		      --------
	       HTMLTemplate	      myfile.html
	       HTMLTemplateExpr	      myfile.html
	       TemplateToolkit	      myfile.tmpl
	       Petal		      myfile.xhtml

	   The per-type	extension is controlled	by the driver config for each
	   "AnyTemplate" driver	(see below under "Driver and Native
	   Configuration" for how to set this).

	   The "auto_add_template_extension" feature is	on by default.	To
	   disable it, pass a value of zero:

	       $self->template->config(
		   auto_add_template_extension => 0,
	       );

	   The automatic extension feature is not just there to	save typing -
	   it's	actually there so you can have templates of different types
	   sitting in the same directory.

	       sub my_runmode {
		   my $self = shift;
		   $self->template->fill;
	       }

	   Then	in your	template path you can have three files:

	       my_runmode.html
	       my_runmode.tmpl
	       my_runmode.xhtml

	   Then	you can	change which templates is used by changing the value
	   of "type" that you pass to "$self->template->config".

	   For applications that want to dynamically choose their template
	   system without changing app code, it's a cleaner solution to	use
	   the extensions than trying to swap template paths at	runtime.  Even
	   if you keep each type of template in	its own	directory, it's
	   simpler to include all the directories all the time and use
	   different extensions	for different template types.

       template_filename_generator
	   If you don't	pass a filename	to "load", one will be generated for
	   you based on	the current run	mode.  If you want to customize	this
	   process, you	can pass a reference to	a subroutine to	do the
	   translation.	 This subroutine will be passed	a reference to the
	   CGI::Application $self object.

	   Here	is a subroutine	that emulates the built-in behaviour of
	   "AnyTemplate":

	       $self->template->config(
		   template_filename_generator => sub {
		       my ($self, $calling_method_name)	= @_;
			   return $self->get_current_runmode;
		       }
		   }
	       );

	   Here	is an example of using a template filename generator to	make
	   full	templates with full paths based	on the module name as well as
	   the current run mode	(this is similar to how
	   CGI::Application::Plugin::TT	generates its template filenames):

	       package My::WebApp;
	       use File::Spec;

	       sub cgiapp_init {
		   my $self = shift;

		   $self->template->config(
		       template_filename_generator => sub {
			   my $self	= shift;
			   my $run_mode	= $self->get_current_runmode;
			   my $module	= ref $self;

			   my @segments	= split	/::/, $module;

			   return File::Spec->catfile(@segments, $run_mode);
		       }
		   );
	       }

	       sub run_mode {
		   my $self = shift;
		   $self->template->load;  # loads My/WebApp/run_mode.html
	       }

	       sub other_run_mode {
		   my $self = shift;
		   $self->template->load;  # loads My/WebApp/other_run_mode.html
	       }

	   Note	that if	the "auto_add_template_extension" option is on (which
	   it is by default), then the extension will be added to your
	   generated filename after you	return it.  If you do not want this to
	   happen, then	set "auto_add_template_extension" to a false value.

       component_handler_class
	   Normally, component embedding is handled by
	   CGI::Application::Plugin::AnyTemplate::ComponentHandler.  If	you
	   want	to use a different class for this purpose, specify the class
	   name	as the value of	this paramter.

	   It still has	to provide the same interface as
	   CGI::Application::Plugin::AnyTemplate::ComponentHandler.  See the
	   source code of that module for details.

       return_references
	   When	true (the default), "output" will return a reference to	a
	   string rather than a	copy.  Normally	this won't matter.  For
	   instance, "CGI::Application"	doesn't	care whether you return	a
	   string or a reference to a string from your run modes.

	   However, if you want	to manipulate the output of the	$html returned
	   from	the template, you may find it convenient to make "output"
	   return a string instead of a	reference.  Especially if you are
	   converting old code based on	HTML::Template which expects "output"
	   to return a string.

       Driver and Native Configuration

       You can configure all the drivers at once with a	single call to
       "config", by including subsections for each driver type:

	   $self->template->config(
	       default_type => 'HTMLTemplate',
	       HTMLTemplate => {
		   cache	      => 1,
		   global_vars	      => 1,
		   die_on_bad_params  => 0,
		   template_extension => '.html',
	       },
	       HTMLTemplateExpr	=> {
		   cache	      => 1,
		   global_vars	      => 1,
		   die_on_bad_params  => 0,
		   template_extension => '.html',
	       },
	       HTMLTemplatePluggable =>	{
		   cache	      => 1,
		   global_vars	      => 1,
		   die_on_bad_params  => 0,
		   template_extension => '.html',
	       },
	       TemplateToolkit => {
		   POST_CHOMP	      => 1,
		   template_extension => '.tmpl',
	       },
	       Petal =>	{
		   error_on_undef     => 0,
		   template_extension => '.xhtml',
	       },
	   );

       Each driver knows how to	separate its own configuration from the
       configuration belonging to the underlying template system.

       For instance in the example above, the "HTMLTemplate" driver knows that
       "template_extension" is a driver	config parameter, but
       "cache_global_vars" and "die_on_bad_params" are all HTML::Template
       configuration parameters.

       Similarly, The "TemplateToolkit"	driver knows that template_extension
       is a driver config parameter, but "POST_CHOMP" is a "Template::Toolkit"
       configuration parameter.

       For details on driver configuration, see	the docs for the individual
       drivers:

       CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplate
       CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplateExpr
       CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplatePluggable
       CGI::Application::Plugin::AnyTemplate::Driver::TemplateToolkit
       CGI::Application::Plugin::AnyTemplate::Driver::Petal

       Copying Query data into Templates

       This feature is now deprecated and will be removed in a future release.

       When you	enable this feature all	data in	"$self->query" are copied into
       the template object before the template is processed.

       For the "HTMLTemplate", "HTMLTemplateExpr" and "HTMLTemplatePluggable"
       drivers this is done with the "associate" feature of HTML::Template and
       HTML::Template::Expr, respectively:

	   my $template	= HTML::Template->new(
	       associate => $self->query,
	   );

       For the other systems, this feature is emulated,	by copying the query
       params into the template	params before the template is processed.

       To enable this feature, pass a true value to "associate_query" or
       "emulate_associate_query" (depending on the template system):
	   $self->template->config(
	       default_type => 'HTMLTemplate',
	       HTMLTemplate => {
		   associate_query => 1,
	       },
	       HTMLTemplateExpr	=> {
		   associate_query => 1,
	       },
	       HTMLTemplatePluggable =>	{
		   associate_query => 1,
	       },
	       TemplateToolkit => {
		   emulate_associate_query => 1,
	       },
	       Petal =>	{
		   emulate_associate_query => 1,
	       },
	   );

       The reason this feature is now disabled by default is that it poses a
       potential XSS (Cross Site Scripting) security risk.

       The reason this feature is now deprecated is that in an ideal world
       developers shouldn't have to flatten objects and	hashes in order	to
       make them available to their templates. They should be able to pass the
       query object (or	another	object such as a config	object)	directly into
       the template:

	   $template->param(
	       'query' => $self->query,
	       'cfg'   => $self->cfg,
	       'ENV'   => $ENV,
	   );

       And in the template retrieve parameters directly:

	   your	username: [% query.param('username') %]
	   administrator: [% cfg.admin %]
	   hostname:	  [% ENV.SERVER_NAME %]

       This approach works with	Template::Toolkit, Petal, and
       HTML::Template::Pluggable (via the HTML::Template::Plugin::Dot plugin).

       Note that "associate" and "associate_query" are not compatible.	So if
       you want	to associate the query and an additional object, pass a	list
       to "associate":

	   $template->config(
	       HTMLTemplate => {
		   associate =>	[$self->query, $self->conf]
	       }
	   );

   load
       Create a	new template object and	configure it.

       This can	be as simple (and magical) as:

	   my $template	= $self->template->load;

       When you	call "load" with no parameters,	it uses	the default template
       type, the default template configuration, and it	determines the name of
       the template based on the name of the current run mode.	It determines
       the current run mode by calling "$self->get_current_runmode".

       If you want to have the current runmode updated when you	pass control
       to another runmode, use the CGI::Application::Plugin::Forward module:

	   use CGI::Application::Plugin::Forward;

	   sub first_runmode {
	       my $self	= shift;
	       return $self->forward('second_runmode');
	   }
	   sub second_runmode {
	       my $self	= shift;
	       my $template = $self->template->load;  #	loads 'second_runmode.html'
	   }

       If instead you call "$self->other_method" directly, the value of
       "$self->get_current_runmode" will not be	updated:

	   sub first_runmode {
	       my $self	= shift;
	       return $self->other_method;
	   }
	   sub other_method {
	       my $self	= shift;
	       my $template = $self->template->load;  #	loads 'first_runmode.html'
	   }

       If you want to override the way the default template filename is
       generated, you can do so	with the "template_filename_generator"
       configuration parameter.

       If you call "load" with one paramter, it	is taken to be either the
       filename	or a reference to a string containing the template text:

	   my $template	= $self->template->load('somefile');
	   my $template	= $self->template->load(\$some_text);

       If the parameter	"auto_add_template_exension" is	true, then the
       appropriate extension will be added for this template type.

       If you call "load" with more than one parameter,	then you can specify
       filename	and configuration paramters directly:

	   my $template	= $self->template->load(
	       file			   => 'some_file.tmpl',
	       type			   => 'HTMLTemplate',
	       auto_add_template_extension => 0,
	       add_include_paths	   => '..',
	       HTMLTemplate => {
		   die_on_bad_params =>	1,
	       },
	   );

       To initialize the template from a string	rather than a file, use:

	   my $template	= $self->template->load(
	       string =>  \$some_text,
	   );

       The configuration parameters you	pass to	"load" are merged with the
       configuration that was passed to	"config".

       You can include any of the configuration	parameters that	you can	pass
       to config, plus the following extra parameters:

       file
	   If you are loading the template from	a file,	then the "file"
	   parameter contains the template's filename.

       string
	   If you are loading the template from	a string, then the "string"
	   parameter contains the text of the template.	 It can	be either a
	   scalar or a reference to a scalar.  Both of the following will
	   work:

	       # passing a string
	       my $template = $self->template->load(
		   string => $some_text,
	       );

	       # passing a reference to	a string
	       my $template = $self->template->load(
		   string => \$some_text,
	       );

       add_include_paths
	   Additional include paths.  These will be merged with
	   "include_paths" before being	passed to the template driver.

       The "load" method returns a template driver object.  See	below under
       "DRIVER METHODS", for how to use	this object.

   fill
       Fill is a convenience method which in a single step creates the
       template, fills it with the template paramters and returns its output.

       You can call it with or without a filename (or string ref).

       The code:

	   $self->template->fill('filename', \%params);

       is equivalent to:

	   my $template	= $self->template->load('filename');
	   $template->output(\%params);

       And the code:

	   $self->template->fill(\$some_text, \%params);

       is equivalent to:

	   my $template	= $self->template->load(\$some_text);
	   $template->output(\%params);

       And the code:

	   $self->template->fill(\%params);

       is equivalent to:

	   my $template	= $self->template->load;
	   $template->output(\%params);

       And the code:

	   $self->template->fill('filename');

       is equivalent to:

	   my $template	= $self->template->load('filename');
	   $template->output;

       And the code:

	   $self->template->fill(\$some_text);

       is equivalent to:

	   my $template	= $self->template->load(\$some_text);
	   $template->output;

       And the code:

	   $self->template->fill;

       is equivalent to:

	   my $template	= $self->template->load;
	   $template->output;

   process
       "process" is an alias for "fill".

APPLICATION METHODS
       These methods are called	directly on your application's $self object.

   load_tmpl
       This is an emulation of CGI::Application's built-in "load_tmpl" method.
       For instance:

	   $self->load_tmpl('some_template.html');

       It is not exported by default.  To enable it, use:

	   use CGI::Application::Plugin::AnyTemplate qw/:load_tmpl/;

       You can call it the same	way as documented in "CGI::Application"	and it
       will have the same effect.  However, it will respect the	current
       template	"type",	so you can still use it	to fill	templates of different
       backends.

       The idea	is that	you can	take an	existing CGI::Application-based	webapp
       which uses "HTML::Template" templates, and add the following code to
       it:

	   use CGI::Application::Plugin::AnyTemplate qw/:load_tmpl/;

	   sub setup {
	       my $self	= shift;
	       $self->template->config(type => TemplateToolkit);
	   }

       This will change	all existing calls to load_tmpl	within your
       application to use Template::Toolkit based templates.

       Calling:

	   my $template	= $self->load_tmpl('some_template.html');

       It is the equivalent of calling:

	   my $template	= $self->template->load(
	       file => 'some_template.html',
	       auto_add_template_extension => 0,
	   );

       If you add extra	options	to "load_tmpl",	these will be assumed to be
       HTML::Template specific options,	with the exception of the "path"
       option, which will be extracted and used	as 'add_include_paths':

	   my $template	= $self->load_tmpl('some_template.html',
	       cache =>	0,
	       path  =>	'/path/to/templates',
	   );

       This will get translated	into:

	   my $template	= $self->template->load(
	       file => 'some_template.html',
	       auto_add_template_extension => 0,
	       add_include_paths => '/path/to/templates',
	       HTMLTemplate => {
		   cache => 0,
	       }
	   );

       Note that if you	specify	any HTML::Template-specific options here, they
       will completely overwrite any options that you passed to	config.

       Some notes and caveats about using the "load_tmpl" method:

       o   This	method only works for the default template configuration (i.e.
	   "$self->template()").  If you set up	a named	configuration (e.g.
	   "$self->template('myconfig')") there	is no way to access it with
	   "load_tmpl".	 Since plugins should be using named configurations,
	   this	means that the "load_tmpl" method should not be	used by
	   plugins.  See "NOTES	FOR AUTHORS OF PLUGINS AND REUSABLE
	   APPLICATIONS", below.

       o   The "load_tmpl" method does not automatically add an	extension to
	   the filename	you pass to it,	even if	you have
	   "auto_add_template_extension" set to	a true value in	your call to
	   "$self->template->config".

       o   The "load_tmpl" method ignores always returns a string, not a
	   reference to	a string.  It ignores the setting of the
	   "returns_references"	option.

   tmpl_path
       You can set the template	"include_paths"	by calling
       "$self->tmpl_path('/path/to/templates')".

       You can also do so by passing a value to	the "TMPL_PATH"	parameter to
       your application's "new"	method:

	   my $webapp =	App->new(
	       TMPL_PATH => '/path/to/templates',
	   );

       Paths that you set via "tmpl_path"/"TMPL_PATH" will be put last in the
       list of include paths, after "add_include_paths"	and "include_paths".

DRIVER METHODS
       These are the most commonly used	methods	of the "AnyTemplate" driver
       object.	The driver is what you get back	from calling
       "$self->template->load".

   param
       The "param" method gets and sets	values within the template.

	   my $template	= $self->template->load;

	   my @param_names = $template->param();

	   my $value = $template->param('name');

	   $template->param('name' => 'value');
	   $template->param(
	       'name1' => 'value1',
	       'name2' => 'value2'
	   );

       It is designed to behave	similarly to the "param" method	in other
       modules like CGI	and HTML::Template.

   get_param_hash
       Returns the template variables as a hash	of names and values.

	   my %params	  = $self->template->get_param_hash;

       In a scalar context, returns a reference	to the hash used internally to
       contain the values:

	   my $params_ref = $self->template->get_param_hash;

	   $params_ref->{'foo'}	= 'bar';  # directly change parameter 'foo'

   output
       Returns the template with all the values	filled in.

	   return $template->output;

       You can also supply names and values to the template at this stage:

	   return $template->output('name' => 'value', 'name2' => 'value2');

       If "return_references" option is	set to true, then the return value of
       "output"	will be	a reference to a string.  If the "return_references"
       option is false,	then a copy of the string will be returned.  By
       default "return_references" is true.

       When you	call the "output" method, any components embedded in the
       template	are run.  See "EMBEDDED	COMPONENTS", below.

PRE- AND POST- PROCESS
       There are several ways to customize the template	process.  You can
       modify the template parameters before the template is filled, and you
       can modify the output of	the template after it has been filled.

       Multiple	applications and plugins can hook into the template process
       pipeline, each making changes to	the template input and output.

       For instance, it	will be	possible to make a general-purpose
       "CGI::Application" plugin that adds arbitrary data to each new template
       (such as	query parameters or configuration data).

       Note that the API has changed for version 0.10 in a non-backwards-
       compatible way in order to use the new hook system provided by recent
       versions	of "CGI::Application".

   The load_tmpl hook
       The "load_tmpl" hook is designed	to be compatible with the "load_tmpl"
       hook defined by "CGI::Application" itself.

       The "load_tmpl" hook is called before the template object is created.
       Any callbacks that you register to this hook will be called before each
       template	is loaded.  Register a "load_tmpl" callback with:

	  $self->add_callback('load_tmpl',\&my_load_tmpl);

       When the	"load_tmpl" callback is	executed it will be passed three
       arguments (adapted from the CGI::Application docs):

	1. A hash reference of the extra params	passed into C<load_tmpl>
	   (ignored by AnyTemplate with	the exception of 'path')

	2. Followed by a hash reference	to template parameters.
	   You can modify this hash by reference to affect values that are
	   actually passed to the param() method of the	template object.

	3. The name of the template file.

       Here's an example stub for a load_tmpl()	callback:

	   sub my_load_tmpl_callback {
	       my ($self, $ht_params, $tmpl_params, $tmpl_file)	= @_;
	       # modify	$tmpl_params by	reference...
	   }

       Currently, of all the params in $ht_params, all but 'path' are ignored,
       because these are specific to "HTML::Template".	If you want to write a
       generic callback	that needs to be able to access	or modify
       "HTML::Template"	parameters then	let me know, or	add a feature request
       on <http://rt.cpan.org>.

       The "path" param	of $ht_params is initially set to the value of
       "add_include_paths" (if set).  Your callback can	modify the "path"
       param, and "add_include_param" will be set to the result.

       Plugin authors who want to provide template processing features are
       encouraged to use the 'load_tmpl' hook when possible, since it will
       work both with AnyTemplate and with CGI::Application's built-in
       "load_tmpl".

   The template_pre_process and	template_post_process hooks
       Before the template output is generated,	the "template_pre_process"
       hook is called.	Any callbacks that you register	to this	hook will be
       called before each template is processed.  Register a
       "template_pre_process" callback as follows:

	   $self->add_callback('template_pre_process', \&my_tmpl_pre_process);

       Pre-process callbacks will be passed a reference	to the $template
       object, and can can modify the parameters passed	into the template by
       using the "param" method:

	   sub my_tmpl_pre_process {
	       my ($self, $template) = @_;

	       # Change	the internal template parameters by reference
	       my $params = $template->get_param_hash;

	       foreach my $key (keys %$params) {
		   $params{$key} = to_piglatin($params{$key});
	       }

	       # Can also set values using the param method
	       $template->param('foo', 'bar');

	   }

       After the template output is generated, the "template_post_process"
       hook is called.	You can	register a "template_post_process" callback as
       follows:

	   $self->add_callback('template_post_process',	\&my_tmpl_post_process);

       Any callbacks that you register to this hook will be called after each
       template	is processed, and will be passed both a	reference to the
       template	object and a reference to the output generated by the
       template.  This allows you to modify the	output of the template:

	   sub my_tmpl_post_process {
	       my ($self, $template, $output_ref) = @_;

	       $$output_ref =~ s/foo/bar/;
	   }

EMBEDDED COMPONENTS
   Introduction
       "CGI::Application::Plugin::AnyTemplate" allows you to include
       application components within your templates.

       For instance, you might include a header	component a the	top of every
       page and	a footer component at the bottom of every page.

       These componenets are actually first-class run modes.  When the
       template	engine finds a special tag marking an embedded component, it
       passes control to the run mode of that name.  That run mode can then do
       whatever	a normal run mode could	do.  But typically it will load	its
       own template and	return the template's output.

       This output returned from the embedded run mode is inserted into	the
       containing template.

       The syntax for embed components is specific to each type	of template
       driver.

   Syntax
       HTML::Template syntax:

	   <TMPL_VAR NAME="CGIAPP_embed('some_run_mode')">

       HTML::Template::Expr syntax:

	   <TMPL_VAR EXPR="CGIAPP_embed('some_run_mode')">

       HTML::Template::Pluggable syntax:

	   <TMPL_VAR EXPR="cgiapp.embed('some_run_mode')">

       Template::Toolkit syntax:

	   [% CGIAPP.embed("some_run_mode") %]

       Petal syntax:

	   <span tal:replace="structure	CGIAPP/embed 'some_run_mode'">
	       this text gets replaced by the output of	some_run_mode
	   </span>

   Getting Template Variables from the Containing Template
       The component run mode is passed	a reference to the template object
       that contained the component.  The component run	mode can use this
       object to access	the params that	were passed to the containing
       template.

       For instance:

	   sub header {
	       my ($self, $containing_template,	@other_params) = @_;

	       my %tmplvars = (
		   'title' => 'My glorious home	page',
	       );

	       my $template = $self->template->load;

	       $template->param(%tmplvars, $containing_template->get_param_hash);
	       return $template->output;
	   }

       In this example,	the template values of the enclosing template would
       override	any values set by the embedded component.

   Passing Parameters
       The template can	pass parameters	to the target run mode.	 These are
       passed in after the reference to	the containing template	object.

       Parameters can either be	literal	strings, specified within the template
       text, or	they can be keys that will be looked up	in the template's
       params.

       Literal strings are enclosed in double or single	quotes.	 Param keys
       are barewords.

       HTML::Template syntax:

	   <TMPL_VAR NAME="CGIAPP_embed('some_run_mode', param1, 'literal string2')">

       Note that HTML::Template	doesn't	support	this type of callback natively
       and that	this behaviour is emulated by the HTMLTemplate driver see the
       docs to CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplate for
       limitations to the emulation.

       HTML::Template::Expr syntax:

	   <TMPL_VAR EXPR="CGIAPP_embed('some_run_mode', param1, 'literal string2')">

       HTML::Template::Pluggable syntax:

	   <TMPL_VAR EXPR="cgiapp.embed('some_run_mode', param1, 'literal string2')">

       Template::Toolkit syntax:

	   [% CGIAPP.embed("some_run_mode", param1, 'literal string2' )	%]

       Petal syntax:

	   <span tal:replace="structure	CGIAPP/embed 'some_run_mode' param1 'literal string2' ">
	       this text gets replaced by the output of	some_run_mode
	   </span>

NOTES FOR AUTHORS OF PLUGINS AND REUSABLE APPLICATIONS
       If you are writing a CGI::Application plugin module, or you are writing
       a "CGI::Application" program that will be distributed to	other people
       (e.g. on	CPAN), then it's important to take steps to prevent your
       application's use of CGI::Application::Plugin::AnyTemplate from
       conflicting with	other plugins or with your end users.

       When a plugin that uses CGI::Application::Plugin::AnyTemplate calls:

	  $self->template->config(...)

       It overwrites any existing template configuration with the new
       settings.  So if	two plugins do that, they probably clobber each	other.

       However,	CGI::Application::Plugin::AnyTemplate has the feature of named
       independent configs:

	  $self->template('your_module')->config(...)
	  $self->template('my_plugin')->config(...)

       These configs remain separate from each other.  However,	you have to
       keep using these	names throughout your module, even when	you load and
       fill the	template.  For instance:

	  sub my_runmode {
	      my $self = shift;
	      my $template = $self->template('my_plugin')->load;
	      $template->output;
	  }

	  sub your_runmode {
	      my $self = shift;
	      my %params;
	      $self->template('your_module')->fill(\%params);
	  }

       It's uglier and more verbose, but it also prevents plugins from
       stepping	on each	other's	toes.

       CGI::Application	plugins	that use CGI::Application::Plugin::AnyTemplate
       should default to using their own package name for the AnyTemplate
       config name:

	  $self->template(__PACKAGE__)->config(...);
	  $self->template(__PACKAGE__)->fill(...);

CHANGING THE NAME OF THE 'template' METHOD
       If you want to access the features of this module using a method	other
       than "template",	you can	do so via Anno Siegel's	Exporter::Renaming
       module (available on CPAN).

       For instance, to	use syntax similar to CGI::Application::Plugin::TT:

	   use Exporter::Renaming;
	   use CGI::Application::Plugin::AnyTemplate Renaming => [ template => tt];

	   sub cgiapp_init {
	       my $self	= shift;

	       my %params = ( ... );

	       # Set config file and other options
	       $self->tt->config(
		   default_type	=> 'TemplateToolkit',
	       );

	   }

	   sub my_runmode {
	       my $self	= shift;
	       $self->tt->process('file', \%params);
	   }

       And to use syntax similar to CGI::Application's "load_tmpl" mechanism:

	   use Exporter::Renaming;
	   use CGI::Application::Plugin::AnyTemplate Renaming => [ template => tmpl];

	   sub cgiapp_init {
	       my $self	= shift;

	       # Set config file and other options
	       $self->tmpl->config(
		   default_type	=> 'HTMLTemplate',
	       );

	   }

	   sub my_runmode {
	       my $self	= shift;

	       my %params = ( ... );

	       my $template = $self->tmpl->load('file');
	       $template->param(\%params);
	       $template->output;
	   }

AUTHOR
       Michael Graham, "<mgraham@cpan.org>"

ACKNOWLEDGEMENTS
       I originally wrote this to be a subsystem in Richard Dice's
       CGI::Application-based framework, before	I moved	it into	its own
       module.

       Various ideas taken from	CGI::Application (Jesse	Erlbaum),
       CGI::Application::Plugin::TT (Cees Hek) and "Text::Boilerplate"
       (Stephen	Nelson).

       "Template::Toolkit" singleton support code stolen from
       CGI::Application::Plugin::TT.

BUGS
       Please report any bugs or feature requests to
       "bug-cgi-application-plugin-anytemplate@rt.cpan.org", or	through	the
       web interface at	<http://rt.cpan.org>.  I will be notified, and then
       you'll automatically be notified	of progress on your bug	as I make
       changes.

SOURCE
       The source code repository for this module can be found at
       http://github.com/mgraham/CAP-AnyTemplate/

SEE ALSO
	   CGI::Application::Plugin::AnyTemplate::Base
	   CGI::Application::Plugin::AnyTemplate::ComponentHandler
	   CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplate
	   CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplateExpr
	   CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplatePluggable
	   CGI::Application::Plugin::AnyTemplate::Driver::TemplateToolkit
	   CGI::Application::Plugin::AnyTemplate::Driver::Petal

	   CGI::Application

	   Template::Toolkit
	   HTML::Template

	   HTML::Template::Pluggable
	   HTML::Template::Plugin::Dot

	   Petal

	   Exporter::Renaming

	   CGI::Application::Plugin::TT

COPYRIGHT & LICENSE
       Copyright 2005 Michael Graham, All Rights Reserved.

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

perl v5.32.1			  2021CGI::Application::Plugin::AnyTemplate(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | APPLICATION METHODS | DRIVER METHODS | PRE- AND POST- PROCESS | EMBEDDED COMPONENTS | NOTES FOR AUTHORS OF PLUGINS AND REUSABLE APPLICATIONS | CHANGING THE NAME OF THE 'template' METHOD | AUTHOR | ACKNOWLEDGEMENTS | BUGS | SOURCE | SEE ALSO | COPYRIGHT & LICENSE

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

home | help