CGI::Builder::HTMLtmpl - CGI::Builder and HTML::Template integration
To have the complete list of all the extensions of the CBF, see "Extensions List" in CGI::Builder
CGI::Builder >= 1.0 HTML::Template >= 2.6
perl -MCPAN -e 'install CGI::Builder::HTMLtmpl'
You have also the possibility to use the Bundle to install all the extensions and prerequisites of the CBF in just one step. Please, notice that the Bundle will install A LOT of modules that you might not need, so use it specially if you want to extensively try the CBF.
perl -MCPAN -e 'install Bundle::CGI::Builder::Complete'
From the directory where this file is located, type:
perl Makefile.PL make make test make install
use CGI::Builder qw| CGI::Builder::HTMLtmpl ... |;
Note: You should know CGI::Builder.
This module transparently integrates CGI::Builder and HTML::Template in a very handy and flexible framework that can save you some coding. It provides you a mostly automatic template system based on HTML::Template: usually you will have just to supply the run time values to the object and this extension will manage automatically all the other tasks of the page production process (such as generating the output and setting the page_content property).
CGI::Builder
HTML::Template
page_content
Note: With this extension you don't need to explicitly set the page_content to the output of your template object (ht->output()) in your Page Handlers, because it will be automatically set. You should explicitly set the page_content property just in case you want to bypass the template system:
ht->output()
# in order to produce the output with the template 'myPage.tmpl', # usually you just need to pass the param to the object sub PH_myPage { my $s = shift; $s->ht_param( something => 'something' ); } # but if you want to completely bypass the template system # just set the page_content sub PH_myPage { my $s = shift; $s->page_content = 'some content'; }
Note: This extension is not as magic and memory saving as the CGI::Builder::Magic template extension, because HTML::Template requires a specific input data structure (i.e. does not allow call back subs unless you use the HTML::Template::Expr), and does not allow to print the output during the process. On the other hand it should be a few milliseconds faster than CGI::Builder::Magic in producing the output.
This is a complete CBB that uses all the default to load the './tm/index.tmpl'template and fill it with a couple of run time values and automatically send the page_content to the client.
package My::WebApp use CGI::Builder qw| CGI::Builder::HTMLtmpl |; sub PH_index { my $s = shift; $s->ht_param( myVar => 'my Variable', myOtherVar => 'other Variable'); } 1;
This is a more complex complete CBB that will automatically send the page_content to the client:
package My::WebApp use CGI::Builder qw| CGI::Builder::HTMLtmpl |; # this will init some properties overriding the default # and adding some option to the ht creation sub OH_init { my $s = shift; $s->page_suffix = '.html'; # override defaults $s->ht_new_args( path => ['/my/path'], # override defaults die_on_bad_params => 0, cache => 1 ); } # this will be called for page 'index' or if no page is specified # it will load the '/my/path/index.html' file (since page_suffix is '.html') # and will fill it with the following variables and send the output() sub PH_index { my $s = shift; $s->ht_param( myVar => 'my Variable', myOtherVar => 'other Variable'); } # this will override the default template for this handler # (i.e. '/my/path/specialPage.html') so loading '/my/path/special.tmp' # template, filling and sending the output as usual sub PH_specialPage { my $s = shift; $s->ht_new_args( filename => 'special.tmp') # override defaults $s->ht_param( mySomething => 'something' ); } 1;
This module adds some template properties (all those prefixed with 'ht_') 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 behaviour of your CBB by setting them to the value you need.
This property group accessor handles the HTML::Template constructor arguments that are used in the creation of the internal HTML::Template object. Use it to change or add the argument you need to the creation of the new object.
It uses the following defaults:
filename
This option is set to the page_name value plus the page_suffix value.
page_name
page_suffix
filename => $s->page_name.$s->page_suffix # when the page_name is 'myPage' # and the page_suffix is the default '.tmpl' # it will be expanded to; filename => 'myPage.tmpl'
path
This option is set to the page_path value.
page_path
path => [ $s->page_path ]
You should use ht_new_args at the very beginning of the process, for any argument but 'filename'.
ht_new_args
# set args in the new instance statement my $webapp = My::WebApp ->new( ht_new_args => { path => ['/my/path'], # override defaults die_on_bad_params => 0, cache => 1 } ..... ); # or in the OH_init handler sub OH_init { my $s = shift; $s->ht_new_args( path => ['/my/path'], # override defaults die_on_bad_params => 0, cache => 1 ); }
Note about custom filenames: it is preferable to avoid to explicitly set the filename argument and let the default do it for you. Anyway if you still need to set the filename, you must know that you have to reset it if you switch_to() another page AFTER setting it.
switch_to()
# and/or in a Page Handler sub PH_specialPage { my $s = shift; $s->ht_new_args( filename => 'special.tmp') # override defaults $s->ht_param( mySomething => 'something' ); }
Note: You can completely override the creation of the internal object by overriding the ht_new() method.
ht_new()
This property group accessor handles the HTML::Template parameters that are internally passed to the ht object before the output production. Use it to collect the params that will be passed to the object.
ht
Note: This group accessor has been added in the 1.21 version in order to avoid to use the ht property:
# deprecated $s->ht->param(...) # OK $s->ht_param(...)
This property is used internally, so you usually don't need to use it directly in your code. In the rare case you need to use it (e.g. if you need to use HTML::Template::query() method), you should use it after any other switch_to() calls, or you should explicitly undef it just before the switch_to() call.
HTML::Template::query()
Note: You can change the default arguments that are internally used to create the object by using the ht_new_args group accessor, or you can completely override the creation of the internal object by overriding the ht_new() method.
Advanced Note: Unlike other template object, the HTML::Template object needs to know the filename at the moment of its creation. That restriction considerably limits the possibility to switch_to another page if and when the ht property has been already used (i.e. the HTML::Template object has been already created). For this reason, the ht property is preferably used only as an ending point (i.e. after we know what is the ultimate page to serve).
This module sets the default of the page_suffix to the traditional '.tmpl'. You can override it by just setting another suffix of your choice.
This module sets the default of the page_content to the template output produced by using the internal ht->output(). 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.
This method is not intended to be used directly in your CBB. It is used internally to initialize and returns the HTML::Template object, but you need to know how it does its job. If you need some more customization you can redefine the method in your CBB.
If (and only if) your application has to switch_to after using the ht property quite often, it may be handy to implement the following switch_to() in your own CBB:
sub switch_to { my $s = shift; $s->ht_new_args( {filename => $_[0].$s->page_suffix} ) if $s{ht_new_args}{filename}; $s->ht = undef; $s->CGI::Builder::switch_to(@_); }
This extension use this method to check if the template file exists before using its template print method, thus avoiding a fatal error when the requested page is not found.
Note: You don't need to directly use this method since it's internally called at the very start of the RESPONSE phase. You don't need to override it if you want just to send a different header status, since the CBF sets the status just if it is not defined yet.
Don't use the ht_new_args in all the Page Handlers: it is intended to be used once e.g. in an OH_init OR as an exceptional case in any Page Handler just to allow overriding (e.g. a different filename just for that particular Page Handler).
Don't explicitly set the page_content property unless you want to bypass the template system: this extension set it for you.
See "SUPPORT" in CGI::Builder.
© 2004 by Domizio Demichelis (http://perl.4pro.net)
All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as perl itself.
Thanks to Rob Arnold for his testing and suggestions.
1 POD Error
The following errors were encountered while parsing the POD:
Non-ASCII character seen before =encoding in ' '. Assuming CP1252
To install CGI::Builder::HTMLtmpl, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CGI::Builder::HTMLtmpl
CPAN shell
perl -MCPAN -e shell install CGI::Builder::HTMLtmpl
For more information on module installation, please visit the detailed CPAN module installation guide.