X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FTutorial%2F03_MoreCatalystBasics.pod;h=2c2ea7a757b8e06daf6fc04a51a5e3bdc25fd38e;hp=d8ba67c10978e9e784302b547ab9aff3b937b3ee;hb=a1de5b6537e37154353b246b66def4f0264b731f;hpb=c988c8b093c26a7205881bfd4eb6f0bf9a5834dd

diff --git a/lib/Catalyst/Manual/Tutorial/03_MoreCatalystBasics.pod b/lib/Catalyst/Manual/Tutorial/03_MoreCatalystBasics.pod
index d8ba67c..2c2ea7a 100644
--- a/lib/Catalyst/Manual/Tutorial/03_MoreCatalystBasics.pod
+++ b/lib/Catalyst/Manual/Tutorial/03_MoreCatalystBasics.pod
@@ -64,16 +64,19 @@ will be too limited to be of use to anyone, it should provide a basic
 environment where we can explore a variety of features used in virtually
 all web applications.
 
-You can check out the source code for this example from the Catalyst
-Subversion repository as per the instructions in
+Source code for the tutorial in included in the F</home/catalyst/Final>
+directory of the Tutorial Virtual machine (one subdirectory per
+chapter).  There are also instructions for downloading the code in
 L<Catalyst::Manual::Tutorial::01_Intro>.
 
 Please take a look at
-L<Catalyst::Manual::Tutorial::01_Intro/CATALYST INSTALLATION> before
-doing the rest of this tutorial.  Although the tutorial should work
-correctly under most any recent version of Perl running on any operating
-system, the tutorial has been written using Debian 6 and tested to be
-sure it runs correctly in this environment.
+L<Catalyst::Manual::Tutorial::01_Intro/STARTING WITH THE TUTORIAL VIRTUAL MACHINE>
+before doing the rest of this tutorial.  Although the tutorial should
+work correctly under most any recent version of Perl running on any
+operating system, the tutorial has been written using the virtual
+machine that is available for download.  The entire tutorial has been
+tested to be sure it runs correctly in this environment, so it is
+the most trouble-free way to get started with Catalyst.
 
 
 =head1 CREATE A NEW APPLICATION
@@ -106,7 +109,7 @@ if you are using Strawberry Perl.)
 =head1 EDIT THE LIST OF CATALYST PLUGINS
 
 One of the greatest benefits of Catalyst is that it has such a large
-library of bases classes and plugins available that you can use easily
+library of base classes and plugins available that you can use to easily
 add functionality to your application. Plugins are used to seamlessly
 integrate existing Perl modules into the overall Catalyst framework. In
 general, they do this by adding additional methods to the C<context>
@@ -140,16 +143,16 @@ If you prefer, there are several other ways to enable debug output:
 
 =item *
 
-Use the C<$c-E<gt>debug> method on the C<$c> Catalyst context object
+the C<$c-E<gt>debug> method on the C<$c> Catalyst context object
 
 =item *
 
-The C<-d> option to C<script/myapp_server.pl>
+the C<-d> option on the C<script/myapp_server.pl> script
 
 =item *
 
-The C<CATALYST_DEBUG=1> environment variable (or use C<CATALYST_DEBUG=0>
-to temporarily disable debug output).
+the C<CATALYST_DEBUG=1> environment variable (or C<CATALYST_DEBUG=0>
+to temporarily disable debug output)
 
 =back
 
@@ -203,7 +206,7 @@ images and CSS files, from the development server.
 
 =back
 
-For our application, we want to add one new plugin into the mix.  To do
+For our application, we want to add one new plugin to the mix.  To do
 this, edit C<lib/MyApp.pm> (this file is generally referred to as your
 I<application class>) and delete the lines with:
 
@@ -234,9 +237,9 @@ Don't let these variations confuse you -- they all accomplish the same
 result.
 
 This tells Catalyst to start using one additional plugin,
-L<Catalyst::Plugin::StackTrace>, to add a stack trace to the standard
-Catalyst "debug screen" (the screen Catalyst sends to your browser when
-an error occurs). Be aware that
+L<Catalyst::Plugin::StackTrace>, to add a stack trace near the top of
+the standard Catalyst "debug screen" (the screen Catalyst sends to your
+browser when an error occurs). Be aware that
 L<StackTrace|Catalyst::Plugin::StackTrace> output appears in your
 browser, not in the console window from which you're running your
 application, which is where logging output usually goes.
@@ -296,15 +299,15 @@ Use the Catalyst C<create> script to add a controller for book-related
 actions:
 
     $ script/myapp_create.pl controller Books
-     exists "/home/me/MyApp/script/../lib/MyApp/Controller"
-     exists "/home/me/MyApp/script/../t"
-    created "/home/me/MyApp/script/../lib/MyApp/Controller/Books.pm"
-    created "/home/me/MyApp/script/../t/controller_Books.t"
+     exists "/home/catalyst/MyApp/script/../lib/MyApp/Controller"
+     exists "/home/catalyst/MyApp/script/../t"
+    created "/home/catalyst/MyApp/script/../lib/MyApp/Controller/Books.pm"
+    created "/home/catalyst/MyApp/script/../t/controller_Books.t"
 
 Then edit C<lib/MyApp/Controller/Books.pm> (as discussed in
 L<Chapter 2|Catalyst::Manual::Tutorial::02_CatalystBasics> of
 the Tutorial, Catalyst has a separate directory under C<lib/MyApp> for
-each of the three parts of MVC: C<Model>, C<View>, and C<Controller>)
+each of the three parts of MVC: C<Model>, C<View> and C<Controller>)
 and add the following method to the controller:
 
     =head2 list
@@ -458,10 +461,10 @@ For our book application, enter the following command to enable the
 C<TT> style of view rendering:
 
     $ script/myapp_create.pl view HTML TT
-     exists "/home/me/MyApp/script/../lib/MyApp/View"
-     exists "/home/me/MyApp/script/../t"
-     created "/home/me/MyApp/script/../lib/MyApp/View/HTML.pm"
-     created "/home/me/MyApp/script/../t/view_HTML.t"
+     exists "/home/catalyst/MyApp/script/../lib/MyApp/View"
+     exists "/home/catalyst/MyApp/script/../t"
+     created "/home/catalyst/MyApp/script/../lib/MyApp/View/HTML.pm"
+     created "/home/catalyst/MyApp/script/../t/view_HTML.t"
 
 This creates a view called C<HTML> (the first argument) in a file called
 C<HTML.pm> that uses L<Catalyst::View::TT> (the second argument) as the
@@ -505,12 +508,15 @@ could be different depending on the version of Catalyst you are using):
     );
 
 
-Change this to match the following:
+Change this to match the following (insert a new
+C<__PACKAGE__-E<gt>config> below the existing statement):
 
     __PACKAGE__->config(
         name => 'MyApp',
         # Disable deprecated behavior needed by old applications
         disable_component_resolution_regex_fallback => 1,
+    );
+    __PACKAGE__->config(
         # Configure the view
         'View::HTML' => {
             #Set the location for TT files
@@ -525,7 +531,7 @@ C<root/src>.
 
 Please stick with the settings above for the duration of the tutorial,
 but feel free to use whatever options you desire in your applications
-(as with most things Perl, there's more than one way to do it...).
+(as with most things in Perl, there's more than one way to do it...).
 
 B<Note:> We will use C<root/src> as the base directory for our template
 files, with a full naming convention of
@@ -576,7 +582,7 @@ looping, conditional logic, etc.  In general, TT simplifies the usual
 range of Perl operators down to the single dot (".") operator.  This
 applies to operations as diverse as method calls, hash lookups, and list
 index values (see L<Template::Manual::Variables> for details and
-examples).  In addition to the usual L<Template> module Pod
+examples).  In addition to the usual L<Template::Toolkit> module Pod
 documentation, you can access the TT manual at
 L<https://metacpan.org/module/Template::Manual>.
 
@@ -739,44 +745,16 @@ technique that we see in
 L<Chapter 4|Catalyst::Manual::Tutorial::04_BasicCRUD>).
 
 
-=head2 Make Sure You Have a Recent Version of the DBIx::Class Model
+=head2 Create Static DBIx::Class Schema Files
 
-First, let's be sure we have a recent version of the DBIC helper,
-L<Catalyst::Model::DBIC::Schema>, so that we can take advantage of some
-recent enhancements in how foreign keys are handled with SQLite.  To
-check your version, run this command:
+B<Note:> If you are not following along in the Tutorial Virtual Machine,
+please be sure that you have version 1.27 or higher of DBD::SQLite and
+version 0.39 or higher of Catalyst::Model::DBIC::Schema.  (The Tutorial
+VM already has versions that are known to work.)  You can get your
+currently installed version numbers with the following commands.
 
     $ perl -MCatalyst::Model::DBIC::Schema\ 999
-    Catalyst::Model::DBIC::Schema version 999 required--this is only version 0.41.
-    BEGIN failed--compilation aborted.
-
-The part we are after is the "version 0.41" at the end of the second
-line.  If you are following along in Debian 6, you should have version
-0.41 or higher. If you have less than v0.39, you will need to run this
-command to install it directly from CPAN:
-
-    $ cpan -i Catalyst::Model::DBIC::Schema
-
-And re-run the version print command to verify that you are now at 0.39
-or higher.
-
-In addition, since we are using SQLite's foreign key support here,
-please be sure that you use version C<1.27> of L<DBD::SQLite> or later:
-
     $ perl -MDBD::SQLite\ 999
-    DBD::SQLite version 999 required--this is only version 1.29.
-    BEGIN failed--compilation aborted.
-
-Upgrade if you are not at version C<1.27> or higher.
-
-Open C<Makefile.PL> and add the following lines to require these versions
-going forward:
-
-    requires 'Catalyst::Model::DBIC::Schema' => '0.39';
-    requires 'DBD::SQLite' => '1.27';
-
-
-=head2 Create Static DBIx::Class Schema Files
 
 Before you continue, make sure your C<myapp.db> database file is in the
 application's topmost directory. Now use the model helper with the
@@ -787,12 +765,12 @@ automatically build the required files for us:
     $ script/myapp_create.pl model DB DBIC::Schema MyApp::Schema \
         create=static dbi:SQLite:myapp.db \
         on_connect_do="PRAGMA foreign_keys = ON"
-     exists "/home/me/MyApp/script/../lib/MyApp/Model"
-     exists "/home/me/MyApp/script/../t"
-    Dumping manual schema for MyApp::Schema to directory /home/me/MyApp/script/../lib ...
+     exists "/home/catalyst/MyApp/script/../lib/MyApp/Model"
+     exists "/home/catalyst/MyApp/script/../t"
+    Dumping manual schema for MyApp::Schema to directory /home/catalyst/MyApp/script/../lib ...
     Schema dump completed.
-    created "/home/me/MyApp/script/../lib/MyApp/Model/DB.pm"
-    created "/home/me/MyApp/script/../t/model_DB.t"
+    created "/home/catalyst/MyApp/script/../lib/MyApp/Model/DB.pm"
+    created "/home/catalyst/MyApp/script/../t/model_DB.t"
 
 Please note the '\' above.  Depending on your environment, you might be
 able to cut and paste the text as shown or need to remove the '\'
@@ -840,9 +818,9 @@ at C<lib/MyApp/Model/DB.pm>, you will see that the SQLite pragma is
 propagated to the Model, so that SQLite's recent (and optional) foreign
 key enforcement is enabled at the start of every database connection.
 
-
 =back
 
+
 If you look in the C<lib/MyApp/Schema.pm> file, you will find that it
 only contains a call to the C<load_namespaces> method.  You will also
 find that C<lib/MyApp> contains a C<Schema> subdirectory, which then has
@@ -877,8 +855,8 @@ when you launch the application).
 Additionally, the C<lib/MyApp/Schema.pm> model can easily be loaded
 outside of Catalyst, for example, in command-line utilities and/or cron
 jobs. C<lib/MyApp/Model/DB.pm> provides a very thin "bridge" between
-Catalyst this external database model.  Once you see how we can add some
-powerful features to our DBIC model in
+Catalyst and this external database model.  Once you see how we can
+add some powerful features to our DBIC model in
 L<Chapter 4|Catalyst::Manual::Tutorial::04_BasicCRUD>, the elegance
 of this approach will start to become more obvious.
 
@@ -903,9 +881,9 @@ L<DBIx::Class::Schema::Loader> version C<0.05000> or later.
 =head1 ENABLE THE MODEL IN THE CONTROLLER
 
 Open C<lib/MyApp/Controller/Books.pm> and un-comment the model code we
-left disabled earlier so that your version matches the following (un-
-comment the line containing C<[$c-E<gt>model('DB::Book')-E<gt>all]> and
-delete the next 2 lines):
+left disabled earlier so that your version matches the following
+(un-comment the line containing C<[$c-E<gt>model('DB::Book')-E<gt>all]>
+and delete the next 2 lines):
 
     =head2 list
     
@@ -978,14 +956,14 @@ display something like:
     [debug] Statistics enabled
     [debug] Loaded plugins:
     .----------------------------------------------------------------------------.
-    | Catalyst::Plugin::ConfigLoader  0.27                                       |
+    | Catalyst::Plugin::ConfigLoader  0.30                                       |
     | Catalyst::Plugin::StackTrace  0.11                                         |
     '----------------------------------------------------------------------------'
     
     [debug] Loaded dispatcher "Catalyst::Dispatcher"
-    [debug] Loaded engine "Catalyst::Engine::HTTP"
-    [debug] Found home "/home/me/MyApp"
-    [debug] Loaded Config "/home/me/MyApp/myapp.conf"
+    [debug] Loaded engine "Catalyst::Engine"
+    [debug] Found home "/home/catalyst/MyApp"
+    [debug] Loaded Config "/home/catalyst/MyApp/myapp.conf"
     [debug] Loaded components:
     .-----------------------------------------------------------------+----------.
     | Class                                                           | Type     |
@@ -1021,7 +999,7 @@ display something like:
     '-------------------------------------+--------------------------------------'
     
     [info] MyApp powered by Catalyst 5.80020
-    You can connect to your server at http://debian:3000
+    HTTP::Server::PSGI: Accepting connections at http://0:3000
 
 B<NOTE:> Be sure you run the C<script/myapp_server.pl> command from the
 'base' directory of your application, not inside the C<script> directory
@@ -1259,15 +1237,15 @@ keys. For example, take a look at C<lib/MyApp/Schema/Result/Book.pm> and
 notice the following code:
 
     =head1 RELATIONS
-
+    
     =head2 book_authors
-
+    
     Type: has_many
-
+    
     Related object: L<MyApp::Schema::Result::BookAuthor>
-
+    
     =cut
-
+    
     __PACKAGE__->has_many(
       "book_authors",
       "MyApp::Schema::Result::BookAuthor",
@@ -1328,15 +1306,15 @@ there is a C<belongs_to> relationship defined that acts as the "mirror
 image" to the C<has_many> relationship we just looked at above:
 
     =head1 RELATIONS
-
+    
     =head2 book
-
+    
     Type: belongs_to
-
+    
     Related object: L<MyApp::Schema::Result::Book>
-
+    
     =cut
-
+    
     __PACKAGE__->belongs_to(
       "book",
       "MyApp::Schema::Result::Book",
@@ -1403,7 +1381,7 @@ alternate way to specify the trace option just in case):
     $ DBIC_TRACE=1 script/myapp_server.pl -r
 
 Make sure that the application loads correctly and that you see the
-three dynamically created model class (one for each of the Result
+three dynamically created model classes (one for each of the Result
 Classes we created).
 
 Then hit the URL L<http://localhost:3000/books/list> with your browser
@@ -1483,11 +1461,11 @@ html" at the end of every field where a user has control over the
 information that can appear in that field (and can therefore inject
 markup or code if you don't "neutralize" those fields).  In addition to
 "| html", Template Toolkit has a variety of other useful filters that
-can found in the documentation for L<Template::Filters>.  (While we are
-on the topic of security and escaping of dangerous values, one of the
-advantages of using tools like DBIC for database access or
+can be found in the documentation for L<Template::Filters>.  (While we
+are on the topic of security and escaping of dangerous values, one of
+the advantages of using tools like DBIC for database access or
 L<HTML::FormFu> for form management [see
-L<Chapter 9|Catalyst::Manual::Tutorial::09_AdvancedCRUD::09_FormFu>
+L<Chapter 9|Catalyst::Manual::Tutorial::09_AdvancedCRUD::09_FormFu>]
 is that they automatically handle most escaping for you and therefore
 dramatically increase the security of your app.)
 
@@ -1500,7 +1478,8 @@ C<scripts/myapp_test.pl> script.  Just supply the URL you wish to
 display and it will run that request through the normal controller
 dispatch logic and use the appropriate view to render the output
 (obviously, complex pages may dump a lot of text to your terminal
-window).  For example, if you type:
+window).  For example, if C<Ctrl+C> out of the development server
+and then type:
 
     $ script/myapp_test.pl "/books/list"
 
@@ -1640,12 +1619,12 @@ C<$c-E<gt>stash-E<gt>{template}> line has changed):
 You should now be able to access the L<http://localhost:3000/books/list>
 URL as before.
 
-B<NOTE:> Please note that if you use the default template technique, you
+B<NOTE:> If you use the default template technique, you
 will B<not> be able to use either the C<$c-E<gt>forward> or the
 C<$c-E<gt>detach> mechanisms (these are discussed in Chapter 2 and
 Chapter 9 of the Tutorial).
 
-B<IMPORTANT:> Make sure that you do NOT skip the following section
+B<IMPORTANT:> Make sure that you do B<not> skip the following section
 before continuing to the next chapter 4 Basic CRUD.
 
 
@@ -1663,17 +1642,18 @@ Check the L<http://localhost:3000/books/list> URL in your browser.  It
 should look the same manner as with earlier sections.
 
 
+You can jump to the next chapter of the tutorial here:
+L<Basic CRUD|Catalyst::Manual::Tutorial::04_BasicCRUD>
+
+
 =head1 AUTHOR
 
 Kennedy Clark, C<hkclark@gmail.com>
 
 Feel free to contact the author for any errors or suggestions, but the
 best way to report issues is via the CPAN RT Bug system at
-<https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Manual>.
-
-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/>.
+L<https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Manual>.
 
-Copyright 2006-2010, Kennedy Clark, under the
+Copyright 2006-2011, Kennedy Clark, under the
 Creative Commons Attribution Share-Alike License Version 3.0
 (L<http://creativecommons.org/licenses/by-sa/3.0/us/>).