package CGI::Application::Plugin::HTCompiled;
use CGI::Application 4.31;
use 5.006;
use strict;
use warnings;
=head1 NAME
CGI::Application::Plugin::HTCompiled - Integrate with HTML::Template::Compiled
=cut
$CGI::Application::Plugin::HTCompiled::VERSION = '2.0';
use vars qw( $VERSION );
=head1 SYNOPSIS
# In your CGI::Application-derived base class. . .
use base "CGI::Application";
use CGI::Application::Plugin::HTCompiled;
# 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" );
$tmpl_view->param( user => $user );
return $tmpl_view->output();
}
=head1 DESCRIPTION
Allows you to use L<HTML::Template::Compiled> as a seamless replacement
for HTML::Template, as far as is possible with that module.
=head1 DEFAULT PARAMETERS
By default, the HTCompiled plugin will automatically add a parameter 'c' to the template that
will return to your CGI::Application object $self. This allows you to access any
methods in your CGI::Application module that you could normally call on $self
from within your template. This allows for some powerful actions in your templates.
For example, your templates will be able to access query parameters, or if you use
the CGI::Application::Plugin::Session module, you can access session parameters.
<a href="<tmpl_var c.query.self_url>">Reload this page</a>
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).
=head1 FUNCTIONS
=head2 import()
Will be called when your Module uses L<HTML::Template::Compiled>. Registers
callbacks at the inti and the load_tmpl stages.
=cut
sub import {
my $caller = scalar( caller );
$caller->add_callback( 'init' => \&_add_init );
$caller->add_callback( 'load_tmpl' => \&_pass_in_self );
goto &Exporter::import;
} # /import
=head2 _pass_in_self()
Adds the parameter c each template that will be processed. See DEFAULT PARAMETERS
for more information.
=cut
sub _pass_in_self {
my ( $self, $one, $tmpl_params, $template_file ) = @_;
warn("Template param 'c' will be overwritten.") if exists $tmpl_params->{c};
$tmpl_params->{c} = $self;
} # /_pass_in_self
=head2 _add_init()
Set html_tmpl_class to L<HTML::Template::Compiled> at the init stage. That way,
each time a template is loaded using load_tmpl, an instance of
HTML::Template::Compiled will be created instead of the defualt HTML::Template.
See the l<CGI::Appliaction> manpage for more information.
=cut
sub _add_init {
my $self = shift;
$self->html_tmpl_class('HTML::Template::Compiled');
} # /_add_init
=head2 Extending load_tmpl()
There are times when the basic C<load_tmpl()> functionality just isn't
enough. The easiest way to do this is by replacing or
extending the functionality of L<CGI::Application>'s C<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, "cache", "1";
return $self->SUPER::load_tmpl($tmpl_file, @extra_params);
}
=head1 BACKWARDS COMPATIBILITY
As of version 2.0, CGI::Application::Plugin::HTCompiled breaks backwards compatibility.
No interface has been changed, you can still use the load_tmpl() method as you did before.
The difference is, that you don't use the plugin via multiple inheritance anymore,
but simply use it.
Old usage:
# In your CGI::Application-derived base class. . .
use base ("CGI::Application::Plugin::HTCompiled", "CGI::Application");
New usage:
# In your CGI::Application-derived base class. . .
use base "CGI::Application";
use CGI::Application::Plugin::HTCompiled;
Multiple inheritance was the onyl way before CGI::Application v. 4.13 to use
HTML::Template::Compiled with the standard load_tmpl() method.
Now, there is no need to use language specific features (such as multiple
inheritance) to implement plugin behavior, because we now have a proper way to
do such plugins. This is the reason why we break backwards compatibility.
If you depend on the old interface, use an older version of this module, such as 1.01.
There is no difference in using this module in version 1.01 or 2.0. No
interface has been changed. It's only the way to actually "use" the plugin,
that changed.
=head1 AUTHOR
Mark Stosberg C<< <mark@summersault.com> >>
...but largely modeled on HTDot plugin by Jason A. Crome.
=head1 BUGS
Please report any bugs or feature requests to
C<bug-cgi-application-plugin-htcompiled@rt.cpan.org>, or through the web interface at
L<
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CGI-Application-Plugin-HTCompiled>.
I will be notified, and then you'll automatically be notified of progress on
your bug as I make changes.
=head1 ACKNOWLEDGEMENTS
The usual crowd in #cgiapp on irc.perl.org
=head1 SEE ALSO
L<CGI::Application>, L<HTML::Template>, L<HTML::Template::Compiled>,
=head1 COPYRIGHT & LICENSE
Copyright 2005 Mark Stosberg, all rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
=cut
1; # End of CGI::Application::Plugin::HTCompiled
RT for rt.cpan.org