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

FreeBSD Manual Pages


home | help
CGI::Builder::TT2(3)  User Contributed Perl Documentation CGI::Builder::TT2(3)

       CGI::Builder::TT2 - CGI::Builder	and Template Toolkit 2 integration

	       CGI::Builder    >= 1.12
	       Template	       >= 2.0

	       perl -MCPAN -e 'install CGI::Builder::TT2'

       Standard	installation
	   From	the directory where this file is located, type:

	       perl Makefile.PL
	       make test
	       make install

	   # just include it in	your build

	   use CGI::Builder
	   qw| CGI::Builder::TT2

       This module transparently integrates "CGI::Builder" and "Template" in a
       very handy, powerful and	flexible framework that	can save you a lot of
       coding, time and	resources.

       With this module, you don't need	to produce the "page_content" within
       your page handlers anymore (unless you want to);	you don't even need to
       manage a	template system	yourself (unless you want to).

       If you use a template system on your own	(i.e. not integrated in	a CBF
       extension), you will have to write all this code	explicitly:

       o   create a page handler for each page as usual

       o   create a new	template object	and assign a new template file

       o   find	the runtime values and assign them to the template object

       o   run the template process and	set the	"page_content" to the produced

       You can save all	that by	just including this module in your build,
       because it implements an	internal transparent and automatic template
       system that even	without	your explicit intervention is capable of
       finding the correct template and	the correct runtime values to fill it,
       and generates the page_content automagically. With this module you can
       even eliminate the page handlers	that are just setting the
       page_content, because the page is automatically sent by the template

       There's an extended example in the directory "example/" of the module
       distribution. Anyway, here a snippet to get the general idea:

	   package WebApp;
	   use CGI::Builder qw/	CGI::Builder::TT2 /;

	   sub PH_index
	       my $self	= shift;

	       $self->tt_vars( environment => \%ENV );

       Here's the template:

	       <meta http-equiv=content-type content="text/html;charset=iso-8859-1">
	       <title>A	random example :)</title>
	       [% FOREACH k IN environment.keys	%]
		   <td>[% k %]</td>
		   <td>[% environment.$k %]</td>
	       [% END %]

       This is just one	of the styles you can adopt with CGI::Builder::TT2.
       Read further.

   How it works
       This module implements a	default	value for the "page_content" property:
       a CODE reference	that produces and print	the page content by using an
       internal	"Template" object.

       Since the "page_content"	property is set	to its own default value
       before the page handler is called, the page handler can completely (and
       usually should) avoid to	produce	any output.

	   sub PH_myPage
	     ... do_something_useful ...
	     ... no_need_to_set_page_content ...
	     ... returned_value_will_be_ignored	...

       This module just	calls the page handler related with the	"page_name",
       but it does not expect any returned value from it.

       The output will be generated internally by the merger of	the template
       file and	the runtime values that	are looked up from the
       "FooBar::Lookup"	package	('FooBar' is not literal, but stands for your
       application namespace plus the '::Lookups' string).

       In simplest cases you can also avoid to create the page handler for
       certain pages: by default the template with the same page name will be
       used to produce the output.

       This does not mean that you cannot do things otherwise when you need
       to.  Just create	a page handler and add there all the properties	you
       want, or	set those you want to override:

	  sub PH_mySpecialPage
	    my $s = shift ;
	       special_key	    => 'that' ,
	       another_special_keys => 'this'
	    ) ;
	    $s->tt_template = '/that/special/template.tt2' ;

       Since the page handler adds values to the "tt_vars" properties group,
       and sets	the "tt_template" property, the	application will add those
       values to the (possibly empty) template variables set, and the template
       system will print with a	specific template and not with the default

       If some page handler needs to produce the output	on its own (completely
       bypassing the template system) it can do	so by setting the
       "page_content" property as usual	(i.e. with the page content or with a
       reference to it)

	  sub PH_mySpecialPage
	    my $s = shift ;
	     ... do_something_useful ...
	    # will bypass the template system
	    $s->page_content  =	'something';
	    $s->page_content .=	'something more';

       For the 'mySpecialPage' page, the application will not use the template
       system at all, because the "page_content" property was set to the

       Note: For former	CGI::Application users:	the returned value of any page
       handler will be ALWAYS ignored, so set explicitly the "page_content"
       property	when needed.

       These features mimics the mechanisms implemented	in
       CGI::Builder::Magic, to provide another way to pass variables to	the
       templates. A way	that CGI::Builder users	could be familiar with.

       *::Lookups package

       This is a special package that your application should define to	allow
       the object to auto-magically look up the	run time values.

       The name	of this	package	is contained in	the "tt_lookups_package"
       property.  The default value for	this property is 'FooBar::Lookup'
       where 'FooBar' is not literal, but stands for your CBB namespace	plus
       the '::Lookups' string, so if you define	a CBB package as 'WebApp' you
       should define a 'WebApp::Lookups' package too (or set the
       "tt_lookup_package" property with the name of the package you will use
       as the lookup).

       In this package you should define all the variables and subs needed to
       supply any runtime value	that will be substituted in place of the
       matching	label or block in any template.

       The lookup is confined to the *::Lookups	package	on purpose. It would
       be simpler to use the same CBB package, but this	would extend the
       lookup to all the properties, methods and handlers of your CBB and this
       might cause conflict and	security holes.	So, by just adding one line to
       your CBB, (e.g. 'package	FooBar::Lookups;') you can separate your CBB
       from the	lookup-allowed part of it.

       Note: Obviously you can also put	the *::Lookup package in its own '.pm'
       file, thus making it simply loadable from different CBBs.

   The Template	syntax
       This module implements a	"Template" object, so the used "tags" are the
       default Template	tags e.g.:

	   [% FOREACH item IN array %]
	     [%	item %]
	   [% END %]

       Please, read Template::Manual.

   How to organize your	CBB
       1.  Set all the actions common to all pages in the "OH_init()" handler
	   (as usual)

       2.  Prepare a template for each page addressed by your application

       3.  Set the variables or	the subs in the	*::Lookups package that	will
	   be available	to the internal	"Template" object (that	could be
	   picked up by	one or more templates processing)

       4.  Define just the page	handlers that needs to do something special

       5.  Use the properties default values, that can save you	a lot of time

       This module adds	some template properties (all those prefixed with
       'tt_') to the standard CBF properties. The default of these properties
       are usually smart enough	to do the right	job for	you, but you can fine-
       tune the	behavior of your CBB by	setting	them to	the value you need.

       This property group accessor allows you to set the variables that will
       be available in the template. If	one of these variables has the same
       name of a variable that's in the	lookups	package, it will be
       overridden.  You	can pass any type of scalar value to the templates:
       numbers,	strings	and any	type of	references. Subroutines	passed to the
       template	in this	way, when called, will receive a reference to the
       application object as their first argument. E.g.:

	   package WebApp;
	   use CGI::Builder qw/	CGI::Builder::TT2 /;

	   sub foo
	       my $app	 = shift;
	       my $param = shift;

	       # $app IS A 'Webapp'
	       # $param's value	is 'bar'

	   sub PH_index
	       my $self	= shift;

	       $self->tt_vars( my_sub => \&foo );

       And this	is the corresponding template:

	   [% my_sub( 'bar' ) %]

       Moreover, every template	will receive a reference to the	CBF object in
       the variable "CBF", with	no action required to the programmer.  It
       should be noted that it's a good	software practice to separate
       application logic from visualization logic: calling application methods
       from the	template could drive to	situations of coupling between these
       two aspects. But	we will	apply Perl's philosophy, giving	rope to	the
       programmer even if he could hang	himself	with it

       This property allows you	to access and set the name of the package
       where the Template object. The default value for	this property is
       'FooBar::Lookup'	where 'FooBar' is not literal, but stands for your
       application namespace plus the '::Lookups' string. (i.e.

       This property allows you	to access and set the 'template' argument
       passed to the Template "process()" method. Set This property to an
       absolute	path if	you want bypass	the "page_path"	property.

   CBF changed property	defaults
       CBF page_suffix

       This module sets	the default of the "page_suffix" to '.tt2'. You	can
       override	it by just setting another suffix of your choice.

       CBF page_content

       This module sets	the default of the "page_content" to a CODE reference
       that produces the page content by using an internal Template object
       (see also "How it works"). If you want to bypass	the template system in
       any Page	Handler, just explicitly set the "page_content"	to the content
       you want	to send.

       In this section you can find all	the most advanced or less used
       features	that document all the details of this module. In most cases
       you don't need to use them, anyway, knowing them	will not hurt.

       This property returns the internal "Template" object.

       This is not intended to be used to generate the page output - that is
       generated automatically - but it	could be useful	to generate other
       outputs (e.g. messages for sendmail) by using the same template object,
       thus preserving the same	arguments.

       Note: You can change the	default	arguments of the object	by using the
       "tt_new_args" property, or you can completely override the creation of
       the internal object by overriding the "tt_new()"	method.

       This method is not intended to be used directly in your CBB. It is used
       internally to initialize	and return the "Template" object. You can
       override	it if you know what you	are doing, or you can simply ignore it

   tt_new_args(	arguments )
       This property group accessor handles the	Template constructor arguments
       that are	used in	the creation of	the internal Template object. Use it
       to finetune the behavior	if you know what are doing.  By	default, only
       one option is set: "INCLUDE_PATH	=" [ $_[0]->page_path ]>.

       Note: You can completely	override the creation of the internal object
       by overriding the "tt_new()" method.

       Even if this module has not been	written	by Domizio Demichelis, you can
       find support via	the mailing list, which	I read daily: I'll try to
       respond as soon as possible. Moreover, if the question involve
       CGI::Builder issues, you	could receive a	reply from CGI::Builder's
       author himself.	The list is used for general support on	the use	of the
       CBF, announcements, bug reports,	patches, suggestions for improvements
       or new features.	The API	to the CBF is stable, but if you use the CBF
       in a production environment, it's probably a good idea to keep a	watch
       on the list.

       You can join the	CBF mailing list at this url:

       Many thanks to Domizio Demichelis, author of the	CGI::Builder
       framework, who helped me	during the development of this module with
       prompt explanations, insightful advices and patience.

       Stefano Rodighiero, <> (<>)

       Vince Veselosky (<>) - Contributed with	many
       ideas, comments and clever solutions to daunting	problems. And the
       extended	example, too.

       (c) 2004	by Stefano Rodighiero <>

       All Rights Reserved. This module	is free	software. It may be used,
       redistributed and/or modified under the same terms as perl itself.

perl v5.32.1			  2004-06-24		  CGI::Builder::TT2(3)


Want to link to this manual page? Use this URL:

home | help