cgi::application::plugin::anytemplate::componenthandler(3pm) [debian man page]

CGI
::Application::Plugin::AnyTemplate::ComponentHandler(User Contributed Perl DocumentCGI::Application::Plugin::AnyTemplate::ComponentHandler(3pm)

NAME

       CGI::Application::Plugin::AnyTemplate::ComponentHandler - Embed run modes within a template

DESCRIPTION

       This is a little helper module used by CGI::Application::Plugin::AnyTemplate to handle finding and running the run modes for embedded
       components, and returning their content.

       You shouldn't need to use this module directly unless you are adding support for a new template system.

       For information on embedded components see the docs of CGI::Application::Plugin::AnyTemplate.

METHODS

       new Creates a new "CGI::Application::Plugin::AnyTemplate::ComponentHandler" object.

	       my $component_handler = CGI::Application::Plugin::AnyTemplate::ComponentHandler->new(
		   webapp	       => $webapp,
		   containing_template => $template,
	       );

	   The "webapp" parameter should be a reference to a "CGI::Application" object.

	   The "containing_template" parameter should be a reference to the template object in which this component is embedded.

       embed
	   Runs the specified "runmode" of the "webapp" object.  Returns the results of this call.

	   Parameters passed to embed should be passed on to the run mode.

	   If the results are a scalar reference, then the return value is dereferenced before returning.  This is the safest way of calling a run
	   mode since you'll get the output as a string and return it as a string, but it involves returning potentially very large strings from
	   subroutines.

       embed_direct
	   Runs the specified "runmode" of the "webapp" object.  Returns the results of this call.

	   Parameters passed to embed_direct should be passed on to the run mode.

	   Even if the result of this call is a scalar reference, the result is NOT dereferenced before returning it.

	   If you call this method instead of embed, you should be careful to deal with the possibility that your results are a reference to a
	   string and not the string itself.

AUTHOR

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

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.10.1							    2010-12-16	      CGI::Application::Plugin::AnyTemplate::ComponentHandler(3pm)

CGI
::Application::Plugin::AnyTemplate::Driver::TemplateTUseriContributed Perl DCGI::Application::Plugin::AnyTemplate::Driver::TemplateToolkit(3pm)

NAME

       CGI::Application::Plugin::AnyTemplate::Driver::TemplateToolkit - Template::Toolkit plugin to AnyTemplate

DESCRIPTION

       This is a driver for CGI::Application::Plugin::AnyTemplate, which provides the implementation details specific to rendering templates via
       the Template::Toolkit templating system.

       All "AnyTemplate" drivers are designed to be used the same way.	For general usage instructions, see the documentation of
       CGI::Application::Plugin::AnyTemplate.

EMBEDDED COMPONENT SYNTAX (Template::Toolkit)
       The Template::Toolkit syntax for embedding components is:

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

       This can be overridden by the following configuration variables:

	   embed_tag_name	# default 'CGIAPP'

       For instance by setting the following values in your configuration file:

	   embed_tag_name	'MYAPP'

       Then the embedded component tag will look like:

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

TT OBJECT CACHING (singleton support)
   Introduction
       In a persistent environment, rather than creating a Template::Toolkit object each time you fill a template, it is much more efficient to
       load a single Template::Toolkit object and use this object to render all of your templates.

       However, in a persistent environment, you may have several different applications running, and they all might need to set different
       Template::Toolkit options (such as "POST_CHOMP", etc.).

       By default, when the "TemplateToolkit" driver creates a Template::Toolkit object, it caches it.	From that point on, whenever the same
       application needs a Template::Toolkit object, the driver uses the cached object rather than creating a new one.

   Multiple Applications in a Shared Persistent Environment
       An attempt is made to prevent different applications from sharing the same TT object.

       Internally, the TT objects are stored in a private hash keyed by the web application's class name.

       You can explicitly specify the class name when you call "config":

	       $self->template->config(
		   type 	 => 'TemplateToolkit',
		   TemplateToolkit => {
		       storage_class => 'My::Project',
		   },
	       );

       If you don't specify the class name, then the package containing the subroutine that called "config" is used.  For instance:

	   package My::Project;
	   sub setup {
	       my $self = shift;
	       $self->template->config( 		# My::Project is used to store
		   type 	 => 'TemplateToolkit',	# cached TT object
	       );
	   }

       A typical "CGI::Application" module hierarchy looks like this:

	   CGI::Application
	       My::Project
		   My::Webapp

       In this hierarchy, it makes sense to store the cached TT object in "My::Project".  To make this happen, either call
       "$self->template->config" from within "My::Project", or explicitly name the "storage_class" when you call "$self->template->config".

   Disabling TT Object Caching
       You can disable Template::Toolkit object caching entirely by providing a false value to the "object_caching" driver config parameter:

	       $self->template->config(
		   type 	 => 'TemplateToolkit',
		   TemplateToolkit => {
		       object_caching => 0,
		   },
	       );

   TT Object Caching and Include Paths
       The "include_paths" driver config parameter is not cached; it is set every time you call "$self->template->load". So you can safely used
       cached TT objects even if the applications sharing the TT object need different "include_paths".

CONFIGURATION

       The CGI::Application::Plugin::AnyTemplate::Driver::TemplateToolkit driver accepts the following config parameters:

       embed_tag_name
	   The name of the tag used for embedding components.  Defaults to "CGIAPP".

       template_extension
	   If "auto_add_template_extension" is true, then CGI::Application::Plugin::AnyTemplate will append the value of "template_extension" to
	   "filename".	By default the "template_extension" is ".xhtml".

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

	   If this config parameter is true, then CGI::Application::Plugin::AnyTemplate::Driver::TemplateToolkit will copy all of the webapp's
	   query params into the template.

	   This is similar to what would happen if you used HTML::Template's "associate" feature with the webapp's query object:

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

	   By default "emulate_associate_query" is false.

       object_caching
	   Whether or not to cache the Template::Toolkit object in a persistent environment

	   By default, "object_caching" is enabled.

	   See "TT OBJECT CACHING (singleton support)", above.

       storage_class
	   What class to use as the storage key when object caching is enabled.

	   By default, "storage_class" defaults to the package containing the subroutine that called "$self->template->config".

	   See "TT OBJECT CACHING (singleton support)", above.

       All other configuration parameters are passed on unchanged to Template::Toolkit.

CONFIGURING UTF-8 TEMPLATES
       "AnyTemplate" does NOT support Template::Toolkit's "binmode" option at runtime:

	   # not possible with AnyTemplate
	   $tt->process($infile, $vars, $outfile, { binmode => 1 })
	       || die $tt->error(), "
";

	   # not possible with AnyTemplate
	   $tt->process($infile, $vars, $outfile, binmode => 1)
	       || die $tt->error(), "
";

	   # not possible with AnyTemplate
	   $tt->process($infile, $vars, $outfile, binmode => ':utf8')
	       || die $tt->error(), "
";

       Instead, use the "ENCODING" option in the initial config:

	   $self->template->config(
	       default_type => 'TemplateToolkit',
	       TemplateToolkit => {
		   ENCODING => 'UTF-8'
	       }
	   );

       If you have a mix of encodings in your templates, use a separate "AnyTemplate" configuration for each encoding:

	   $self->template('ascii')->config(
	       default_type => 'TemplateToolkit',
	   );
	   $self->template('utf-8')->config(
	       default_type => 'TemplateToolkit',
	       TemplateToolkit => {
		   ENCODING => 'UTF-8'
	       }
	   );

   required_modules
       The "required_modules" function returns the modules required for this driver to operate.  In this case: "Template".

DRIVER METHODS

       initialize
	   Initializes the "TemplateToolkit" driver.  See the docs for CGI::Application::Plugin::AnyTemplate::Base for details.

       render_template
	   Fills the Template::Toolkit object with "$self->param"

	   If the param "emulate_associate_query" is true, then set params for each of $self->{'webapp'}->query, mimicking HTML::Template's
	   associate mechanism.

	   Also set up a CGI::Application::Plugin::AnyTemplate::ComponentHandler object so that the "CGIAPP.embed" callback will work.

	   Returns the output of the filled template as a string reference.

	   See the docs for CGI::Application::Plugin::AnyTemplate::Base for details.

SEE ALSO

	   CGI::Application::Plugin::AnyTemplate
	   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::Petal

	   CGI::Application

	   Template::Toolkit
	   HTML::Template

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

	   Petal

	   Exporter::Renaming

	   CGI::Application::Plugin::TT

ACKNOWLEDGEMENTS

       Thanks to Cees Hek for discussing the issues of caching in a persistent environment.  And also for his excellent
       CGI::Application::Plugin::TT module, from which I stole ideas and some code:  especially the bit about how to change the include path in a
       TT object after you've initialized it.

AUTHOR

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

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.10.1							    2010-12-16 CGI::Application::Plugin::AnyTemplate::Driver::TemplateToolkit(3pm)