Debian Codegraph @

README

raw
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