CGI::Application::Plugin::HTDot - Enable "magic dot" notation in the CGI::Application manpage-derived applications that use the HTML::Template manpage for their templating mechanism.
Version 0.06
# In your CGI::Application-derived base class. . .
use base ("CGI::Application::Plugin::HTDot", "CGI::Application");
# Later, in a run mode far, far away. . .
sub view {
my $self = shift;
my $username = $self->query->param( 'user' );
my $user = My::Users->retrieve( $username );
my $tmpl_view = $self->load_tmpl( 'view_user.tmpl' );
# The magic happens here! Pass our Class::DBI object
# to the template and display it
$tmpl_view->param( user => $user );
return $tmpl_view->output;
}
Imagine this: you've written a lot of code based upon the CGI::Application manpage, and
also with the HTML::Template manpage because the two have always had such a high level
of integration. You reach a situation (many times, perhaps) where you could
really use the power and convenience of being able to pass objects to your
templates and call methods of those objects from within your template (ala
Template Toolkit), but your development schedule doesn't give you the time
to learn (much less migrate to!) Template Toolkit or AnyTemplate. Well, you
need fret no more! CGI::Application::Plugin::HTDot helps you bring the
power of the magic dot to your the HTML::Template manpage-based templates from within
your the CGI::Application manpage-derived webapps.
the CGI::Application::Plugin::HTDot manpage provides the glue between
the CGI::Application manpage, the HTML::Template::Pluggable manpage and
the HTML::Template::Plugin::Dot manpage. It overrides the load_tmpl() method
provided with the CGI::Application manpage and replaces it with one that turns on the
magic dot in the HTML::Template manpage. The load_tmpl() method provided here is
100% compatible with the one found in a stock the CGI::Application manpage app, so
using this plugin does not require refactoring of any code. You can use the
magic dot in your application and templates going forward, and refactor older
code to use it as your schedule permits.
When you have lots of apps and lots of templates, and no means to switch to Template Toolkit, this will make your life infinitely easier.
For more information about the magic dot, see the HTML::Template::Plugin::Dot manpage.
load_tmpl()For the most part, this is the exact load_tmpl() method from
the CGI::Application manpage, except it uses the HTML::Template::Pluggable manpage and
the HTML::Template::Plugin::Dot manpage instead of the HTML::Template manpage.
See the the CGI::Application manpage reference for more detailed information
on what parameters can be passed to load_tmpl().
load_tmpl()There are times when the basic load_tmpl() functionality just isn't
enough. Many the HTML::Template manpage developers set die_on_bad_params to 0
on all of their templates. The easiest way to do this is by replacing or
extending the functionality of the CGI::Application manpage's load_tmpl() method.
This is still possible using the plugin.
The following code snippet illustrates one possible way of achieving this:
sub load_tmpl { my ($self, $tmpl_file, @extra_params) = @_;
push @extra_params, "die_on_bad_params", "0";
push @extra_params, "cache", "1";
return $self->SUPER::load_tmpl($tmpl_file, @extra_params);
}
This plugin honors the load_tmpl() callback. Any load_tmpl()-based
callbacks you have created will be executed as intended:
By default, this plugin will automatically add a parameter 'c' to your template that will return your the CGI::Application manpage object. This will allow you to access any methods in your application from within your template. This allows for some powerful actions in your templates. For example, your templates can access query parameters, or if you use the excellent the CGI::Application::Plugin::Session manpage module, you can access session parameters:
Hello <tmpl_var c.session.param('username')>!
<a href="<tmpl_var c.query.self_url>">Reload this page</a>
Another useful plugin that can use this feature is the the CGI::Application::Plugin::HTMLPrototype manpage plugin, which gives easy access to the prototype.js JavaScript library:
<tmpl_var c.prototype.define_javascript_functions>
<a href="#" onclick="javascript:<tmpl_var c.prototype.visual_effect( 'Appear', 'extra_info' )>; return false;">Extra Info</a>
<div style="display: none" id="extra_info">Here is some more extra info</div>
With this extra flexibility comes some responsibilty as well. It could lead down a dangerous path if you start making alterations to your object from within the template. For example you could call c.header_add to add new outgoing headers, but that is something that should be left in your code, not in your template. Try to limit yourself to pulling in information into your templates (like the session example above does).
This plugin will respect your current die_on_bad_params setting. If
die_on_bad_params is set to 1 and your template does not use 'c', the
plugin will not attempt to pass the the CGI::Application manpage object to your
template. In other words, it does not force your application to set
die_on_bad_params to 0 to accomplish this action.
Jason A. Crome, <cromedome@cpan.org>
Please report any bugs or feature requests to
bug-cgi-application-plugin-htdot@rt.cpan.org, or through the web interface at
http://rt.cpan.org/NoAuth/ReportBug.html.
I will be notified, and then you'll automatically be notified of progress on
your bug as I make changes.
Thanks and credit needs to be given to Jesse Erlbaum and Mark Stosberg for the
original load_tmpl() method that this is based on, to Rhesa Rozendaal and
Mark Stosberg for their work on enabling the magic dot in the HTML::Template manpage,
Cees Hek for his idea (and tutorial on how) to use multiple inheritance to
make this plugin work, and to the usual crowd in #cgiapp on irc.perl.org for
making this all worthwhile for me :)
An extra special thanks to Cees Hek for the inspiration, code, and examples to implement the 'c' parameter in templates.
the CGI::Application manpage, the HTML::Template manpage, the HTML::Template::Pluggable manpage, the HTML::Template::Plugin::Dot manpage, the CGI::Application::Plugin::TT manpage.
Copyright (C) 2005-2007, Jason A. Crome. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.