-
-
14 Nov 2009 17:23:02 UTC
- Distribution: Catalyst-View-TD
- Module version: 0.12
- Source (raw)
- Browse (raw)
- Changes
- How to Contribute
- Clone repository
- Issues (0)
- Testers (413 / 24 / 1)
- Kwalitee
Bus factor: 1- % Coverage
- License: perl_5
- Perl: v5.8.1
- Activity
24 month- Tools
- Download (35.54KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
- Dependencies
- Catalyst
- Class::Accessor
- File::Find
- MRO::Compat
- Template::Declare
- and possibly others
- Reverse dependencies
- CPAN Testers List
- Dependency graph
Name
Catalyst::View::TD - Catalyst Template::Declare View Class
Synopsis
Use the helper to create your view:
./script/myapp_create.pl view HTML TD
Create a template by editing lib/MyApp/Templates/HTML.pm:
template hello => sub { my ($self, $vars) = @_; html { head { title { "Hello, $vars->{user}" } }; body { h1 { "Hello, $vars->{user}" } }; }; };
Render the view from MyApp::Controller::SomeController:
sub message : Global { my ( $self, $c ) = @_; $c->stash->{template} = 'hello'; $c->stash->{user} = 'Slim Shady'; $c->forward( $c->view('HTML') ); }
Description
This is the Catalyst view class for Template::Declare. Your application should define a view class that subclasses this module. The easiest way to achieve this is using the myapp_create.pl script (where myapp should be replaced with whatever your application is called). This script is created as part of the Catalyst setup.
./script/myapp_create.pl view HTML TD
This creates a
MyApp::View::HTML
module in the lib directory (again, replacingMyApp
with the name of your application) that looks something like this:package MyApp::View::HTML; use strict; use warnings; use parent 'Catalyst::View::TD'; __PACKAGE__->config( # dispatch_to => [qw(MyApp::Templates::HTML)], # auto_alias => 1, # strict => 1, # postprocessor => sub { ... }, # around_template => sub { ... }, );
It also creates a
MyApp::Templates::HTML
template class that looks something like this:package MyApp::Templates::HTML; use strict; use warnings; use parent 'Template::Declare::Catalyst'; use Template::Declare::Tags; # template hello => sub { # my ($self, $vars) = @_; # html { # head { title { "Hello, $vars->{user}" } }; # body { h1 { "Hello, $vars->{user}" } }; # }; # };
Now you can modify your action handlers in the main application and/or controllers to forward to your view class. You might choose to do this in the
end()
method, for example, to automatically forward all actions to the TD view class.# In MyApp::Controller::SomeController sub end : Private { my( $self, $c ) = @_; $c->forward( $c->view('HTML') ); }
Configuration
There are a three different ways to configure your view class (see config for an explanation of the configuration options). The first way is to call the
config()
method in the view subclass. This happens when the module is first loaded.package MyApp::View::HTML; use strict; use parent 'Catalyst::View::TD'; __PACKAGE__->config({ dispatch_to => [ 'MyApp::Templates::HTML' ], auto_alias => 1, strict => 1, postprocessor => sub { ... }, around_template => sub { ... }, });
The second way is to define a
new()
method in your view subclass. This performs the configuration when the view object is created, shortly after being loaded. Remember to delegate to the base classnew()
method (via$self->next::method()
in the example below) after performing any configuration.sub new { my $self = shift; $self->config({ dispatch_to => [ 'MyApp::Templates::HTML' ], auto_alias => 1, strict => 1, postprocessor => sub { ... }, around_template => sub { ... }, }); return $self->next::method(@_); }
The final, and perhaps most direct way, is to call the ubiquitous
config()
method in your main application configuration. The items in the class hash are added to those already defined by the above two methods. This happens in the base classnew()
method (which is one reason why you must remember to call it viaMRO::Compat
if you redefine thenew()
method in a subclass).package MyApp; use strict; use Catalyst; MyApp->config({ name => 'MyApp', 'View::HTML' => { dispatch_to => [ 'MyApp::Templates::HTML' ], auto_alias => 1, strict => 1, postprocessor => sub { ... }, around_template => sub { ... }, }, });
Note that any configuration defined by one of the earlier methods will be overwritten by items of the same name provided by the later methods.
Auto-Aliasing
In addition to the dispatch template class (as defined in the
dispatch_to
configuration, or defaulting toMyApp::Templates::ViewName
), you can write templates in other classes and they will automatically be aliased into the dispatch class. The aliasing of templates is similar to how controller actions map to URLs.For example, say that you have a dispatch template class for your
MyApp::View::XHTML
view namedMyApp::Templates::XHTML
:package TestApp::Templates::XHTML; use parent 'Template::Declare::Catalyst'; use Template::Declare::Tags; template home => sub { html { head { title { 'Welcome home' } }; body { h1 { 'Welcome home' } }; }; };
This will handle a call to render the
/home
(or justhome
):$c->stash->{template} = 'home'; $c->forward( $c->view('XHTML') );
But let's say that you have a controller,
MyApp::Controller::Users
, that has an action namedlist
. Ideally what you'd like to do is to have it dispatch to a view named/users/list
. And sure enough, you can define one right in the dispatch class if you like:template 'users/list' => sub { my ($self, $args) = @_; ul { li { $_ } for @{ $args->{users} }; }; };
But it can get to be a nightmare to manage all of your templates in this one class. A better idea is to define them in multiple template classes just as you have actions in multiple controllers. The
auto_alias
feature of Catalyst::View::TD does just that. Rather than define a template namedusers/list
in the dispatch class (MyApp::Templates::XHTML
), create a new template class,MyApp::Templates::XHTML::Users
:./script/myapp_create.pl TDClass XHTML::Users
Then create a
list
template there:package TestApp::Templates::XHTML::Users; use parent 'Template::Declare::Catalyst'; use Template::Declare::Tags; template list => sub { my ($self, $args) = @_; ul { li { $_ } for @{ $args->{users} } }; };
Catalyst::View::TD will automatically import the templates found in all classes defined below the dispatch class. Thus this template will be imported as
users/list
. The nice thing about this is it allows you to create template classes with templates that correspond directly to controller classes and their actions.You can also use this approach to create utility templates. For example, if you wanted to put the header and footer output into utility templates, you could put them into a utility class:
package TestApp::Templates::XHTML::Util; use parent 'Template::Declare::Catalyst'; use Template::Declare::Tags; template header => sub { my ($self, $args) = @_; head { title { $args->{title} } }; }; template footer => sub { div { id is 'fineprint'; p { 'Site contents licensed under a Creative Commons License.' } }; };
And then you can simply use these templates from the dispatch class or any other aliased template class, including the dispatch class:
package TestApp::Templates::XHTML; use parent 'Template::Declare::Catalyst'; use Template::Declare::Tags; template home => sub { html { show '/util/header'; body { h1 { 'Welcome home' }; show '/util/footer'; }; }; };
And the users class:
package TestApp::Templates::XHTML::Users; use parent 'Template::Declare::Catalyst'; use Template::Declare::Tags; template list => sub { my ($self, $args) = @_; html { show '/util/header'; body { ul { li { $_ } for @{ $args->{users} } }; show '/util/footer'; }; }; };
If you'd rather control the importing of templates yourself, you can always set
auto_alias
to a false value. Then you'd just need to explicitly inherit fromTemplate::Declare::Catayst
and do the mixing yourself. The equivalent to the auto-aliasing in the above examples would be:package TestApp::Templates::XHTML; use parent 'Template::Declare::Catalyst'; use Template::Declare::Tags; use TestApp::Templates::XHTML::Users; use TestApp::Templates::XHTML::Util; alias TestApp::Templates::XHTML::Users under '/users'; alias TestApp::Templates::XHTML::Util under '/util';
This would be the way to go if you wanted finer control over Template::Declare's composition features.
Dynamic
dispatch_to
Sometimes it is desirable to modify
dispatch_to
for your templates at runtime. Additional paths can be prepended or appendeddispatch_to
via the stash as follows:$c->stash->{prepend_template_classes} = [ 'MyApp::Other::Templates' ]; $c->stash->{append_template_classes} = [ 'MyApp::Fallback::Templates' ];
If you need to munge the list of dispatch classes in more complex ways, there is also a
dispatch_to()
accessor:my $view = $c->view('HTML') splice @{ $view->dispatch_to }, 1, 0, 'My::Templates' unless grep { $_ eq 'My::Templates' } $view->dispatch_to;
Note that if you use
dispatch_to()
to change template classes, they are permanently changed. You therefore must check for duplicate paths if you do this on a per-request basis, as in this example. Otherwise, the class will continue to be added on every request, which would be a rather ugly memory leak.A safer approach is to use
dispatch_to()
to overwrite the array of template classes rather than adding to it. This eliminates both the need to perform duplicate checking and the chance of a memory leak:$c->view('HTML')->dispatch_to( ['My::Templates', 'Your::Templates'] );
This is safe to do on a per-request basis. But you're really better off using the stash approach. I suggest sticking to that when you can.
If you are calling
render
directly, then you can specify extra template classes under theprepend_template_classes
andappend_template_classes
keys. See "Capturing Template Output" for an example.Rendering Views
The Catalyst
view()
method renders the template specified in thetemplate
item in the stash.sub message : Global { my ( $self, $c ) = @_; $c->stash->{template} = 'message'; $c->forward( $c->view('HTML') ); }
If a stash item isn't defined, then it instead uses the stringification of the action dispatched to (as defined by
$c->action
). In the above example, this would bemessage
.The items defined in the stash are passed to the the Template::Declare template as a hash reference. Thus, for this controller action:
sub default : Private { my ( $self, $c ) = @_; $c->stash->{template} = 'message'; $c->stash->{message} = 'Hello World!'; $c->forward( $c->view('TD') ); }
Your template can use access the
message
key like so:template message => sub { my ($self, $args) = @_; h1 { $args->{message} }; };
Template classes are automatically subclasses of Template::Declare::Catalyst, which is itself a subclass of Template::Declare. Template::Declare::Catalyst provides a few extra accessors for use in your templates (though note that they will return
undef
if you callrender()
without a context object):context
-
A reference to the context object,
$c
c
-
An alias for
context()
These can be accessed from the template like so:
template message => sub { my ($self, $args) = @_; p { "The message is $args->{message}" }; p { "The base is " . $self->context->req->base }; p { "The name is " . $self->c->config->{name} }; };
The output generated by the template is stored in
$c->response->body
.Capturing Template Output
If you wish to use the output of a template for some purpose other than displaying in the response, e.g. for sending an email, use Catalyst::Plugin::Email and the render method:
sub send_email : Local { my ($self, $c) = @_; $c->email( header => [ To => 'me@localhost', Subject => 'A TD Email', ], body => $c->view('TD')->render($c, 'email', { prepend_template_classes => [ 'My::EmailTemplates' ], email_tmpl_param1 => 'foo' }), ); # Redirect or display a message }
Template Class Helper
In addition to the usual helper for creating TD views, you can also use the
TDClass
helper to create new template classes:./script/myapp_create.pl TDClass HTML::Users
This will create a new Template::Declare template class,
MyApp::Templates::HTML::Users
in the lib directory. This is perhaps best used in conjunction with creating a new controller for which you expect to create views:./script/myapp_create.pl controller Users ./script/myapp_create.pl TDClass HTML::Users
As explained in "Auto-Aliasing", if you already have the TD view
MyApp::View::HTML
, the templates in theMyApp::Templates::HTML::Users
class will be aliased under the/users
path. So if you defined alist
action in theUsers
controller and a correspondinglist
view in theHTML::Users
view, both would resolve to/users/list
.Methods
Constructor
new
my $view = MyApp::View::HTML->new( $c, $args );
The constructor for the TD view. Sets up the template provider and reads the application config. The
$args
hash reference, if present, overrides the application config.Class Methods
config
__PACKAGE__->config( dispatch_to => [qw(MyApp::Templates::HTML)], auto_alias => 1, strict => 1, postprocessor => sub { ... }, around_template => sub { ... }, );
Sets up the configuration your view subclass. All the settings are the same as for Template::Declare's
init()
method except:- auto_alias
-
Additional option. Determines whether or not classes found under the dispatch template's namespace are automatically aliased as described in "Auto-Aliasing".
- strict
-
Set to true by default so that exceptional conditions are appropriately fatal (it's false by default in Template::Declare).
Instance Methods
process
$view->process($c);
Renders the template specified in
$c->stash->{template}
or$c->action
(the private name of the matched action). Calls render() to perform actual rendering. Output is stored in$c->response->body
.render
my $output = $view->render( $c, $template_name, $args );
Renders the given template and returns output. Dies on error.
If
$args
is a hash reference, it will be passed to the template. Otherwise,$c->stash
will be passed if$c
is defined.SEE ALSO
Catalyst, Catalyst::View::TT, Catalyst::Helper::View::TD, Catalyst::Helper::TDClass, Template::Manual, http://justatheory.com/computers/programming/perl/catalyst/
Author
David E. Wheeler <david@justatheory.com>
Copyright
This program is free software. You can redistribute it and/or modify it under the same terms as Perl itself.
Module Install Instructions
To install Catalyst::View::TD, copy and paste the appropriate command in to your terminal.
cpanm Catalyst::View::TD
perl -MCPAN -e shell install Catalyst::View::TD
For more information on module installation, please visit the detailed CPAN module installation guide.