Catalyst::View::Templated - generic base class for template-based views

View::Templated makes all (template-based) Catalyst views work the same way:

   # setup the config
   MyApp->config->{View::SomeEngine} 
     = { TEMPLATE_EXTENSION => '.tmpl',
         CATALYST_VAR       => 'c',
         INCLUDE_PATH       => ['root', 'root/my_theme'], # defaults to root
         CONTENT_TYPE       => 'application/xhtml+xml', # defaults to text/html
       };

   # set the template in your action
   $c->view('View::SomeEngine')->template('the_template_name');
   # or let it guess the template name from the action name and EXTENSION

   # capture the text of the template
   my $output = $c->view('View::SomeEngine')->render;

   # process a template (in an end action)
   $c->detach('View::Name');
   $c->view('View::Name')->process;

Called by Catalyst when creating the component.

Set the template to $template, or return the current template is $template is undefined.

Called by Catalyst to render a template. Renders the template returned by $self->template and sets the response body to the result of the template evaluation.

Also sets up a content-type header for text/html with the charset of the data (utf8 if the data contains utf8 characters, iso-8859-1 otherwise).

Renders the named template and returns the output. If $template is omitted, it is determined by calling $self->template.

You can also omit $c. If the first arg is a reference, it will be treated as $c. If it's not, then it will be treated as the name of the template to render.

If you only want to supply $args, pass undef as the first argument, before $args.

Supplying no arguments at all is also legal.

Old style:

   $c->view('TT')->render($c, 'template', { args => 'here' });

New style:

   $c->view('TT')->render('template', { args => 'here' });
   $c->view('TT')->render('template'); # no args

   $c->view('TT')->template('template');
   $c->view('TT')->render(undef, { args => 'here' });
   $c->view('TT')->render; # no args

All you need to do is implement a new method (for setup) and a _render method that accepts a template name, a hashref of paramaters, and a hashref of arguments (optional, passed to render by the user), and returns the rendered template. This class will handle converting the stash to a hashref for you, so you don't need to worry about munging it to get the context, base, or name. Just render with what you're given. It's what the user wants.

Example:

   package Catalyst::View::MyTemplate;
   use base 'Catalyst::View::Templated';

   sub new {
      my ($class, $c, $args) = @_;
      my $self = $class->next::method($c, $args);

      $self->{engine} = MyTemplate->new(include => $self->{INCLUDE_PATH});
      return $self;
   }

   sub _render {
      my ($self, $template, $stash, $args) = @_;
      my $engine = $self->{engine};

      return $engine->render_template($template, $stash, $args);
   }

Now your View will work exactly like every other Catalyst View. All you have to worry about is sending a hashref into a template and returning the result. Easy!

We're using Class::C3 instead of NEXT (NEXT). Don't use NEXT anymore.

Returning false from _render is not an error. If something bad happens, throw an exception. The error will automatically be handled appropriately; all you need to do is die with an informative message.

The message shown to the user is:

   Couldn't render template '$template': $@

$@ is whatever you invoked die against.

$self->{INCLUDE_PATH}

An array ref containing the user's desired include paths. This is set to a reasonable default (root/) if the user omits it from his config.

Jonathan Rockway jrockway AT cpan.org.

Copyright (c) 2007 Jonathan Rockway. You may distribute this module under the same terms as Perl itself.