Jonathan Rockway > Catalyst-View-Templated-0.02 > Catalyst::View::Templated

Download:
Catalyst-View-Templated-0.02.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  2
Open  0
View/Report Bugs
Module Version: 0.02   Source  

NAME ^

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

SYNOPSIS ^

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;

METHODS ^

new($c, $args)

Called by Catalyst when creating the component.

template([$template])

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

process

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).

render([[$c], [$template, [$args]]])

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

IMPLEMENTING A SUBCLASS ^

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!

VARIABLES FOR YOU

$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.

AUTHOR ^

Jonathan Rockway jrockway AT cpan.org.

LICENSE ^

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

syntax highlighting: