1NAME
2 CGI::Application::Plugin::HTDot - Enable "magic dot" notation in
3 CGI::Application-derived applications that use HTML::Template for their
4 templating mechanism.
5
6VERSION
7 Version 0.07
8
9SYNOPSIS
10 # In your CGI::Application-derived base class. . .
11 use base ("CGI::Application::Plugin::HTDot", "CGI::Application");
12
13 # Later, in a run mode far, far away. . .
14 sub view {
15 my $self = shift;
16 my $username = $self->query->param( 'user' );
17 my $user = My::Users->retrieve( $username );
18
19 my $tmpl_view = $self->load_tmpl( 'view_user.tmpl' );
20
21 # The magic happens here! Pass our Class::DBI object
22 # to the template and display it
23 $tmpl_view->param( user => $user );
24
25 return $tmpl_view->output;
26 }
27
28DESCRIPTION
29 Imagine this: you've written a lot of code based upon CGI::Application,
30 and also with HTML::Template because the two have always had such a high
31 level of integration. You reach a situation (many times, perhaps) where
32 you could really use the power and convenience of being able to pass
33 objects to your templates and call methods of those objects from within
34 your template (ala Template Toolkit), but your development schedule
35 doesn't give you the time to learn (much less migrate to!) Template
36 Toolkit or AnyTemplate. Well, you need fret no more!
37 "CGI::Application::Plugin::HTDot" helps you bring the power of the magic
38 dot to your HTML::Template-based templates from within your
39 CGI::Application-derived webapps.
40
41 CGI::Application::Plugin::HTDot provides the glue between
42 CGI::Application, HTML::Template::Pluggable and
43 HTML::Template::Plugin::Dot. It overrides the "load_tmpl()" method
44 provided with CGI::Application and replaces it with one that turns on
45 the magic dot in HTML::Template. The "load_tmpl()" method provided here
46 is 100% compatible with the one found in a stock CGI::Application app,
47 so using this plugin does not require refactoring of any code. You can
48 use the magic dot in your application and templates going forward, and
49 refactor older code to use it as your schedule permits.
50
51 When you have lots of apps and lots of templates, and no means to switch
52 to Template Toolkit, this will make your life infinitely easier.
53
54 For more information about the magic dot, see
55 HTML::Template::Plugin::Dot.
56
57 As of version 4.31 of " CGI::Application ", you can use the "
58 html_tmpl_class() " method as an alternative to this plugin. TIMTOWTDI.
59
60METHODS
61 load_tmpl()
62 For the most part, this is the exact "load_tmpl()" method from
63 CGI::Application, except it uses HTML::Template::Pluggable and
64 HTML::Template::Plugin::Dot instead of HTML::Template.
65
66 See the CGI::Application reference for more detailed information on what
67 parameters can be passed to "load_tmpl()".
68
69 Extending load_tmpl()
70 There are times when the basic "load_tmpl()" functionality just isn't
71 enough. Many HTML::Template developers set "die_on_bad_params" to 0 on
72 all of their templates. The easiest way to do this is by replacing or
73 extending the functionality of CGI::Application's "load_tmpl()" method.
74 This is still possible using the plugin.
75
76 The following code snippet illustrates one possible way of achieving
77 this:
78
79 sub load_tmpl {
80 my ($self, $tmpl_file, @extra_params) = @_;
81
82 push @extra_params, "die_on_bad_params", "0";
83 push @extra_params, "cache", "1";
84
85 return $self->SUPER::load_tmpl($tmpl_file, @extra_params);
86 }
87
88 This plugin honors the "load_tmpl()" callback. Any "load_tmpl()"-based
89 callbacks you have created will be executed as intended:
90
91DEFAULT PARAMETERS
92 By default, this plugin will automatically add a parameter 'c' to your
93 template that will return your CGI::Application object. This will allow
94 you to access any methods in your application from within your template.
95 This allows for some powerful actions in your templates. For example,
96 your templates can access query parameters, or if you use the excellent
97 CGI::Application::Plugin::Session module, you can access session
98 parameters:
99
100 Hello <tmpl_var c.session.param('username')>!
101
102 <a href="<tmpl_var c.query.self_url>">Reload this page</a>
103
104 Another useful plugin that can use this feature is the
105 CGI::Application::Plugin::HTMLPrototype plugin, which gives easy access
106 to the prototype.js JavaScript library:
107
108 <tmpl_var c.prototype.define_javascript_functions>
109 <a href="#" onclick="javascript:<tmpl_var c.prototype.visual_effect( 'Appear', 'extra_info' )>; return false;">Extra Info</a>
110 <div style="display: none" id="extra_info">Here is some more extra info</div>
111
112 With this extra flexibility comes some responsibilty as well. It could
113 lead down a dangerous path if you start making alterations to your
114 object from within the template. For example you could call c.header_add
115 to add new outgoing headers, but that is something that should be left
116 in your code, not in your template. Try to limit yourself to pulling in
117 information into your templates (like the session example above does).
118
119 This plugin will respect your current "die_on_bad_params" setting. If
120 "die_on_bad_params" is set to 1 and your template does not use 'c', the
121 plugin will not attempt to pass the CGI::Application object to your
122 template. In other words, it does not force your application to set
123 "die_on_bad_params" to 0 to accomplish this action.
124
125AUTHOR
126 Jason A. Crome, "<cromedome@cpan.org>"
127
128BUGS
129 Please report any bugs or feature requests to
130 "bug-cgi-application-plugin-htdot@rt.cpan.org", or through the web
131 interface at
132 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CGI-Application-Plugin-H
133 TDot>. I will be notified, and then you'll automatically be notified of
134 progress on your bug as I make changes.
135
136ACKNOWLEDGMENTS
137 Thanks and credit needs to be given to Jesse Erlbaum and Mark Stosberg
138 for the original "load_tmpl()" method that this is based on, to Rhesa
139 Rozendaal and Mark Stosberg for their work on enabling the magic dot in
140 HTML::Template, Cees Hek for his idea (and tutorial on how) to use
141 multiple inheritance to make this plugin work, and to the usual crowd in
142 #cgiapp on irc.perl.org for making this all worthwhile for me :)
143
144 An extra special thanks to Cees Hek for the inspiration, code, and
145 examples to implement the 'c' parameter in templates.
146
147SEE ALSO
148 CGI::Application, HTML::Template, HTML::Template::Pluggable,
149 HTML::Template::Plugin::Dot, CGI::Application::Plugin::TT.
150
151COPYRIGHT & LICENSE
152 Copyright (C) 2005-2007, Jason A. Crome. All rights reserved.
153
154 This program is free software; you can redistribute it and/or modify it
155 under the same terms as Perl itself.
156
157