Rechercher une page de manuel
CGI::Builder::HTMLtmpl.3pm
Langue: en
Version: 2005-06-30 (mandriva - 01/05/08)
Section: 3 (Bibliothèques de fonctions)
Sommaire
NAME
CGI::Builder::HTMLtmpl - CGI::Builder and HTML::Template integrationVERSION 1.21
To have the complete list of all the extensions of the CBF, see ``Extensions List'' in CGI::BuilderINSTALLATION
- Prerequisites
-
CGI::Builder >= 1.0 HTML::Template >= 2.6
- CPAN
-
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'
- Standard installation
- From the directory where this file is located, type:
perl Makefile.PL make make test make install
SYNOPSIS
use CGI::Builder qw| CGI::Builder::HTMLtmpl ... |;
DESCRIPTION
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).
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:
# 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.
EXAMPLES
Simple CBB (all defaults)
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;
More complex CBB (overriding defaults)
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;
PROPERTY and GROUP ACCESSORS
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.ht_new_args( arguments )
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.
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.
path => [ $s->page_path ]
You should use "ht_new_args" at the very beginning of the process, for any argument but 'filename'.
# 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.
# 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_param
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.
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(...)
ht
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.
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).
CBF changed property defaults
CBF page_suffix
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.
CBF page_content
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.
METHODS
ht_new()
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.
switch_to overriding
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(@_); }
CBF overridden methods
page_content_check
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.
AVOIDING MISTAKES
- •
- 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.
SUPPORT
See ``SUPPORT'' in CGI::Builder.AUTHOR and COPYRIGHT
X 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.
CREDITS
Thanks to Rob Arnold for his testing and suggestions.Contenus ©2006-2024 Benjamin Poulain
Design ©2006-2024 Maxime Vantorre