X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FView%2FTT.pm;h=f545ea434ff6fc397c655130e79d13ed508c6d84;hb=ee06e29a8475f5dd926aa81c6fcce4f75b7d7585;hp=80ab8546be31363175cd9a3c59892f6c664dc788;hpb=940a2e8aca13f60eb214dabbc8152a8f1268437d;p=catagits%2FCatalyst-View-TT.git

diff --git a/lib/Catalyst/View/TT.pm b/lib/Catalyst/View/TT.pm
index 80ab854..f545ea4 100644
--- a/lib/Catalyst/View/TT.pm
+++ b/lib/Catalyst/View/TT.pm
@@ -8,11 +8,15 @@ use Data::Dump 'dump';
 use Template;
 use Template::Timer;
 use MRO::Compat;
+use Scalar::Util qw/blessed weaken/;
 
-our $VERSION = '0.33';
+our $VERSION = '0.41';
+$VERSION = eval $VERSION;
 
 __PACKAGE__->mk_accessors('template');
+__PACKAGE__->mk_accessors('expose_methods');
 __PACKAGE__->mk_accessors('include_path');
+__PACKAGE__->mk_accessors('content_type');
 
 *paths = \&include_path;
 
@@ -24,27 +28,31 @@ Catalyst::View::TT - Template View Class
 
 # use the helper to create your View
 
-    myapp_create.pl view TT TT
+    myapp_create.pl view Web TT
 
-# configure in lib/MyApp.pm (Could be set from configfile instead)
+# add custom configration in View/Web.pm
 
     __PACKAGE__->config(
-        name         => 'MyApp',
-        root         => MyApp->path_to('root'),
-        default_view => 'TT',
-        'View::TT' => {
-            # any TT configurations items go here
+        # any TT configuration items go here
+        TEMPLATE_EXTENSION => '.tt',
+        CATALYST_VAR => 'c',
+        TIMER        => 0,
+        ENCODING     => 'utf-8'
+        # Not set by default
+        PRE_PROCESS        => 'config/main',
+        WRAPPER            => 'site/wrapper',
+        render_die => 1, # Default for new apps, see render method docs
+        expose_methods => [qw/method_in_view_class/],
+    );
+
+# add include path configuration in MyApp.pm
+
+    __PACKAGE__->config(
+        'View::Web' => {
             INCLUDE_PATH => [
-              MyApp->path_to( 'root', 'src' ),
-              MyApp->path_to( 'root', 'lib' ),
+                __PACKAGE__->path_to( 'root', 'src' ),
+                __PACKAGE__->path_to( 'root', 'lib' ),
             ],
-            TEMPLATE_EXTENSION => '.tt',
-            CATALYST_VAR => 'c',
-            TIMER        => 0,
-            # Not set by default
-            PRE_PROCESS        => 'config/main',
-            WRAPPER            => 'site/wrapper',
-            render_die => 1, # Default for new apps, see render method docs
         },
     );
 
@@ -54,7 +62,7 @@ Catalyst::View::TT - Template View Class
         my ( $self, $c ) = @_;
         $c->stash->{template} = 'message.tt2';
         $c->stash->{message}  = 'Hello World!';
-        $c->forward( $c->view('TT') );
+        $c->forward( $c->view('Web') );
     }
 
 # access variables from template
@@ -90,6 +98,7 @@ sub new {
     my $config = {
         EVAL_PERL          => 0,
         TEMPLATE_EXTENSION => '',
+        CLASS              => 'Template',
         %{ $class->config },
         %{$arguments},
     };
@@ -131,6 +140,7 @@ sub new {
     # Set base include paths. Local'd in render if needed
     $self->include_path($config->{INCLUDE_PATH});
 
+    $self->expose_methods($config->{expose_methods});
     $self->config($config);
 
     # Creation of template outside of call to new so that we can pass [ $self ]
@@ -188,8 +198,8 @@ sub new {
     }
 
     $self->{template} =
-        Template->new($config) || do {
-            my $error = Template->error();
+        $config->{CLASS}->new($config) || do {
+            my $error = $config->{CLASS}->error();
             $c->log->error($error);
             $c->error($error);
             return undef;
@@ -213,14 +223,15 @@ sub process {
     local $@;
     my $output = eval { $self->render($c, $template) };
     if (my $err = $@) {
-        my $error = qq/Couldn't render template "$template"/;
-        $c->log->error($error);
-        $c->error($error);
-        return 0;
+        return $self->_rendering_error($c, $template . ': ' . $err);
+    }
+    if (blessed($output) && $output->isa('Template::Exception')) {
+        $self->_rendering_error($c, $output);
     }
 
     unless ( $c->response->content_type ) {
-        $c->response->content_type('text/html; charset=utf-8');
+        my $default = $self->content_type || 'text/html; charset=utf-8';
+        $c->response->content_type($default);
     }
 
     $c->response->body($output);
@@ -228,6 +239,14 @@ sub process {
     return 1;
 }
 
+sub _rendering_error {
+    my ($self, $c, $err) = @_;
+    my $error = qq/Couldn't render template "$err"/;
+    $c->log->error($error);
+    $c->error($error);
+    return 0;
+}
+
 sub render {
     my ($self, $c, $template, $args) = @_;
 
@@ -248,8 +267,7 @@ sub render {
             die $self->template->error if $self->{render_die};
             return $self->template->error;
         }
-        require Carp;
-        Carp::carp('The Catalyst::View::TT render() method of will die on error in a future release. If you want it to continue to return the exception instead, pass render_die => 0 to the constructor');
+        $c->log->debug('The Catalyst::View::TT render() method will start dying on error in a future release. Unless you are calling the render() method manually, you probably want the new behaviour, so set render_die => 1 in config for ' . blessed($self) . '. If you wish to continue to return the exception rather than throwing it, add render_die => 0 to your config.') if $c && $c->debug;
         return $self->template->error;
     }
     return $output;
@@ -261,16 +279,33 @@ sub template_vars {
     return  () unless $c;
     my $cvar = $self->config->{CATALYST_VAR};
 
-    defined $cvar
+    my %vars = defined $cvar
       ? ( $cvar => $c )
       : (
         c    => $c,
         base => $c->req->base,
         name => $c->config->{name}
-      )
+      );
+
+    if ($self->expose_methods) {
+        my $meta = $self->meta;
+        foreach my $method_name (@{$self->expose_methods}) {
+            my $method = $meta->find_method_by_name( $method_name );
+            unless ($method) {
+                Catalyst::Exception->throw( "$method_name not found in TT view" );
+            }
+            my $method_body = $method->body;
+            my $weak_ctx = $c;
+            weaken $weak_ctx;
+            my $sub = sub {
+                $self->$method_body($weak_ctx, @_);
+            };
+            $vars{$method_name} = $sub;
+        }
+    }
+    return %vars;
 }
 
-
 1;
 
 __END__
@@ -279,23 +314,23 @@ __END__
 
 This is the Catalyst view class for the L<Template Toolkit|Template>.
 Your application should defined a view class which is a subclass of
-this module.  The easiest way to achieve this is using the
-F<myapp_create.pl> script (where F<myapp> should be replaced with
-whatever your application is called).  This script is created as part
-of the Catalyst setup.
+this module. Throughout this manual it will be assumed that your application
+is named F<MyApp> and you are creating a TT view named F<Web>; these names
+are placeholders and should always be replaced with whatever name you've
+chosen for your application and your view. The easiest way to create a TT
+view class is through the F<myapp_create.pl> script that is created along
+with the application:
 
-    $ script/myapp_create.pl view TT TT
+    $ script/myapp_create.pl view Web TT
 
-This creates a MyApp::View::TT.pm module in the F<lib> directory (again,
+This creates a F<MyApp::View::Web.pm> module in the F<lib> directory (again,
 replacing C<MyApp> with the name of your application) which looks
 something like this:
 
-    package FooBar::View::TT;
+    package FooBar::View::Web;
+    use Moose;
 
-    use strict;
-    use warnings;
-
-    use base 'Catalyst::View::TT';
+    extends 'Catalyst::View::TT';
 
     __PACKAGE__->config(DEBUG => 'all');
 
@@ -308,7 +343,7 @@ to the TT view class.
 
     sub end : Private {
         my( $self, $c ) = @_;
-        $c->forward( $c->view('TT') );
+        $c->forward( $c->view('Web') );
     }
 
 But if you are using the standard auto-generated end action, you don't even need
@@ -320,7 +355,7 @@ to do this!
     # in MyApp.pm
     __PACKAGE__->config(
         ...
-        default_view => 'TT',
+        default_view => 'Web',
     );
 
 This will Just Work.  And it has the advantages that:
@@ -336,7 +371,7 @@ for details.
 =item *
 
 << $c->res->redirect >> is handled by default.  If you just forward to 
-C<View::TT> in your C<end> routine, you could break this by sending additional
+C<View::Web> in your C<end> routine, you could break this by sending additional
 content.
 
 =back
@@ -349,68 +384,45 @@ There are a three different ways to configure your view class.  The
 first way is to call the C<config()> method in the view subclass.  This
 happens when the module is first loaded.
 
-    package MyApp::View::TT;
-
-    use strict;
-    use base 'Catalyst::View::TT';
+    package MyApp::View::Web;
+    use Moose;
+    extends 'Catalyst::View::TT';
 
-    MyApp::View::TT->config({
-        INCLUDE_PATH => [
-            MyApp->path_to( 'root', 'templates', 'lib' ),
-            MyApp->path_to( 'root', 'templates', 'src' ),
-        ],
+    __PACKAGE__->config({
         PRE_PROCESS  => 'config/main',
         WRAPPER      => 'site/wrapper',
     });
 
-The second way is to define a C<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 class
-C<new()> method (via C<$self-E<gt>next::method()> in the example below) after
-performing any configuration.
+You may also override the configuration provided in the view class by adding
+a 'View::Web' section to your application config.
 
-    sub new {
-        my $self = shift;
-        $self->config({
+This should generally be used to inject the include paths into the view to
+avoid the view trying to load the application to resolve paths.
+
+    .. inside MyApp.pm ..
+    __PACKAGE__->config(
+        'View::Web' => {
             INCLUDE_PATH => [
-                MyApp->path_to( 'root', 'templates', 'lib' ),
-                MyApp->path_to( 'root', 'templates', 'src' ),
+                __PACKAGE__->path_to( 'root', 'templates', 'lib' ),
+                __PACKAGE__->path_to( 'root', 'templates', 'src' ),
             ],
-            PRE_PROCESS  => 'config/main',
-            WRAPPER      => 'site/wrapper',
-        });
-        return $self->next::method(@_);
-    }
+        },
+    );
 
-The final, and perhaps most direct way, is to define a class
-item in your main application configuration, again by calling the
-ubiquitous C<config()> method.  The items in the class hash are
-added to those already defined by the above two methods.  This happens
-in the base class new() method (which is one reason why you must
-remember to call it via C<MRO::Compat> if you redefine the C<new()>
-method in a subclass).
+You can also configure your view from within your config file if you're
+using L<Catalyst::Plugin::ConfigLoader>. This should be reserved for
+deployment-specific concerns. For example:
 
-    package MyApp;
+    # MyApp_local.conf (Config::General format)
 
-    use strict;
-    use Catalyst;
+    <View Web>
+      WRAPPER "custom_wrapper"
+      INCLUDE_PATH __path_to('root/templates/custom_site')__
+      INCLUDE_PATH __path_to('root/templates')__
+    </View>
 
-    MyApp->config({
-        name     => 'MyApp',
-        root     => MyApp->path_to('root'),
-        'View::TT' => {
-            INCLUDE_PATH => [
-                MyApp->path_to( 'root', 'templates', 'lib' ),
-                MyApp->path_to( 'root', 'templates', 'src' ),
-            ],
-            PRE_PROCESS  => 'config/main',
-            WRAPPER      => 'site/wrapper',
-        },
-    });
-
-Note that any configuration items defined by one of the earlier
-methods will be overwritten by items of the same name provided by the
-latter methods.
+might be used as part of a simple way to deploy different instances of the
+same application with different themes.
 
 =head2 DYNAMIC INCLUDE_PATH
 
@@ -425,7 +437,7 @@ follows:
 If you need to add paths to the end of INCLUDE_PATH, there is also an
 include_path() accessor available:
 
-    push( @{ $c->view('TT')->include_path }, qw/path/ );
+    push( @{ $c->view('Web')->include_path }, qw/path/ );
 
 Note that if you use include_path() to add extra paths to INCLUDE_PATH, you
 MUST check for duplicate paths. Without such checking, the above code will add
@@ -435,12 +447,18 @@ A safer approach is to use include_path() to overwrite the array of paths
 rather than adding to it. This eliminates both the need to perform duplicate
 checking and the chance of a memory leak:
 
-    @{ $c->view('TT')->include_path } = qw/path another_path/;
+    @{ $c->view('Web')->include_path } = qw/path another_path/;
 
 If you are calling C<render> directly then you can specify dynamic paths by
 having a C<additional_template_paths> key with a value of additonal directories
 to search. See L<CAPTURING TEMPLATE OUTPUT> for an example showing this.
 
+=head2 Unicode
+
+Be sure to set C<< ENCODING => 'utf-8' >> and use
+L<Catalyst::Plugin::Unicode::Encoding> if you want to use non-ascii
+characters (encoded as utf-8) in your templates.
+
 =head2 RENDERING VIEWS
 
 The view plugin renders the template specified in the C<template>
@@ -449,7 +467,7 @@ item in the stash.
     sub message : Global {
         my ( $self, $c ) = @_;
         $c->stash->{template} = 'message.tt2';
-        $c->forward( $c->view('TT') );
+        $c->forward( $c->view('Web') );
     }
 
 If a stash item isn't defined, then it instead uses the
@@ -464,7 +482,7 @@ use as template variables.
         my ( $self, $c ) = @_;
         $c->stash->{template} = 'message.tt2';
         $c->stash->{message}  = 'Hello World!';
-        $c->forward( $c->view('TT') );
+        $c->forward( $c->view('Web') );
     }
 
 A number of other template variables are also added:
@@ -498,7 +516,7 @@ L<Catalyst::Plugin::Email> and the L<render> method:
         To      => 'me@localhost',
         Subject => 'A TT Email',
       ],
-      body => $c->view('TT')->render($c, 'email.tt', {
+      body => $c->view('Web')->render($c, 'email.tt', {
         additional_template_paths => [ $c->config->{root} . '/email_templates'],
         email_tmpl_param1 => 'foo'
         }
@@ -527,7 +545,7 @@ perform actual rendering. Output is stored in C<< $c->response->body >>.
 It is possible to forward to the process method of a TT view from inside
 Catalyst like this:
 
-    $c->forward('View::TT');
+    $c->forward('View::Web');
 
 N.B. This is usually done automatically by L<Catalyst::Action::RenderView>.
 
@@ -536,12 +554,12 @@ N.B. This is usually done automatically by L<Catalyst::Action::RenderView>.
 Renders the given template and returns output. Throws a L<Template::Exception>
 object upon error.
 
-The template variables are set to C<%$args> if $args is a hashref, or
-$C<< $c->stash >> otherwise. In either case the variables are augmented with
-C<base> set to C< << $c->req->base >>, C<c> to C<$c> and C<name> to
+The template variables are set to C<%$args> if C<$args> is a hashref, or
+C<< $c->stash >> otherwise. In either case the variables are augmented with
+C<base> set to C<< $c->req->base >>, C<c> to C<$c>, and C<name> to
 C<< $c->config->{name} >>. Alternately, the C<CATALYST_VAR> configuration item
 can be defined to specify the name of a template variable through which the
-context reference (C<$c>) can be accessed. In this case, the C<c>, C<base> and
+context reference (C<$c>) can be accessed. In this case, the C<c>, C<base>, and
 C<name> variables are omitted.
 
 C<$template> can be anything that Template::process understands how to
@@ -554,7 +572,7 @@ This can be useful for tests, for instance.
 It is possible to forward to the render method of a TT view from inside Catalyst
 to render page fragments like this:
 
-    my $fragment = $c->forward("View::TT", "render", $template_name, $c->stash->{fragment_data});
+    my $fragment = $c->forward("View::Web", "render", $template_name, $c->stash->{fragment_data});
 
 =head3 Backwards compatibility note
 
@@ -586,22 +604,47 @@ the TT configuration hash, or to set the options as below:
 
 The list of paths TT will look for templates in.
 
-=head2 C<CATALYST_VAR>
+=head2 expose_methods
 
-Allows you to change the name of the Catalyst context object. If set, it will also
-remove the base and name aliases, so you will have access them through <context>.
+The list of methods in your View class which should be made available to the templates.
 
 For example:
 
-    MyApp->config({
-        name     => 'MyApp',
-        root     => MyApp->path_to('root'),
-        'View::TT' => {
-            CATALYST_VAR => 'Catalyst',
-        },
-    });
+  expose_methods => [qw/uri_for_css/],
+
+  ...
+
+  sub uri_for_css {
+    my ($self, $c, $filename) = @_;
+
+    # additional complexity like checking file exists here
+
+    return $c->uri_for('/static/css/' . $filename);
+  }
+
+Then in the template:
+
+  [% uri_for_css('home.css') %]
+
+=head2 content_type
+
+This lets you override the default content type for the response.  If you do
+not set this and if you do not set the content type in your controllers, the
+default is C<text/html; charset=utf-8>.
+
+Use this if you are creating alternative view responses, such as text or JSON
+and want a global setting.
+
+Any content type set in your controllers before calling this view are respected
+and have priority.
 
-F<message.tt2>:
+=head2 C<CATALYST_VAR>
+
+Allows you to change the name of the Catalyst context object. If set, it will also
+remove the base and name aliases, so you will have access them through <context>.
+
+For example, if CATALYST_VAR has been set to "Catalyst", a template might
+contain:
 
     The base is [% Catalyst.req.base %]
     The name is [% Catalyst.config.name %]
@@ -640,10 +683,10 @@ Would by default look for a template in <root>/test/test. If you set TEMPLATE_EX
 
 Allows you to specify the template providers that TT will use.
 
-    MyApp->config({
+    MyApp->config(
         name     => 'MyApp',
         root     => MyApp->path_to('root'),
-        'View::TT' => {
+        'View::Web' => {
             PROVIDERS => [
                 {
                     name    => 'DBI',
@@ -657,7 +700,7 @@ Allows you to specify the template providers that TT will use.
                 }
             ]
         },
-    });
+    );
 
 The 'name' key should correspond to the class name of the provider you
 want to use.  The _file_ name is a special case that represents the default
@@ -681,15 +724,34 @@ from the general config, into the config for the provider:
 This can prove useful when you want to use the additional_template_paths hack
 in your own provider, or if you need to use Template::Provider::Encoding
 
+=head2 C<CLASS>
+
+Allows you to specify a custom class to use as the template class instead of
+L<Template>.
+
+    package MyApp::View::Web;
+    use Moose;
+    extends 'Catalyst::View::TT';
+
+    use Template::AutoFilter;
+
+    __PACKAGE__->config({
+        CLASS => 'Template::AutoFilter',
+    });
+
+This is useful if you want to use your own subclasses of L<Template>, so you
+can, for example, prevent XSS by automatically filtering all output through
+C<| html>.
+
 =head2 HELPERS
 
 The L<Catalyst::Helper::View::TT> and
 L<Catalyst::Helper::View::TTSite> helper modules are provided to create
 your view module.  There are invoked by the F<myapp_create.pl> script:
 
-    $ script/myapp_create.pl view TT TT
+    $ script/myapp_create.pl view Web TT
 
-    $ script/myapp_create.pl view TT TTSite
+    $ script/myapp_create.pl view Web TTSite
 
 The L<Catalyst::Helper::View::TT> module creates a basic TT view
 module.  The L<Catalyst::Helper::View::TTSite> module goes a little
@@ -723,6 +785,8 @@ Jesse Sheidlower, C<jester@panix.com>
 
 Andy Wardley, C<abw@cpan.org>
 
+Luke Saunders, C<luke.saunders@gmail.com>
+
 =head1 COPYRIGHT
 
 This program is free software. You can redistribute it and/or modify it