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=28a9254c7f12eb2ebc0c4f2718f03f21702a71ad;hp=91c255bd2ef8cb549bb1feadbaf6e084559c6447;hb=1edbdee6a1bad3524a3d97c6daaae02b5109c1d2;hpb=5988477160c698d0e5efd1cf1911845d40a327cf

diff --git a/lib/Catalyst/Manual/Tutorial/02_CatalystBasics.pod b/lib/Catalyst/Manual/Tutorial/02_CatalystBasics.pod
index 91c255b..28a9254 100644
--- a/lib/Catalyst/Manual/Tutorial/02_CatalystBasics.pod
+++ b/lib/Catalyst/Manual/Tutorial/02_CatalystBasics.pod
@@ -103,7 +103,8 @@ them to the necessary model and view.
 
 The use of Object-Relational Mapping (ORM) technology for database
 access. Specifically, ORM provides an automated and standardized means
-to persist and restore objects to/from a relational database.
+to persist and restore objects to/from a relational database and will
+automatically create our Catalyst model for use with a database.
 
 =back
 
@@ -132,8 +133,13 @@ script to initialize the framework for an application called C<Hello>:
     created "Hello/root"
     ...
     created "Hello/script/hello_create.pl"
+    Change to application directory and Run "perl Makefile.PL" to make sure your install is complete
     $ cd Hello
 
+Note: If you are using Strawberry Perl on Win32, drop the ".pl"
+from the end of the "catalyst.pl" command and simply use
+"catalyst Hello".
+
 The C<catalyst.pl> helper script will display the names of the
 directories and files it creates:
 
@@ -182,13 +188,20 @@ 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:
     .----------------------------------------------------------------------------.
-    | Catalyst::Plugin::ConfigLoader  0.20                                       |
-    | Catalyst::Plugin::Static::Simple  0.20                                     |
+    | Catalyst::Plugin::ConfigLoader  0.27                                       |
     '----------------------------------------------------------------------------'
     
     [debug] Loaded dispatcher "Catalyst::Dispatcher"
@@ -215,11 +228,11 @@ previous step):
     .-------------------------------------+--------------------------------------.
     | Path                                | Private                              |
     +-------------------------------------+--------------------------------------+
-    | /                                   | /default                             |
     | /                                   | /index                               |
+    | /                                   | /default                             |
     '-------------------------------------+--------------------------------------'
     
-    [info] Hello powered by Catalyst 5.80004
+    [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 
@@ -229,17 +242,19 @@ screen or an "Index" screen, you probably forgot to specify port 3000
 in your URL).  Information similar to the following should be appended 
 to the logging output of the development server:
 
-    [info] *** Request 1 (0.005/s) [20712] [Sun Mar  8 15:49:09 2009] ***
-    [debug] "GET" request for "/" from "1.1.1.98"
-    [info] Request took 0.007342s (136.203/s)
-    .----------------------------------------------------------------+-----------.
-    | Action                                                         | Time      |
-    +----------------------------------------------------------------+-----------+
-    | /index                                                         | 0.000491s |
-    | /end                                                           | 0.000595s |
-    '----------------------------------------------------------------+-----------'
+    [info] *** Request 1 (0.001/s) [23194] [Sat Jan 16 11:09:18 2010] ***
+    [debug] "GET" request for "/" from "127.0.0.1"
+    [debug] Path is "/"
+    [info] Request took 0.004851s (206.143/s)
+    .------------------------------------------------------------+-----------.
+    | Action                                                     | Time      |
+    +------------------------------------------------------------+-----------+
+    | /index                                                     | 0.000395s |
+    | /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
@@ -250,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 ) = @_;
@@ -261,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" 
@@ -269,36 +285,35 @@ 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. (Depending on your version of 
-Catalyst, it used to say "Private" but using that with 'default' or 'index' 
-is currently deprecated.)
+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 
+should also probably upgrade before continuing the tutorial.)
 
 Some MVC frameworks handle dispatching in a central place. Catalyst, 
 by policy, prefers to handle URL dispatching with attributes on 
 controller methods. There is a lot of flexibility in specifying which 
 URLs to match.  This particular method will match all URLs, because it 
 doesn't specify the path (nothing comes after "Path"), but will only 
-accept a single args because of the ":Args(0)". 
+accept a URL without any args because of the ":Args(0)". 
 
-The default is to map URLs to controller names, and because of 
-the way that Perl handles namespaces through package names, 
-it is simple to create hierarchical structures in 
-Catalyst. This means that you can create controllers with deeply 
-nested actions in a clean and logical way. 
-
-For example, the URL C<http://hello.com/admin/articles/create> maps 
-to the package C<Hello::Controller::Admin::Articles>, and the C<create>
-method. 
+The default is to map URLs to controller names, and because of the way 
+that Perl handles namespaces through package names, it is simple to 
+create hierarchical structures in Catalyst. This means that you can 
+create controllers with deeply nested actions in a clean and logical 
+way. For example, the URL C<http://hello.com/admin/articles/create> 
+maps to the package C<Hello::Controller::Admin::Articles>, and the 
+C<create> method. 
 
 Add the following subroutine to your C<lib/Hello/Controller/Root.pm> 
 file:
 
-    sub hello : Global {
+    sub hello :Global {
         my ( $self, $c ) = @_;
         
         $c->response->body("Hello, World!");
@@ -309,25 +324,52 @@ 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 
-up), and go to L<http://localhost:3000/hello> to 
-see "Hello, World!"
+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
 
-In the Catalyst world  a "View" is not a page of XHTML or a template 
-designed to present a page to a browser. It is the module that 
-determines the I<type> of view -- HTML, pdf, XML, etc. For the 
-thing that generates the I<content> of that view, (such as the 
-default Toolkit Template) the actual templates go under the 
+In the Catalyst world a "View" itself is not a page of XHTML or a 
+template designed to present a page to a browser. Rather, it is the 
+module that determines the I<type> of view -- HTML, pdf, XML, etc. For 
+the thing that generates the I<content> of that view (such as the a 
+Toolkit Template template file), the actual templates go under the 
 "root" directory.
 
 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
@@ -338,22 +380,25 @@ 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 *
 
-The final "TT" tells it that you are creating a Template Toolkit view.
+The final "TT" tells Catalyst the I<type> of the view, with "TT" 
+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 contains a
-config statement to set the TT extension to ".tt".
+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 
-able to use it to display the view templates, using the "process" 
-method that it inherits from the C<Catalyst::View::TT class>.
+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.
 
 Template Toolkit is a very full featured template facility, with 
 excellent documentation at L<http://template-toolkit.org/>, 
@@ -364,7 +409,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>
@@ -377,24 +422,53 @@ template file (C<hello.tt>).  The rest of the template is normal HTML.
 Change the hello method in C<lib/Hello/Controller/Root.pm> to the 
 following:
 
-    sub hello : Global {
+    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 setting 
-the value of the "template" hash key in the Catalyst "stash", an area 
-for putting information to share with other parts of your application. 
-The "template" key determines which template will be displayed at the 
-end of the method. Catalyst controllers have a default "end" action 
-for all methods which causes the first (or 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.
+This time, instead of doing C<$c-E<gt>response-E<gt>body()>, you are 
+setting the value of the "template" hash key in the Catalyst "stash", 
+an area for putting information to share with other parts of your 
+application. The "template" key determines which template will be 
+displayed at the end of the request cycle. Catalyst controllers have a 
+default "end" action for all methods which causes the first (or 
+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, 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.
 
-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.
+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
@@ -405,21 +479,20 @@ Create a controller named "Site" by executing the create script:
 
 This will create a C<lib/Hello/Controller/Site.pm> file (and a test 
 file). Bring Site.pm up in your editor, and you can see that there's 
-not much there. Most people probably don't bother to use the create 
-script to make controllers after they're used to using Catalyst.
+not much there. 
 
 In C<lib/Hello/Controller/Site.pm>, add the following method:
 
-    sub test : Local {
+    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 
-the C<test> action (now that we have assigned an action type to the 
-method it appears as a controller "action" to Catalyst) to be executed 
+the C<test> action (now that we have assigned an "action type" to the 
+method it appears as a "controller action" to Catalyst) to be executed 
 on the "controller/method" URL, or, in this case, "site/test".  We 
 will see additional information on controller actions throughout the 
 rest of the tutorial, but if you are curious take a look at 
@@ -441,13 +514,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