| 1 |
NAME |
| 2 |
CGI::Application::Plugin::AnyTemplate - Use any templating system from |
| 3 |
within CGI::Application using a unified interface |
| 4 |
|
| 5 |
VERSION |
| 6 |
Version 0.18 |
| 7 |
|
| 8 |
SYNOPSIS |
| 9 |
In your CGI::Application-based webapp: |
| 10 |
|
| 11 |
use base 'CGI::Application'; |
| 12 |
use CGI::Application::Plugin::AnyTemplate; |
| 13 |
|
| 14 |
sub cgiapp_init { |
| 15 |
my $self = shift; |
| 16 |
|
| 17 |
# Set template options |
| 18 |
$self->template->config( |
| 19 |
default_type => 'TemplateToolkit', |
| 20 |
); |
| 21 |
} |
| 22 |
|
| 23 |
Later on, in a runmode: |
| 24 |
|
| 25 |
sub my_runmode { |
| 26 |
my $self = shift; |
| 27 |
|
| 28 |
my %template_params = ( |
| 29 |
name => 'Winston Churchill', |
| 30 |
age => 7, |
| 31 |
); |
| 32 |
|
| 33 |
$self->template->fill('some_template', \%template_params); |
| 34 |
} |
| 35 |
|
| 36 |
DESCRIPTION |
| 37 |
Template-Independence |
| 38 |
"CGI::Application::Plugin::AnyTemplate" allows you to use any supported |
| 39 |
Perl templating system using a single consistent interface. |
| 40 |
|
| 41 |
Currently supported templating systems include HTML::Template, |
| 42 |
HTML::Template::Expr, HTML::Template::Pluggable, Template::Toolkit and |
| 43 |
Petal. |
| 44 |
|
| 45 |
You can access any of these templating systems using the same interface. |
| 46 |
In this way, you can use the same code and switch templating systems on |
| 47 |
the fly. |
| 48 |
|
| 49 |
This approach has many uses. For instance, it can be useful in migrating |
| 50 |
your application from one templating system to another. |
| 51 |
|
| 52 |
Embedded Components |
| 53 |
In addition to template abstraction, "AnyTemplate" also provides a |
| 54 |
*embedded component mechanism*. For instance, you might include a |
| 55 |
*header* component at the top of every page and a *footer* component at |
| 56 |
the bottom of every page. |
| 57 |
|
| 58 |
These components are actually full CGI::Application run modes, and can |
| 59 |
do anything normal run mode can do, including processing form parameters |
| 60 |
and filling in their own templates. See below under "EMBEDDED |
| 61 |
COMPONENTS" for details. |
| 62 |
|
| 63 |
Multiple Named Template Configurations |
| 64 |
You can set up multiple named template configurations and select between |
| 65 |
them at run time. |
| 66 |
|
| 67 |
sub cgiapp_init { |
| 68 |
my $self = shift; |
| 69 |
|
| 70 |
# Can't use Template::Toolkit any more - |
| 71 |
# The boss wants everything has to be XML, |
| 72 |
# so we switch to Petal |
| 73 |
|
| 74 |
# Set old-style template options (legacy scripts) |
| 75 |
$self->template('oldstyle')->config( |
| 76 |
default_type => 'TemplateToolkit', |
| 77 |
TemplateToolkit => { |
| 78 |
POST_CHOMP => 1, |
| 79 |
} |
| 80 |
); |
| 81 |
# Set new-style template options as default |
| 82 |
$self->template->config( |
| 83 |
default_type => 'Petal', |
| 84 |
auto_add_template_extension => 0, |
| 85 |
); |
| 86 |
} |
| 87 |
|
| 88 |
sub old_style_runmode { |
| 89 |
my $self = shift; |
| 90 |
|
| 91 |
# ... |
| 92 |
|
| 93 |
# use TemplateToolkit to fill template edit_user.tmpl |
| 94 |
$self->template('oldstyle')->fill('edit_user', \%params); |
| 95 |
|
| 96 |
} |
| 97 |
|
| 98 |
sub new_style_runmode { |
| 99 |
my $self = shift; |
| 100 |
|
| 101 |
# ... |
| 102 |
|
| 103 |
# use Petal to fill template edit_user.xhml |
| 104 |
$self->template->fill('edit_user.xhtml', \%params); |
| 105 |
|
| 106 |
} |
| 107 |
|
| 108 |
Flexible Syntax |
| 109 |
The syntax is pretty flexible. Pick a style that's most comfortable for |
| 110 |
you. |
| 111 |
|
| 112 |
CGI::Application::Plugin::TT style syntax |
| 113 |
$self->template->process('edit_user', \%params); |
| 114 |
|
| 115 |
or (with slightly less typing): |
| 116 |
|
| 117 |
$self->template->fill('edit_user', \%params); |
| 118 |
|
| 119 |
CGI::Application load_tmpl style syntax |
| 120 |
my $template = $self->template->load('edit_user'); |
| 121 |
$template->param('foo' => 'bar'); |
| 122 |
$template->output; |
| 123 |
|
| 124 |
Verbose syntax (for complete control) |
| 125 |
my $template = $self->template('named_config')->load( |
| 126 |
file => 'edit_user' |
| 127 |
type => 'TemplateToolkit' |
| 128 |
add_include_paths => '.', |
| 129 |
); |
| 130 |
|
| 131 |
$template->param('foo' => 'bar'); |
| 132 |
$template->output; |
| 133 |
|
| 134 |
See also below under "CHANGING THE NAME OF THE 'template' METHOD". |
| 135 |
|
| 136 |
METHODS |
| 137 |
config |
| 138 |
Initialize the "AnyTemplate" system and provide the default |
| 139 |
configuration. |
| 140 |
|
| 141 |
$self->template->config( |
| 142 |
default_type => 'HTMLTemplate', |
| 143 |
); |
| 144 |
|
| 145 |
You can keep multiple configurations handy at the same time by passing a |
| 146 |
value to "template": |
| 147 |
|
| 148 |
$self->template('oldstyle')->config( |
| 149 |
default_type => 'HTML::Template', |
| 150 |
); |
| 151 |
$self->template('newstyle')->config( |
| 152 |
default_type => 'HTML::Template::Expr', |
| 153 |
); |
| 154 |
|
| 155 |
Then in a runmode you can mix and match configurations: |
| 156 |
|
| 157 |
$self->template('oldstyle')->load # loads an HTML::Template driver object |
| 158 |
$self->template('newstyle')->load # loads an HTML::Template::Expr driver object |
| 159 |
|
| 160 |
The configuration passed to "config" is divided into three areas: |
| 161 |
*plugin configuration*, *driver configuration*, and *native |
| 162 |
configuration*: |
| 163 |
|
| 164 |
Config Type What it Configures |
| 165 |
----------- ------------------ |
| 166 |
Plugin Config AnyTemplate itself |
| 167 |
Driver Config AnyTemplate Driver (e.g. HTMLTemplate) |
| 168 |
Native Config Actual template module (e.g. HTML::Template) |
| 169 |
|
| 170 |
These are described in more detail below. |
| 171 |
|
| 172 |
Plugin Configuration |
| 173 |
These configuration params are specific to the |
| 174 |
"CGI::Application::Plugin::AnyTemplate" itself. They are included at the |
| 175 |
top level of the configuration hash passed to "config". For instance: |
| 176 |
|
| 177 |
$self->template->config( |
| 178 |
default_type => 'HTMLTemplate', |
| 179 |
auto_add_template_extension => 0, |
| 180 |
); |
| 181 |
|
| 182 |
The *plugin configuration* parameters and their defaults are as follows: |
| 183 |
|
| 184 |
default_type |
| 185 |
type |
| 186 |
The default type of template for this named configuration. Should be |
| 187 |
the name of a driver in the |
| 188 |
"CGI::Application::Plugin::AnyTemplate::Driver" namespace: |
| 189 |
|
| 190 |
Type Driver |
| 191 |
---- ------ |
| 192 |
HTMLTemplate CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplate |
| 193 |
HTMLTemplateExpr CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplateExpr |
| 194 |
TemplateToolkit CGI::Application::Plugin::AnyTemplate::Driver::TemplateToolkit |
| 195 |
Petal CGI::Application::Plugin::AnyTemplate::Driver::Petal |
| 196 |
|
| 197 |
include_paths |
| 198 |
Include Paths (sometimes called search paths) are used by the |
| 199 |
various template backends to find filenames that aren't fully |
| 200 |
qualified by an absolute path. Each directory is searched in turn |
| 201 |
until the template file is found. |
| 202 |
|
| 203 |
Can be a single string or a reference to a list. |
| 204 |
|
| 205 |
auto_add_template_extension |
| 206 |
Add a template-system specific extension to template filenames. |
| 207 |
|
| 208 |
So, if this feature is enabled and you provide the filename |
| 209 |
"myfile", then the actual filename will depend on the current |
| 210 |
template driver: |
| 211 |
|
| 212 |
Driver Template |
| 213 |
------ -------- |
| 214 |
HTMLTemplate myfile.html |
| 215 |
HTMLTemplateExpr myfile.html |
| 216 |
TemplateToolkit myfile.tmpl |
| 217 |
Petal myfile.xhtml |
| 218 |
|
| 219 |
The per-type extension is controlled by the driver config for each |
| 220 |
"AnyTemplate" driver (see below under "Driver and Native |
| 221 |
Configuration" for how to set this). |
| 222 |
|
| 223 |
The "auto_add_template_extension" feature is on by default. To |
| 224 |
disable it, pass a value of zero: |
| 225 |
|
| 226 |
$self->template->config( |
| 227 |
auto_add_template_extension => 0, |
| 228 |
); |
| 229 |
|
| 230 |
The automatic extension feature is not just there to save typing - |
| 231 |
it's actually there so you can have templates of different types |
| 232 |
sitting in the same directory. |
| 233 |
|
| 234 |
sub my_runmode { |
| 235 |
my $self = shift; |
| 236 |
$self->template->fill; |
| 237 |
} |
| 238 |
|
| 239 |
Then in your template path you can have three files: |
| 240 |
|
| 241 |
my_runmode.html |
| 242 |
my_runmode.tmpl |
| 243 |
my_runmode.xhtml |
| 244 |
|
| 245 |
Then you can change which templates is used by changing the value of |
| 246 |
"type" that you pass to "$self->template->config". |
| 247 |
|
| 248 |
For applications that want to dynamically choose their template |
| 249 |
system without changing app code, it's a cleaner solution to use the |
| 250 |
extensions than trying to swap template paths at runtime. Even if |
| 251 |
you keep each type of template in its own directory, it's simpler to |
| 252 |
include all the directories all the time and use different |
| 253 |
extensions for different template types. |
| 254 |
|
| 255 |
template_filename_generator |
| 256 |
If you don't pass a filename to "load", one will be generated for |
| 257 |
you based on the current run mode. If you want to customize this |
| 258 |
process, you can pass a reference to a subroutine to do the |
| 259 |
translation. This subroutine will be passed a reference to the |
| 260 |
CGI::Application $self object. |
| 261 |
|
| 262 |
Here is a subroutine that emulates the built-in behaviour of |
| 263 |
"AnyTemplate": |
| 264 |
|
| 265 |
$self->template->config( |
| 266 |
template_filename_generator => sub { |
| 267 |
my ($self, $calling_method_name) = @_; |
| 268 |
return $self->get_current_runmode; |
| 269 |
} |
| 270 |
} |
| 271 |
); |
| 272 |
|
| 273 |
Here is an example of using a template filename generator to make |
| 274 |
full templates with full paths based on the module name as well as |
| 275 |
the current run mode (this is similar to how |
| 276 |
CGI::Application::Plugin::TT generates its template filenames): |
| 277 |
|
| 278 |
package My::WebApp; |
| 279 |
use File::Spec; |
| 280 |
|
| 281 |
sub cgiapp_init { |
| 282 |
my $self = shift; |
| 283 |
|
| 284 |
$self->template->config( |
| 285 |
template_filename_generator => sub { |
| 286 |
my $self = shift; |
| 287 |
my $run_mode = $self->get_current_runmode; |
| 288 |
my $module = ref $self; |
| 289 |
|
| 290 |
my @segments = split /::/, $module; |
| 291 |
|
| 292 |
return File::Spec->catfile(@segments, $run_mode); |
| 293 |
} |
| 294 |
); |
| 295 |
} |
| 296 |
|
| 297 |
sub run_mode { |
| 298 |
my $self = shift; |
| 299 |
$self->template->load; # loads My/WebApp/run_mode.html |
| 300 |
} |
| 301 |
|
| 302 |
sub other_run_mode { |
| 303 |
my $self = shift; |
| 304 |
$self->template->load; # loads My/WebApp/other_run_mode.html |
| 305 |
} |
| 306 |
|
| 307 |
Note that if the "auto_add_template_extension" option is on (which |
| 308 |
it is by default), then the extension will be added to your |
| 309 |
generated filename after you return it. If you do not want this to |
| 310 |
happen, then set "auto_add_template_extension" to a false value. |
| 311 |
|
| 312 |
component_handler_class |
| 313 |
Normally, component embedding is handled by |
| 314 |
CGI::Application::Plugin::AnyTemplate::ComponentHandler. If you want |
| 315 |
to use a different class for this purpose, specify the class name as |
| 316 |
the value of this paramter. |
| 317 |
|
| 318 |
It still has to provide the same interface as |
| 319 |
CGI::Application::Plugin::AnyTemplate::ComponentHandler. See the |
| 320 |
source code of that module for details. |
| 321 |
|
| 322 |
return_references |
| 323 |
When true (the default), "output" will return a reference to a |
| 324 |
string rather than a copy. Normally this won't matter. For instance, |
| 325 |
"CGI::Application" doesn't care whether you return a string or a |
| 326 |
reference to a string from your run modes. |
| 327 |
|
| 328 |
However, if you want to manipulate the output of the $html returned |
| 329 |
from the template, you may find it convenient to make "output" |
| 330 |
return a string instead of a reference. Especially if you are |
| 331 |
converting old code based on HTML::Template which expects "output" |
| 332 |
to return a string. |
| 333 |
|
| 334 |
Driver and Native Configuration |
| 335 |
You can configure all the drivers at once with a single call to |
| 336 |
"config", by including subsections for each driver type: |
| 337 |
|
| 338 |
$self->template->config( |
| 339 |
default_type => 'HTMLTemplate', |
| 340 |
HTMLTemplate => { |
| 341 |
cache => 1, |
| 342 |
global_vars => 1, |
| 343 |
die_on_bad_params => 0, |
| 344 |
template_extension => '.html', |
| 345 |
}, |
| 346 |
HTMLTemplateExpr => { |
| 347 |
cache => 1, |
| 348 |
global_vars => 1, |
| 349 |
die_on_bad_params => 0, |
| 350 |
template_extension => '.html', |
| 351 |
}, |
| 352 |
HTMLTemplatePluggable => { |
| 353 |
cache => 1, |
| 354 |
global_vars => 1, |
| 355 |
die_on_bad_params => 0, |
| 356 |
template_extension => '.html', |
| 357 |
}, |
| 358 |
TemplateToolkit => { |
| 359 |
POST_CHOMP => 1, |
| 360 |
template_extension => '.tmpl', |
| 361 |
}, |
| 362 |
Petal => { |
| 363 |
error_on_undef => 0, |
| 364 |
template_extension => '.xhtml', |
| 365 |
}, |
| 366 |
); |
| 367 |
|
| 368 |
Each driver knows how to separate its own configuration from the |
| 369 |
configuration belonging to the underlying template system. |
| 370 |
|
| 371 |
For instance in the example above, the "HTMLTemplate" driver knows that |
| 372 |
"template_extension" is a driver config parameter, but |
| 373 |
"cache_global_vars" and "die_on_bad_params" are all HTML::Template |
| 374 |
configuration parameters. |
| 375 |
|
| 376 |
Similarly, The "TemplateToolkit" driver knows that template_extension is |
| 377 |
a driver config parameter, but "POST_CHOMP" is a "Template::Toolkit" |
| 378 |
configuration parameter. |
| 379 |
|
| 380 |
For details on driver configuration, see the docs for the individual |
| 381 |
drivers: |
| 382 |
|
| 383 |
CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplate |
| 384 |
CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplateExpr |
| 385 |
CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplatePluggable |
| 386 |
CGI::Application::Plugin::AnyTemplate::Driver::TemplateToolkit |
| 387 |
CGI::Application::Plugin::AnyTemplate::Driver::Petal |
| 388 |
|
| 389 |
Copying Query data into Templates |
| 390 |
This feature is now deprecated and will be removed in a future release. |
| 391 |
|
| 392 |
When you enable this feature all data in "$self->query" are copied into |
| 393 |
the template object before the template is processed. |
| 394 |
|
| 395 |
For the "HTMLTemplate", "HTMLTemplateExpr" and "HTMLTemplatePluggable" |
| 396 |
drivers this is done with the "associate" feature of HTML::Template and |
| 397 |
HTML::Template::Expr, respectively: |
| 398 |
|
| 399 |
my $template = HTML::Template->new( |
| 400 |
associate => $self->query, |
| 401 |
); |
| 402 |
|
| 403 |
For the other systems, this feature is emulated, by copying the query |
| 404 |
params into the template params before the template is processed. |
| 405 |
|
| 406 |
To enable this feature, pass a true value to "associate_query" or |
| 407 |
"emulate_associate_query" (depending on the template system): |
| 408 |
$self->template->config( default_type => 'HTMLTemplate', HTMLTemplate => |
| 409 |
{ associate_query => 1, }, HTMLTemplateExpr => { associate_query => 1, |
| 410 |
}, HTMLTemplatePluggable => { associate_query => 1, }, TemplateToolkit |
| 411 |
=> { emulate_associate_query => 1, }, Petal => { emulate_associate_query |
| 412 |
=> 1, }, ); |
| 413 |
|
| 414 |
The reason this feature is now disabled by default is that it poses a |
| 415 |
potential XSS (Cross Site Scripting) security risk. |
| 416 |
|
| 417 |
The reason this feature is now deprecated is that in an ideal world |
| 418 |
developers shouldn't have to flatten objects and hashes in order to make |
| 419 |
them available to their templates. They should be able to pass the query |
| 420 |
object (or another object such as a config object) directly into the |
| 421 |
template: |
| 422 |
|
| 423 |
$template->param( |
| 424 |
'query' => $self->query, |
| 425 |
'cfg' => $self->cfg, |
| 426 |
'ENV' => $ENV, |
| 427 |
); |
| 428 |
|
| 429 |
And in the template retrieve parameters directly: |
| 430 |
|
| 431 |
your username: [% query.param('username') %] |
| 432 |
administrator: [% cfg.admin %] |
| 433 |
hostname: [% ENV.SERVER_NAME %] |
| 434 |
|
| 435 |
This approach works with Template::Toolkit, Petal, and |
| 436 |
HTML::Template::Pluggable (via the HTML::Template::Plugin::Dot plugin). |
| 437 |
|
| 438 |
Note that "associate" and "associate_query" are not compatible. So if |
| 439 |
you want to associate the query and an additional object, pass a list to |
| 440 |
"associate": |
| 441 |
|
| 442 |
$template->config( |
| 443 |
HTMLTemplate => { |
| 444 |
associate => [$self->query, $self->conf] |
| 445 |
} |
| 446 |
); |
| 447 |
|
| 448 |
load |
| 449 |
Create a new template object and configure it. |
| 450 |
|
| 451 |
This can be as simple (and magical) as: |
| 452 |
|
| 453 |
my $template = $self->template->load; |
| 454 |
|
| 455 |
When you call "load" with no parameters, it uses the default template |
| 456 |
type, the default template configuration, and it determines the name of |
| 457 |
the template based on the name of the current run mode. It determines |
| 458 |
the current run mode by calling "$self->get_current_runmode". |
| 459 |
|
| 460 |
If you want to have the current runmode updated when you pass control to |
| 461 |
another runmode, use the CGI::Application::Plugin::Forward module: |
| 462 |
|
| 463 |
use CGI::Application::Plugin::Forward; |
| 464 |
|
| 465 |
sub first_runmode { |
| 466 |
my $self = shift; |
| 467 |
return $self->forward('second_runmode'); |
| 468 |
} |
| 469 |
sub second_runmode { |
| 470 |
my $self = shift; |
| 471 |
my $template = $self->template->load; # loads 'second_runmode.html' |
| 472 |
} |
| 473 |
|
| 474 |
If instead you call "$self->other_method" directly, the value of |
| 475 |
"$self->get_current_runmode" will not be updated: |
| 476 |
|
| 477 |
sub first_runmode { |
| 478 |
my $self = shift; |
| 479 |
return $self->other_method; |
| 480 |
} |
| 481 |
sub other_method { |
| 482 |
my $self = shift; |
| 483 |
my $template = $self->template->load; # loads 'first_runmode.html' |
| 484 |
} |
| 485 |
|
| 486 |
If you want to override the way the default template filename is |
| 487 |
generated, you can do so with the "template_filename_generator" |
| 488 |
configuration parameter. |
| 489 |
|
| 490 |
If you call "load" with one paramter, it is taken to be either the |
| 491 |
filename or a reference to a string containing the template text: |
| 492 |
|
| 493 |
my $template = $self->template->load('somefile'); |
| 494 |
my $template = $self->template->load(\$some_text); |
| 495 |
|
| 496 |
If the parameter "auto_add_template_exension" is true, then the |
| 497 |
appropriate extension will be added for this template type. |
| 498 |
|
| 499 |
If you call "load" with more than one parameter, then you can specify |
| 500 |
filename and configuration paramters directly: |
| 501 |
|
| 502 |
my $template = $self->template->load( |
| 503 |
file => 'some_file.tmpl', |
| 504 |
type => 'HTMLTemplate', |
| 505 |
auto_add_template_extension => 0, |
| 506 |
add_include_paths => '..', |
| 507 |
HTMLTemplate => { |
| 508 |
die_on_bad_params => 1, |
| 509 |
}, |
| 510 |
); |
| 511 |
|
| 512 |
To initialize the template from a string rather than a file, use: |
| 513 |
|
| 514 |
my $template = $self->template->load( |
| 515 |
string => \$some_text, |
| 516 |
); |
| 517 |
|
| 518 |
The configuration parameters you pass to "load" are merged with the |
| 519 |
configuration that was passed to "config". |
| 520 |
|
| 521 |
You can include any of the configuration parameters that you can pass to |
| 522 |
config, plus the following extra parameters: |
| 523 |
|
| 524 |
file |
| 525 |
If you are loading the template from a file, then the "file" |
| 526 |
parameter contains the template's filename. |
| 527 |
|
| 528 |
string |
| 529 |
If you are loading the template from a string, then the "string" |
| 530 |
parameter contains the text of the template. It can be either a |
| 531 |
scalar or a reference to a scalar. Both of the following will work: |
| 532 |
|
| 533 |
# passing a string |
| 534 |
my $template = $self->template->load( |
| 535 |
string => $some_text, |
| 536 |
); |
| 537 |
|
| 538 |
# passing a reference to a string |
| 539 |
my $template = $self->template->load( |
| 540 |
string => \$some_text, |
| 541 |
); |
| 542 |
|
| 543 |
add_include_paths |
| 544 |
Additional include paths. These will be merged with "include_paths" |
| 545 |
before being passed to the template driver. |
| 546 |
|
| 547 |
The "load" method returns a template driver object. See below under |
| 548 |
"DRIVER METHODS", for how to use this object. |
| 549 |
|
| 550 |
fill |
| 551 |
Fill is a convenience method which in a single step creates the |
| 552 |
template, fills it with the template paramters and returns its output. |
| 553 |
|
| 554 |
You can call it with or without a filename (or string ref). |
| 555 |
|
| 556 |
The code: |
| 557 |
|
| 558 |
$self->template->fill('filename', \%params); |
| 559 |
|
| 560 |
is equivalent to: |
| 561 |
|
| 562 |
my $template = $self->template->load('filename'); |
| 563 |
$template->output(\%params); |
| 564 |
|
| 565 |
And the code: |
| 566 |
|
| 567 |
$self->template->fill(\$some_text, \%params); |
| 568 |
|
| 569 |
is equivalent to: |
| 570 |
|
| 571 |
my $template = $self->template->load(\$some_text); |
| 572 |
$template->output(\%params); |
| 573 |
|
| 574 |
And the code: |
| 575 |
|
| 576 |
$self->template->fill(\%params); |
| 577 |
|
| 578 |
is equivalent to: |
| 579 |
|
| 580 |
my $template = $self->template->load; |
| 581 |
$template->output(\%params); |
| 582 |
|
| 583 |
And the code: |
| 584 |
|
| 585 |
$self->template->fill('filename'); |
| 586 |
|
| 587 |
is equivalent to: |
| 588 |
|
| 589 |
my $template = $self->template->load('filename'); |
| 590 |
$template->output; |
| 591 |
|
| 592 |
And the code: |
| 593 |
|
| 594 |
$self->template->fill(\$some_text); |
| 595 |
|
| 596 |
is equivalent to: |
| 597 |
|
| 598 |
my $template = $self->template->load(\$some_text); |
| 599 |
$template->output; |
| 600 |
|
| 601 |
And the code: |
| 602 |
|
| 603 |
$self->template->fill; |
| 604 |
|
| 605 |
is equivalent to: |
| 606 |
|
| 607 |
my $template = $self->template->load; |
| 608 |
$template->output; |
| 609 |
|
| 610 |
process |
| 611 |
"process" is an alias for "fill". |
| 612 |
|
| 613 |
APPLICATION METHODS |
| 614 |
These methods are called directly on your application's $self object. |
| 615 |
|
| 616 |
load_tmpl |
| 617 |
This is an emulation of CGI::Application's built-in "load_tmpl" method. |
| 618 |
For instance: |
| 619 |
|
| 620 |
$self->load_tmpl('some_template.html'); |
| 621 |
|
| 622 |
It is not exported by default. To enable it, use: |
| 623 |
|
| 624 |
use CGI::Application::Plugin::AnyTemplate qw/:load_tmpl/; |
| 625 |
|
| 626 |
You can call it the same way as documented in "CGI::Application" and it |
| 627 |
will have the same effect. However, it will respect the current template |
| 628 |
"type", so you can still use it to fill templates of different backends. |
| 629 |
|
| 630 |
The idea is that you can take an existing CGI::Application-based webapp |
| 631 |
which uses "HTML::Template" templates, and add the following code to it: |
| 632 |
|
| 633 |
use CGI::Application::Plugin::AnyTemplate qw/:load_tmpl/; |
| 634 |
|
| 635 |
sub setup { |
| 636 |
my $self = shift; |
| 637 |
$self->template->config(type => TemplateToolkit); |
| 638 |
} |
| 639 |
|
| 640 |
This will change all existing calls to load_tmpl within your application |
| 641 |
to use Template::Toolkit based templates. |
| 642 |
|
| 643 |
Calling: |
| 644 |
|
| 645 |
my $template = $self->load_tmpl('some_template.html'); |
| 646 |
|
| 647 |
It is the equivalent of calling: |
| 648 |
|
| 649 |
my $template = $self->template->load( |
| 650 |
file => 'some_template.html', |
| 651 |
auto_add_template_extension => 0, |
| 652 |
); |
| 653 |
|
| 654 |
If you add extra options to "load_tmpl", these will be assumed to be |
| 655 |
HTML::Template specific options, with the exception of the "path" |
| 656 |
option, which will be extracted and used as 'add_include_paths': |
| 657 |
|
| 658 |
my $template = $self->load_tmpl('some_template.html', |
| 659 |
cache => 0, |
| 660 |
path => '/path/to/templates', |
| 661 |
); |
| 662 |
|
| 663 |
This will get translated into: |
| 664 |
|
| 665 |
my $template = $self->template->load( |
| 666 |
file => 'some_template.html', |
| 667 |
auto_add_template_extension => 0, |
| 668 |
add_include_paths => '/path/to/templates', |
| 669 |
HTMLTemplate => { |
| 670 |
cache => 0, |
| 671 |
} |
| 672 |
); |
| 673 |
|
| 674 |
Note that if you specify any HTML::Template-specific options here, they |
| 675 |
will completely overwrite any options that you passed to config. |
| 676 |
|
| 677 |
Some notes and caveats about using the "load_tmpl" method: |
| 678 |
|
| 679 |
* This method only works for the default template configuration (i.e. |
| 680 |
"$self->template()"). If you set up a named configuration (e.g. |
| 681 |
"$self->template('myconfig')") there is no way to access it with |
| 682 |
"load_tmpl". Since plugins should be using named configurations, |
| 683 |
this means that the "load_tmpl" method should not be used by |
| 684 |
plugins. See "NOTES FOR AUTHORS OF PLUGINS AND REUSABLE |
| 685 |
APPLICATIONS", below. |
| 686 |
|
| 687 |
* The "load_tmpl" method does not automatically add an extension to |
| 688 |
the filename you pass to it, even if you have |
| 689 |
"auto_add_template_extension" set to a true value in your call to |
| 690 |
"$self->template->config". |
| 691 |
|
| 692 |
* The "load_tmpl" method ignores always returns a string, not a |
| 693 |
reference to a string. It ignores the setting of the |
| 694 |
"returns_references" option. |
| 695 |
|
| 696 |
tmpl_path |
| 697 |
You can set the template "include_paths" by calling |
| 698 |
"$self->tmpl_path('/path/to/templates')". |
| 699 |
|
| 700 |
You can also do so by passing a value to the "TMPL_PATH" parameter to |
| 701 |
your application's "new" method: |
| 702 |
|
| 703 |
my $webapp = App->new( |
| 704 |
TMPL_PATH => '/path/to/templates', |
| 705 |
); |
| 706 |
|
| 707 |
Paths that you set via "tmpl_path"/"TMPL_PATH" will be put last in the |
| 708 |
list of include paths, after "add_include_paths" and "include_paths". |
| 709 |
|
| 710 |
DRIVER METHODS |
| 711 |
These are the most commonly used methods of the "AnyTemplate" driver |
| 712 |
object. The driver is what you get back from calling |
| 713 |
"$self->template->load". |
| 714 |
|
| 715 |
param |
| 716 |
The "param" method gets and sets values within the template. |
| 717 |
|
| 718 |
my $template = $self->template->load; |
| 719 |
|
| 720 |
my @param_names = $template->param(); |
| 721 |
|
| 722 |
my $value = $template->param('name'); |
| 723 |
|
| 724 |
$template->param('name' => 'value'); |
| 725 |
$template->param( |
| 726 |
'name1' => 'value1', |
| 727 |
'name2' => 'value2' |
| 728 |
); |
| 729 |
|
| 730 |
It is designed to behave similarly to the "param" method in other |
| 731 |
modules like CGI and HTML::Template. |
| 732 |
|
| 733 |
get_param_hash |
| 734 |
Returns the template variables as a hash of names and values. |
| 735 |
|
| 736 |
my %params = $self->template->get_param_hash; |
| 737 |
|
| 738 |
In a scalar context, returns a reference to the hash used internally to |
| 739 |
contain the values: |
| 740 |
|
| 741 |
my $params_ref = $self->template->get_param_hash; |
| 742 |
|
| 743 |
$params_ref->{'foo'} = 'bar'; # directly change parameter 'foo' |
| 744 |
|
| 745 |
output |
| 746 |
Returns the template with all the values filled in. |
| 747 |
|
| 748 |
return $template->output; |
| 749 |
|
| 750 |
You can also supply names and values to the template at this stage: |
| 751 |
|
| 752 |
return $template->output('name' => 'value', 'name2' => 'value2'); |
| 753 |
|
| 754 |
If "return_references" option is set to true, then the return value of |
| 755 |
"output" will be a reference to a string. If the "return_references" |
| 756 |
option is false, then a copy of the string will be returned. By default |
| 757 |
"return_references" is true. |
| 758 |
|
| 759 |
When you call the "output" method, any components embedded in the |
| 760 |
template are run. See "EMBEDDED COMPONENTS", below. |
| 761 |
|
| 762 |
PRE- AND POST- PROCESS |
| 763 |
There are several ways to customize the template process. You can modify |
| 764 |
the template parameters before the template is filled, and you can |
| 765 |
modify the output of the template after it has been filled. |
| 766 |
|
| 767 |
Multiple applications and plugins can hook into the template process |
| 768 |
pipeline, each making changes to the template input and output. |
| 769 |
|
| 770 |
For instance, it will be possible to make a general-purpose |
| 771 |
"CGI::Application" plugin that adds arbitrary data to each new template |
| 772 |
(such as query parameters or configuration data). |
| 773 |
|
| 774 |
Note that the API has changed for version 0.10 in a |
| 775 |
non-backwards-compatible way in order to use the new hook system |
| 776 |
provided by recent versions of "CGI::Application". |
| 777 |
|
| 778 |
The load_tmpl hook |
| 779 |
The "load_tmpl" hook is designed to be compatible with the "load_tmpl" |
| 780 |
hook defined by "CGI::Application" itself. |
| 781 |
|
| 782 |
The "load_tmpl" hook is called before the template object is created. |
| 783 |
Any callbacks that you register to this hook will be called before each |
| 784 |
template is loaded. Register a "load_tmpl" callback with: |
| 785 |
|
| 786 |
$self->add_callback('load_tmpl',\&my_load_tmpl); |
| 787 |
|
| 788 |
When the "load_tmpl" callback is executed it will be passed three |
| 789 |
arguments (*adapted from the* CGI::Application *docs*): |
| 790 |
|
| 791 |
1. A hash reference of the extra params passed into C<load_tmpl> |
| 792 |
(ignored by AnyTemplate with the exception of 'path') |
| 793 |
|
| 794 |
2. Followed by a hash reference to template parameters. |
| 795 |
You can modify this hash by reference to affect values that are |
| 796 |
actually passed to the param() method of the template object. |
| 797 |
|
| 798 |
3. The name of the template file. |
| 799 |
|
| 800 |
Here's an example stub for a load_tmpl() callback: |
| 801 |
|
| 802 |
sub my_load_tmpl_callback { |
| 803 |
my ($self, $ht_params, $tmpl_params, $tmpl_file) = @_; |
| 804 |
# modify $tmpl_params by reference... |
| 805 |
} |
| 806 |
|
| 807 |
Currently, of all the params in $ht_params, all but 'path' are ignored, |
| 808 |
because these are specific to "HTML::Template". If you want to write a |
| 809 |
generic callback that needs to be able to access or modify |
| 810 |
"HTML::Template" parameters then let me know, or add a feature request |
| 811 |
on <http://rt.cpan.org>. |
| 812 |
|
| 813 |
The "path" param of $ht_params is initially set to the value of |
| 814 |
"add_include_paths" (if set). Your callback can modify the "path" param, |
| 815 |
and "add_include_param" will be set to the result. |
| 816 |
|
| 817 |
Plugin authors who want to provide template processing features are |
| 818 |
encouraged to use the 'load_tmpl' hook when possible, since it will work |
| 819 |
both with AnyTemplate and with CGI::Application's built-in "load_tmpl". |
| 820 |
|
| 821 |
The template_pre_process and template_post_process hooks |
| 822 |
Before the template output is generated, the "template_pre_process" hook |
| 823 |
is called. Any callbacks that you register to this hook will be called |
| 824 |
before each template is processed. Register a "template_pre_process" |
| 825 |
callback as follows: |
| 826 |
|
| 827 |
$self->add_callback('template_pre_process', \&my_tmpl_pre_process); |
| 828 |
|
| 829 |
Pre-process callbacks will be passed a reference to the $template |
| 830 |
object, and can can modify the parameters passed into the template by |
| 831 |
using the "param" method: |
| 832 |
|
| 833 |
sub my_tmpl_pre_process { |
| 834 |
my ($self, $template) = @_; |
| 835 |
|
| 836 |
# Change the internal template parameters by reference |
| 837 |
my $params = $template->get_param_hash; |
| 838 |
|
| 839 |
foreach my $key (keys %$params) { |
| 840 |
$params{$key} = to_piglatin($params{$key}); |
| 841 |
} |
| 842 |
|
| 843 |
# Can also set values using the param method |
| 844 |
$template->param('foo', 'bar'); |
| 845 |
|
| 846 |
} |
| 847 |
|
| 848 |
After the template output is generated, the "template_post_process" hook |
| 849 |
is called. You can register a "template_post_process" callback as |
| 850 |
follows: |
| 851 |
|
| 852 |
$self->add_callback('template_post_process', \&my_tmpl_post_process); |
| 853 |
|
| 854 |
Any callbacks that you register to this hook will be called after each |
| 855 |
template is processed, and will be passed both a reference to the |
| 856 |
template object and a reference to the output generated by the template. |
| 857 |
This allows you to modify the output of the template: |
| 858 |
|
| 859 |
sub my_tmpl_post_process { |
| 860 |
my ($self, $template, $output_ref) = @_; |
| 861 |
|
| 862 |
$$output_ref =~ s/foo/bar/; |
| 863 |
} |
| 864 |
|
| 865 |
EMBEDDED COMPONENTS |
| 866 |
Introduction |
| 867 |
"CGI::Application::Plugin::AnyTemplate" allows you to include |
| 868 |
application components within your templates. |
| 869 |
|
| 870 |
For instance, you might include a *header* component a the top of every |
| 871 |
page and a *footer* component at the bottom of every page. |
| 872 |
|
| 873 |
These componenets are actually first-class run modes. When the template |
| 874 |
engine finds a special tag marking an embedded component, it passes |
| 875 |
control to the run mode of that name. That run mode can then do whatever |
| 876 |
a normal run mode could do. But typically it will load its own template |
| 877 |
and return the template's output. |
| 878 |
|
| 879 |
This output returned from the embedded run mode is inserted into the |
| 880 |
containing template. |
| 881 |
|
| 882 |
The syntax for embed components is specific to each type of template |
| 883 |
driver. |
| 884 |
|
| 885 |
Syntax |
| 886 |
HTML::Template syntax: |
| 887 |
|
| 888 |
<TMPL_VAR NAME="CGIAPP_embed('some_run_mode')"> |
| 889 |
|
| 890 |
HTML::Template::Expr syntax: |
| 891 |
|
| 892 |
<TMPL_VAR EXPR="CGIAPP_embed('some_run_mode')"> |
| 893 |
|
| 894 |
HTML::Template::Pluggable syntax: |
| 895 |
|
| 896 |
<TMPL_VAR EXPR="cgiapp.embed('some_run_mode')"> |
| 897 |
|
| 898 |
Template::Toolkit syntax: |
| 899 |
|
| 900 |
[% CGIAPP.embed("some_run_mode") %] |
| 901 |
|
| 902 |
Petal syntax: |
| 903 |
|
| 904 |
<span tal:replace="structure CGIAPP/embed 'some_run_mode'"> |
| 905 |
this text gets replaced by the output of some_run_mode |
| 906 |
</span> |
| 907 |
|
| 908 |
Getting Template Variables from the Containing Template |
| 909 |
The component run mode is passed a reference to the template object that |
| 910 |
contained the component. The component run mode can use this object to |
| 911 |
access the params that were passed to the containing template. |
| 912 |
|
| 913 |
For instance: |
| 914 |
|
| 915 |
sub header { |
| 916 |
my ($self, $containing_template, @other_params) = @_; |
| 917 |
|
| 918 |
my %tmplvars = ( |
| 919 |
'title' => 'My glorious home page', |
| 920 |
); |
| 921 |
|
| 922 |
my $template = $self->template->load; |
| 923 |
|
| 924 |
$template->param(%tmplvars, $containing_template->get_param_hash); |
| 925 |
return $template->output; |
| 926 |
} |
| 927 |
|
| 928 |
In this example, the template values of the enclosing template would |
| 929 |
override any values set by the embedded component. |
| 930 |
|
| 931 |
Passing Parameters |
| 932 |
The template can pass parameters to the target run mode. These are |
| 933 |
passed in after the reference to the containing template object. |
| 934 |
|
| 935 |
Parameters can either be literal strings, specified within the template |
| 936 |
text, or they can be keys that will be looked up in the template's |
| 937 |
params. |
| 938 |
|
| 939 |
Literal strings are enclosed in double or single quotes. Param keys are |
| 940 |
barewords. |
| 941 |
|
| 942 |
HTML::Template syntax: |
| 943 |
|
| 944 |
<TMPL_VAR NAME="CGIAPP_embed('some_run_mode', param1, 'literal string2')"> |
| 945 |
|
| 946 |
*Note that HTML::Template doesn't support this type of callback |
| 947 |
natively* *and that this behaviour is emulated by the HTMLTemplate |
| 948 |
driver* *see the docs to* |
| 949 |
CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplate *for |
| 950 |
limitations to the emulation*. |
| 951 |
|
| 952 |
HTML::Template::Expr syntax: |
| 953 |
|
| 954 |
<TMPL_VAR EXPR="CGIAPP_embed('some_run_mode', param1, 'literal string2')"> |
| 955 |
|
| 956 |
HTML::Template::Pluggable syntax: |
| 957 |
|
| 958 |
<TMPL_VAR EXPR="cgiapp.embed('some_run_mode', param1, 'literal string2')"> |
| 959 |
|
| 960 |
Template::Toolkit syntax: |
| 961 |
|
| 962 |
[% CGIAPP.embed("some_run_mode", param1, 'literal string2' ) %] |
| 963 |
|
| 964 |
Petal syntax: |
| 965 |
|
| 966 |
<span tal:replace="structure CGIAPP/embed 'some_run_mode' param1 'literal string2' "> |
| 967 |
this text gets replaced by the output of some_run_mode |
| 968 |
</span> |
| 969 |
|
| 970 |
NOTES FOR AUTHORS OF PLUGINS AND REUSABLE APPLICATIONS |
| 971 |
If you are writing a CGI::Application plugin module, or you are writing |
| 972 |
a "CGI::Application" program that will be distributed to other people |
| 973 |
(e.g. on CPAN), then it's important to take steps to prevent your |
| 974 |
application's use of CGI::Application::Plugin::AnyTemplate from |
| 975 |
conflicting with other plugins or with your end users. |
| 976 |
|
| 977 |
When a plugin that uses CGI::Application::Plugin::AnyTemplate calls: |
| 978 |
|
| 979 |
$self->template->config(...) |
| 980 |
|
| 981 |
It overwrites any existing template configuration with the new settings. |
| 982 |
So if two plugins do that, they probably clobber each other. |
| 983 |
|
| 984 |
However, CGI::Application::Plugin::AnyTemplate has the feature of named |
| 985 |
independent configs: |
| 986 |
|
| 987 |
$self->template('your_module')->config(...) |
| 988 |
$self->template('my_plugin')->config(...) |
| 989 |
|
| 990 |
These configs remain separate from each other. However, you have to keep |
| 991 |
using these names throughout your module, even when you load and fill |
| 992 |
the template. For instance: |
| 993 |
|
| 994 |
sub my_runmode { |
| 995 |
my $self = shift; |
| 996 |
my $template = $self->template('my_plugin')->load; |
| 997 |
$template->output; |
| 998 |
} |
| 999 |
|
| 1000 |
sub your_runmode { |
| 1001 |
my $self = shift; |
| 1002 |
my %params; |
| 1003 |
$self->template('your_module')->fill(\%params); |
| 1004 |
} |
| 1005 |
|
| 1006 |
It's uglier and more verbose, but it also prevents plugins from stepping |
| 1007 |
on each other's toes. |
| 1008 |
|
| 1009 |
CGI::Application plugins that use CGI::Application::Plugin::AnyTemplate |
| 1010 |
should default to using their own package name for the AnyTemplate |
| 1011 |
config name: |
| 1012 |
|
| 1013 |
$self->template(__PACKAGE__)->config(...); |
| 1014 |
$self->template(__PACKAGE__)->fill(...); |
| 1015 |
|
| 1016 |
CHANGING THE NAME OF THE 'template' METHOD |
| 1017 |
If you want to access the features of this module using a method other |
| 1018 |
than "template", you can do so via Anno Siegel's Exporter::Renaming |
| 1019 |
module (available on CPAN). |
| 1020 |
|
| 1021 |
For instance, to use syntax similar to CGI::Application::Plugin::TT: |
| 1022 |
|
| 1023 |
use Exporter::Renaming; |
| 1024 |
use CGI::Application::Plugin::AnyTemplate Renaming => [ template => tt]; |
| 1025 |
|
| 1026 |
sub cgiapp_init { |
| 1027 |
my $self = shift; |
| 1028 |
|
| 1029 |
my %params = ( ... ); |
| 1030 |
|
| 1031 |
# Set config file and other options |
| 1032 |
$self->tt->config( |
| 1033 |
default_type => 'TemplateToolkit', |
| 1034 |
); |
| 1035 |
|
| 1036 |
} |
| 1037 |
|
| 1038 |
sub my_runmode { |
| 1039 |
my $self = shift; |
| 1040 |
$self->tt->process('file', \%params); |
| 1041 |
} |
| 1042 |
|
| 1043 |
And to use syntax similar to CGI::Application's "load_tmpl" mechanism: |
| 1044 |
|
| 1045 |
use Exporter::Renaming; |
| 1046 |
use CGI::Application::Plugin::AnyTemplate Renaming => [ template => tmpl]; |
| 1047 |
|
| 1048 |
sub cgiapp_init { |
| 1049 |
my $self = shift; |
| 1050 |
|
| 1051 |
# Set config file and other options |
| 1052 |
$self->tmpl->config( |
| 1053 |
default_type => 'HTMLTemplate', |
| 1054 |
); |
| 1055 |
|
| 1056 |
} |
| 1057 |
|
| 1058 |
sub my_runmode { |
| 1059 |
my $self = shift; |
| 1060 |
|
| 1061 |
my %params = ( ... ); |
| 1062 |
|
| 1063 |
my $template = $self->tmpl->load('file'); |
| 1064 |
$template->param(\%params); |
| 1065 |
$template->output; |
| 1066 |
} |
| 1067 |
|
| 1068 |
AUTHOR |
| 1069 |
Michael Graham, "<[email protected]>" |
| 1070 |
|
| 1071 |
ACKNOWLEDGEMENTS |
| 1072 |
I originally wrote this to be a subsystem in Richard Dice's |
| 1073 |
CGI::Application-based framework, before I moved it into its own module. |
| 1074 |
|
| 1075 |
Various ideas taken from CGI::Application (Jesse Erlbaum), |
| 1076 |
CGI::Application::Plugin::TT (Cees Hek) and "Text::Boilerplate" (Stephen |
| 1077 |
Nelson). |
| 1078 |
|
| 1079 |
"Template::Toolkit" singleton support code stolen from |
| 1080 |
CGI::Application::Plugin::TT. |
| 1081 |
|
| 1082 |
BUGS |
| 1083 |
Please report any bugs or feature requests to |
| 1084 |
"[email protected]", or through the web |
| 1085 |
interface at <http://rt.cpan.org>. I will be notified, and then you'll |
| 1086 |
automatically be notified of progress on your bug as I make changes. |
| 1087 |
|
| 1088 |
SOURCE |
| 1089 |
The source code repository for this module can be found at |
| 1090 |
http://github.com/mgraham/CAP-AnyTemplate/ |
| 1091 |
|
| 1092 |
SEE ALSO |
| 1093 |
CGI::Application::Plugin::AnyTemplate::Base |
| 1094 |
CGI::Application::Plugin::AnyTemplate::ComponentHandler |
| 1095 |
CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplate |
| 1096 |
CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplateExpr |
| 1097 |
CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplatePluggable |
| 1098 |
CGI::Application::Plugin::AnyTemplate::Driver::TemplateToolkit |
| 1099 |
CGI::Application::Plugin::AnyTemplate::Driver::Petal |
| 1100 |
|
| 1101 |
CGI::Application |
| 1102 |
|
| 1103 |
Template::Toolkit |
| 1104 |
HTML::Template |
| 1105 |
|
| 1106 |
HTML::Template::Pluggable |
| 1107 |
HTML::Template::Plugin::Dot |
| 1108 |
|
| 1109 |
Petal |
| 1110 |
|
| 1111 |
Exporter::Renaming |
| 1112 |
|
| 1113 |
CGI::Application::Plugin::TT |
| 1114 |
|
| 1115 |
COPYRIGHT & LICENSE |
| 1116 |
Copyright 2005 Michael Graham, All Rights Reserved. |
| 1117 |
|
| 1118 |
This program is free software; you can redistribute it and/or modify it |
| 1119 |
under the same terms as Perl itself. |
| 1120 |
|