X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FTutorial%2FCatalystBasics.pod;h=73d265b2be4849e950c17b2dd1152dd75f2ca11f;hb=9183745a1266d667b117db56915c25ce4d78ae78;hp=7096679d5957c06440cf3bf5a6af81def9a07a43;hpb=c9b77c06a0de97f1d6e9a66091e693a637578357;p=catagits%2FCatalyst-Runtime.git

diff --git a/lib/Catalyst/Manual/Tutorial/CatalystBasics.pod b/lib/Catalyst/Manual/Tutorial/CatalystBasics.pod
index 7096679..73d265b 100644
--- a/lib/Catalyst/Manual/Tutorial/CatalystBasics.pod
+++ b/lib/Catalyst/Manual/Tutorial/CatalystBasics.pod
@@ -114,7 +114,10 @@ following command:
 
 Catalyst provides a number of helper scripts that can be used to quickly
 flesh out the basic structure of your application. All Catalyst projects
-begin with the C<catalyst.pl> helper.
+begin with the C<catalyst.pl> helper (see L<Catalyst::Helper|Catalyst::Helper>
+for more information on helpers).  Also note that as of Catalyst 5.7000,
+you will not have the helper scripts unless you install both 
+L<Catalyst::Runtime|Catalyst::Runtime> and L<Catalyst::Devel|Catalyst::Devel>.
 
 In the case of this tutorial, use the Catalyst C<catalyst.pl> script to
 initialize the framework for an application called C<MyApp>:
@@ -693,7 +696,8 @@ to the controller:
         $c->stash->{books} = [$c->model('MyAppDB::Book')->all];
         
         # Set the TT template to use.  You will almost always want to do this
-        # in your action methods.
+        # in your action methods (actions methods respond to user input in
+        # your controllers).
         $c->stash->{template} = 'books/list.tt2';
     }
 
@@ -728,7 +732,7 @@ include Mason (L<http://www.masonhq.com> and
 L<http://www.masonbook.com>) and L<HTML::Template|HTML::Template>
 (L<http://html-template.sourceforge.net>).
 
-=head2 Create a Catalyst View Using C<TTSITE>
+=head2 Create a Catalyst View Using C<TTSite>
 
 When using TT for the Catalyst view, there are two main helper scripts:
 
@@ -788,7 +792,7 @@ Catalyst C<c> variable.)
 B<TIP>: When troubleshooting TT it can be helpful to enable variable
 C<DEBUG> options.  You can do this in a Catalyst environment by adding
 a C<DEBUG> line to the C<__PACKAGE__->config> declaration in 
-C<MyApp/View/TT.pm>:
+C<lib/MyApp/View/TT.pm>:
 
     __PACKAGE__->config({
         CATALYST_VAR => 'Catalyst',
@@ -803,6 +807,12 @@ L<Template::Constants> for more information (remove the C<DEBUG_>
 portion of the name shown in the TT docs and convert to lower case
 for use inside Catalyst).
 
+B<NOTE:> Please be sure to disable TT debug options before 
+continuing the tutorial (especially the 'undef' option -- leaving
+this enabled will conflict with several of the conventions used
+by this tutorial and TTSite to leave some variables undefined
+on purpose).
+
 
 =head2 Using C<RenderView> for the Default View
 
@@ -872,9 +882,10 @@ Older Catalyst-related documents often suggest that you add a "private
 end action" to your application class (C<MyApp.pm>) or Root.pm 
 (C<MyApp/Controller/Root.pm>).  These examples should be easily 
 converted to L<RenderView|Catalyst::Action::RenderView> by simply adding 
-C<ActionClass('RenderView')> to the C<sub end> definition. If end sub is 
-defined in your application class (C<MyApp.pm>), you should also migrate 
-it to C<MyApp/Controller/Root.pm>.
+the attribute C<:ActionClass('RenderView')> to the C<sub end> 
+definition. If end sub is defined in your application class 
+(C<MyApp.pm>), you should also migrate it to 
+C<MyApp/Controller/Root.pm>.
 
 =item *
 
@@ -1128,6 +1139,66 @@ You should see 5 such lines of debug output as DBIC fetches the author
 information for each book.
 
 
+=head1 USING THE DEFAULT TEMPLATE NAME
+
+By default, C<Catalyst::View::TT> will look for a template that uses the 
+same name as your controller action, allowing you to save the step of 
+manually specifying the template name in each action.  For example, this 
+would allow us to remove (or comment out) the 
+C<$c-E<gt>stash-E<gt>{template} = 'books/list.tt2';> line of our 
+C<list> action in the Books controller.  Open 
+C<lib/MyApp/Controller/Books.pm> in your editor and update it to 
+match the following:
+
+    =head2 list
+    
+    Fetch all book objects and pass to books/list.tt2 in stash to be displayed
+    
+    =cut
+    
+    sub list : Local {
+        # Retrieve the usual perl OO '$self' for this object. $c is the Catalyst
+        # 'Context' that's used to 'glue together' the various components
+        # that make up the application
+        my ($self, $c) = @_;
+    
+        # Retrieve all of the book records as book model objects and store in the
+        # stash where they can be accessed by the TT template
+        $c->stash->{books} = [$c->model('MyAppDB::Book')->all];
+    
+        # Automatically look for a template of 'books/list.tt2' template
+        # (if TEMPLATE_EXTENSION is set to '.tt2')
+    }
+
+C<Catalyst::View::TT> defaults to looking for a template with no 
+extension.  In our case, we need to override this to look for an 
+extension of C<.tt2>.  Open C<lib/MyApp/View/TT.pm> and add the 
+C<TEMPLATE_EXTENSION> definition as follows:
+
+    __PACKAGE__->config({
+        CATALYST_VAR => 'Catalyst',
+        INCLUDE_PATH => [
+            MyApp->path_to( 'root', 'src' ),
+            MyApp->path_to( 'root', 'lib' )
+        ],
+        PRE_PROCESS  => 'config/main',
+        WRAPPER      => 'site/wrapper',
+        ERROR        => 'error.tt2',
+        TIMER        => 0,
+        TEMPLATE_EXTENSION => '.tt2',
+    });
+
+You should now be able to restart the development server as per the 
+previous section and access the L<http://localhost:3000/books/list>
+as before.
+
+Although this can be a valuable technique to establish a default 
+template for each of your actions, the remainder of the tutorial
+will manually assign the template name to 
+C<$c-E<gt>stash-E<gt>{template}> in each action in order to make 
+the logic as conspicuous as possible.
+
+
 =head1 AUTHOR
 
 Kennedy Clark, C<hkclark@gmail.com>