X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FTutorial%2F02_CatalystBasics.pod;h=8a295a402ef04cbd0df0d4111e799a3d2ae899b9;hp=3404ca2ee0aab6098e771bc1d4672a5142f73034;hb=d09971d0950d09ed4b766ecbbc1c2c1624a8fd33;hpb=3dfcf16a80948793046ece8b2bde7f5272d5a7bb

diff --git a/lib/Catalyst/Manual/Tutorial/02_CatalystBasics.pod b/lib/Catalyst/Manual/Tutorial/02_CatalystBasics.pod
index 3404ca2..8a295a4 100644
--- a/lib/Catalyst/Manual/Tutorial/02_CatalystBasics.pod
+++ b/lib/Catalyst/Manual/Tutorial/02_CatalystBasics.pod
@@ -188,7 +188,15 @@ Run the following command to start up the built-in development web
 server (make sure you didn't forget the "C<cd Hello>" from the 
 previous step):
 
-    $ script/hello_server.pl
+B<Note>: The "-r" argument enables reloading on code changes so you 
+don't have to stop and start the server when you update code. See 
+C<perldoc script/hello_server.pl> or C<script/hello_server.pl --help>
+for additional options you might find helpful. Most of the rest of the
+tutorial will assume that you are using "-r" when you start the development
+server, but feel free to manually start and stop it (use C<Ctrl-C> to
+breakout of the dev server) if you prefer. 
+
+    $ script/hello_server.pl -r
     [debug] Debug messages enabled
     [debug] Statistics enabled
     [debug] Loaded plugins:
@@ -224,7 +232,7 @@ previous step):
     | /                                   | /default                             |
     '-------------------------------------+--------------------------------------'
     
-    [info] Hello powered by Catalyst 5.80018
+    [info] Hello powered by Catalyst 5.80020
     You can connect to your server at http://debian:3000
 
 Point your web browser to L<http://localhost:3000> (substituting a 
@@ -245,7 +253,8 @@ to the logging output of the development server:
     | /end                                                       | 0.000425s |
     '------------------------------------------------------------+-----------'
 
-Press Ctrl-C to break out of the development server.
+B<Note>: Press C<Ctrl-C> to break out of the development server if 
+necessary.
 
 
 =head1 HELLO WORLD
@@ -256,9 +265,7 @@ The Root.pm controller is a place to put global actions that usually
 execute on the root URL. Open the C<lib/Hello/Controller/Root.pm> file in 
 your editor. You will see the "index" subroutine, which is 
 responsible for displaying the welcome screen that you just saw in 
-your browser. Later on you'll want to change that to something more 
-reasonable, such as a "404" message or a redirect, but for now just 
-leave it alone.
+your browser. 
 
     sub index :Path :Args(0) {
         my ( $self, $c ) = @_;
@@ -267,6 +274,9 @@ leave it alone.
         $c->response->body( $c->welcome_message );
     }
 
+Later on you'll want to change that to something more reasonable, such 
+as a "404" message or a redirect, but for now just leave it alone. 
+
 The "C<$c>" here refers to the Catalyst context, which is used to 
 access the Catalyst application. In addition to many other things, 
 the Catalyst context provides access to "response" and "request" 
@@ -275,14 +285,14 @@ L<Catalyst::Response|Catalyst::Response>, and
 L<Catalyst::Request|Catalyst::Request>) 
 
 C<$c-E<gt>response-E<gt>body> sets the HTTP response (see 
-L<Catalyst::Response|Catalyst::Response>), while C<$c-E<gt>welcome_message> 
-is a special method that returns the welcome message that you saw in 
-your browser.
+L<Catalyst::Response|Catalyst::Response>), while 
+C<$c-E<gt>welcome_message> is a special method that returns the 
+welcome message that you saw in your browser.
 
 The ":Path :Args(0)" after the method name are attributes which 
 determine which URLs will be dispatched to this method. (You might see 
 ":Private" if you are using an older version of Catalyst, but using 
-that with 'default' or 'index' is currently deprecated.  If so, you 
+that with "default" or "index" is currently deprecated.  If so, you 
 should also probably upgrade before continuing the tutorial.)
 
 Some MVC frameworks handle dispatching in a central place. Catalyst, 
@@ -309,15 +319,45 @@ file:
         $c->response->body("Hello, World!");
     }
 
+Once you restart the server, you will need to use the new address
+L<http://localhost:3000/hello> instead of L<http://localhost:3000/> to see the
+changes.
+
 B<TIP>: See Appendix 1 for tips on removing the leading spaces when
 cutting and pasting example code from POD-based documents.
 
 Here you're sending your own string to the webpage.
 
-Save the file, start the server (stop and restart it if it's still 
-running), and go to L<http://localhost:3000/hello> to 
-see "Hello, World!"  Also notice that a new action is listed under
-"Loaded Private actions" in the development server debug output.
+Save the file, and you should notice the following in your server output:
+
+    Saw changes to the following files:
+     - /home/me/Hello/lib/Hello/Controller/Root.pm (modify)
+    
+    Attempting to restart the server
+    ...
+    [debug] Loaded Private actions:
+    .----------------------+--------------------------------------+--------------.
+    | Private              | Class                                | Method       |
+    +----------------------+--------------------------------------+--------------+
+    | /default             | Hello::Controller::Root              | default      |
+    | /end                 | Hello::Controller::Root              | end          |
+    | /index               | Hello::Controller::Root              | index        |
+    | /hello               | Hello::Controller::Root              | hello        |
+    '----------------------+--------------------------------------+--------------'
+    
+    [debug] Loaded Path actions:
+    .-------------------------------------+--------------------------------------.
+    | Path                                | Private                              |
+    +-------------------------------------+--------------------------------------+
+    | /                                   | /index                               |
+    | /                                   | /default                             |
+    | /hello                              | /hello                               |
+    '-------------------------------------+--------------------------------------'
+    ...
+
+Go to L<http://localhost:3000/hello> to see "Hello, World!".   Also 
+notice that the newly defined 'hello' action is listed under "Loaded 
+Private actions" in the development server debug output.
 
 
 =head2 Hello, World! Using a View and a Template
@@ -331,9 +371,9 @@ Toolkit Template template file), the actual templates go under the
 
 To create a TT view, run:
 
-    $ script/hello_create.pl view TT TT
+    $ script/hello_create.pl view HTML TT
 
-This creates the C<lib/Hello/View/TT.pm> module, which is a subclass of 
+This creates the C<lib/Hello/View/HTML.pm> module, which is a subclass of 
 C<Catalyst::View::TT>. 
 
 =over 4
@@ -344,9 +384,11 @@ The "view" keyword tells the create script that you are creating a view.
 
 =item *
 
-The first "TT" tells the script to name the View module "TT.pm", which is a
-commonly used name for TT views.  (You can name it anything you want, such as
-"HTML.pm".)
+The first argument "HTML" tells the script to name the View module "HTML.pm",
+which is a commonly used name for TT views.  You can name it anything you want,
+such as "MyView.pm". If you have more than one view, be sure to set the
+default_view in Hello.pm (See L<Catalyst::View::TT|Catalyst::View::TT> for more
+details on setting this).
 
 =item *
 
@@ -355,12 +397,12 @@ indicating that you want to a Template Toolkit view.
 
 =back
 
-If you look at C<lib/Hello/View/TT.pm> you will find that it only 
+If you look at C<lib/Hello/View/HTML.pm> you will find that it only 
 contains a config statement to set the TT extension to ".tt".
 
-Now that the TT.pm "View" exists, Catalyst will autodiscover it and be 
+Now that the HTML.pm "View" exists, Catalyst will autodiscover it and be 
 able to use it to display the view templates using the "process" 
-method that it inherits from the C<Catalyst::View::TT class>.
+method that it inherits from the C<Catalyst::View::TT> class.
 
 Template Toolkit is a very full featured template facility, with 
 excellent documentation at L<http://template-toolkit.org/>, 
@@ -371,7 +413,7 @@ chapters of the tutorial).
 Create a C<root/hello.tt> template file (put it in the C<root> under 
 the C<Hello> directory that is the base of your application). Here is 
 a simple sample:
-  
+
     <p>
         This is a TT view template, called '[% template.name %]'.
     </p>
@@ -387,7 +429,7 @@ following:
     sub hello :Global {
         my ( $self, $c ) = @_;
         
-        $c->stash->{template} = 'hello.tt';
+        $c->stash(template => 'hello.tt');
     }
 
 This time, instead of doing C<$c-E<gt>response-E<gt>body()>, you are 
@@ -400,9 +442,37 @@ default) view to be rendered (unless there's a C<$c-E<gt>response-
 E<gt>body()> statement). So your template will be magically displayed 
 at the end of your method.
 
-After saving the file, restart the development server, and look at 
-L<http://localhost:3000/hello> again. You should 
-see the template that you just made.
+After saving the file, the development server should automatically
+restart (again, the tutorial is written to assume that you are
+using the "-r" option -- manually restart it if you aren't), 
+and look at L<http://localhost:3000/hello> in your again. You 
+should see the template that you just made.
+
+B<TIP:> If you keep the server running with "-r" in a "background 
+window," don't let that window get totally hidden... if you have an 
+syntax error in your code, the debug server output will contain the 
+error information.
+
+B<Note:> You will probably run into a variation of the "stash"
+statement above that looks like:
+
+    $c->stash->{template} = 'hello.tt';
+
+Although this style is still relatively common, the approach we
+used previous is becoming more common because it allows you to
+set multiple stash variables in one line.  For example:
+
+    $c->stash(template => 'hello.tt', foo => 'bar', 
+              another_thing => 1);
+
+You can also set multiple stash values with a hashref:
+
+    $c->stash({template => 'hello.tt', foo => 'bar', 
+              another_thing => 1});
+
+Any of these formats work, but the C<$c-E<gt>stash(name =E<gt> value);>
+style is growing in popularity -- you may wish to use it all the 
+time (even when you are only setting a single value).
 
 
 =head1 CREATE A SIMPLE CONTROLLER AND AN ACTION
@@ -420,8 +490,8 @@ In C<lib/Hello/Controller/Site.pm>, add the following method:
     sub test :Local {
         my ( $self, $c ) = @_;
     
-        $c->stash->{username} = "John";
-        $c->stash->{template} = 'site/test.tt';
+        $c->stash(username => 'John',
+                  template => 'site/test.tt');
     }
 
 Notice the "Local" attribute on the C<test> method. This will cause 
@@ -448,13 +518,13 @@ template file at that location. Include a line like:
 
     <p>Hello, [% username %]!</p>
 
-Bring up or restart the server.  Notice in the server output that 
-C</site/test> is listed in the Loaded Path actions. Go to 
-L<http://localhost:3000/site/test> in your browser.
-
 You should see your test.tt file displayed, including the name "John"
 that you set in the controller.
 
+Once the server automatically restarts, notice in the server 
+output that C</site/test> is listed in the Loaded Path actions. 
+Go to L<http://localhost:3000/site/test> in your browser.
+
 
 =head1 AUTHORS
 
@@ -465,5 +535,5 @@ Please report any errors, issues or suggestions to the author.  The
 most recent version of the Catalyst Tutorial can be found at
 L<http://dev.catalyst.perl.org/repos/Catalyst/Catalyst-Manual/5.80/trunk/lib/Catalyst/Manual/Tutorial/>.
 
-Copyright 2006-2008, Kennedy Clark & Gerda Shank, under Creative Commons License
+Copyright 2006-2010, Kennedy Clark, under Creative Commons License
 (L<http://creativecommons.org/licenses/by-sa/3.0/us/>).