[Catalyst-commits] r11697 - in Catalyst-View-TD/trunk/lib/Catalyst: Helper/View View

theory at dev.catalyst.perl.org theory at dev.catalyst.perl.org
Fri Oct 30 18:03:15 GMT 2009


Author: theory
Date: 2009-10-30 18:03:14 +0000 (Fri, 30 Oct 2009)
New Revision: 11697

Modified:
   Catalyst-View-TD/trunk/lib/Catalyst/Helper/View/TD.pm
   Catalyst-View-TD/trunk/lib/Catalyst/View/TD.pm
Log:
Updated docs for the new helper.

Modified: Catalyst-View-TD/trunk/lib/Catalyst/Helper/View/TD.pm
===================================================================
--- Catalyst-View-TD/trunk/lib/Catalyst/Helper/View/TD.pm	2009-10-30 17:41:59 UTC (rev 11696)
+++ Catalyst-View-TD/trunk/lib/Catalyst/Helper/View/TD.pm	2009-10-30 18:03:14 UTC (rev 11697)
@@ -71,7 +71,6 @@
 
 use strict;
 use warnings;
-
 use parent 'Catalyst::View::TD';
 
 # Unless auto_alias is false, Catalyst::View::TD will automatically load all

Modified: Catalyst-View-TD/trunk/lib/Catalyst/View/TD.pm
===================================================================
--- Catalyst-View-TD/trunk/lib/Catalyst/View/TD.pm	2009-10-30 17:41:59 UTC (rev 11696)
+++ Catalyst-View-TD/trunk/lib/Catalyst/View/TD.pm	2009-10-30 18:03:14 UTC (rev 11697)
@@ -19,7 +19,7 @@
 
 Use the helper to create your view:
 
-    myapp_create.pl view HTML TD
+    ./script/myapp_create.pl view HTML TD
 
 Configure in F<lib/MyApp.pm> (could be set from config file instead):
 
@@ -34,14 +34,8 @@
         },
     );
 
-Create a template in F<lib/MyApp/TD/HTML.pm>:
+Create a template by editing F<lib/MyApp/TD/HTML.pm>:
 
-    package TestApp::TD::HTML;
-
-    use strict;
-    use warnings;
-    use Template::Declare::Tags;
-
     template hello => sub {
         my ($self, $vars) = @_;
         html {
@@ -210,26 +204,47 @@
 =head1 Description
 
 This is the Catalyst view class for L<Template::Declare|Template::Declare>.
-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.
+Your application should define a view class that subclasses 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.
 
-    $ script/myapp_create.pl view HTML TD
+    ./script/myapp_create.pl view HTML TD
 
 This creates a C<MyApp::View::HTML> module in the F<lib> directory (again,
-replacing C<MyApp> with the name of your application) which looks something
+replacing C<MyApp> with the name of your application) that looks something
 like this:
 
     package MyApp::View::HTML;
 
     use strict;
     use warnings;
+    use parent 'Catalyst::View::TD';
 
-    use base 'Catalyst::View::TD';
+    __PACKAGE__->config(
+        # dispatch_to     => [qw(MyApp::TD::HTML)],
+        # auto_alias      => 1,
+        # postprocessor   => sub { ... },
+        # around_template => sub { ... },
+    );
 
-    __PACKAGE__->config->{DEBUG} = 'all';
+It also creates a C<MyApp::TD::HTML> template class that looks something like
+this:
 
+    package MyApp::TD::HTML;
+
+    use strict;
+    use warnings;
+    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
 C<end()> method, for example, to automatically forward all actions to the TD
@@ -251,7 +266,7 @@
     package MyApp::View::HTML;
 
     use strict;
-    use base 'Catalyst::View::TD';
+    use parent 'Catalyst::View::TD';
 
     MyApp::View::TD->config({
         dispatch_to     => [ 'MyApp::TD::HTML' ],
@@ -298,44 +313,9 @@
         },
     });
 
-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.
+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.
 
-=head2 Dynamic C<dispatch_to>
-
-Sometimes it is desirable to modify C<dispatch_to> for your templates at
-runtime. Additional paths can be prepended or appended C<dispatch_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 add template classes paths to the end of C<dispatch_to>, there
-is also a C<include_path()> accessor:
-
-    my $view = $c->view('HTML')
-    push @{ $view->dispatch_to }, 'My::Templates'
-        unless grep { $_ eq 'My::Templates' } $view->dispatch_to;
-
-Note that if you use C<dispatch_to()> to add extra template classes, they are
-I<permanently> added. You therefore B<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 C<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 C<render> directly, then you can specify extra template
-classes under the C<prepend_template_classes> and C<append_template_classes>
-keys. See L</"Capturing Template Output"> for an example.
-
 =head2 Auto-Aliasing
 
 In addition to the dispatch template class (as defined in the C<dispatch_to>
@@ -464,6 +444,41 @@
 This would be the way to go if you wanted finer control over
 Template::Declare's L<composition features|Template::Declare/"Template Composition">.
 
+=head2 Dynamic C<dispatch_to>
+
+Sometimes it is desirable to modify C<dispatch_to> for your templates at
+runtime. Additional paths can be prepended or appended C<dispatch_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 add template classes paths to the end of C<dispatch_to>, there
+is also a C<dispatch_to()> accessor:
+
+    my $view = $c->view('HTML')
+    push @{ $view->dispatch_to }, 'My::Templates'
+        unless grep { $_ eq 'My::Templates' } $view->dispatch_to;
+
+Note that if you use C<dispatch_to()> to add extra template classes, they are
+I<permanently> added. You therefore B<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 C<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 C<render> directly, then you can specify extra template
+classes under the C<prepend_template_classes> and C<append_template_classes>
+keys. See L</"Capturing Template Output"> for an example.
+
 =head2 Rendering Views
 
 The Catalyst C<view()> method renders the template specified in the C<template>
@@ -532,8 +547,8 @@
     template message => sub {
         my ($self, $args) = @_;
         p { "The message is $args->{message}" };
-        p { "The base is " . $self->base };
-        p { "The name is " . $self->name };
+        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<< $c->response->body >>.
@@ -560,6 +575,27 @@
         # Redirect or display a message
     }
 
+=head2 Template Class Helper
+
+In addition to the usual helper for creating TD views, you can also use the
+C<TDClass> helper to create new template classes:
+
+    ./script/myapp_create.pl TDClass HTML::Users
+
+This will create a new Template::Declare template class,
+C<MyApp::TD::HTML::Users> in the F<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 L</"Auto-Aliasing">, if you already have the TD view
+C<MyApp::View::HTML>, the templates in the C<MyApp::TD::HTML::Users> class
+will be aliased under the C</users> path. So if you defined a C<list> action
+in the C<Users> controller and a corresponding C<list> view in the
+C<HTML::Users> view, both would resolve to C</users/list>.
+
 =head2 Methods
 
 =head3 C<new>




More information about the Catalyst-commits mailing list