X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FTutorial%2FMoreCatalystBasics.pod;h=092b8674cbf1ba386366a9406e1b690b522aa209;hp=c2edcbe1ca79370b75f915cd3d837fb09833f167;hb=98fd8420ab3b60bf830264311beebe0a5f334478;hpb=4d63a0d5e1abea67f1128011988b508f49caa1bc

diff --git a/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod b/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod
index c2edcbe..092b867 100644
--- a/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod
+++ b/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod
@@ -344,7 +344,7 @@ path.  For example, "C<:Path('list')>" in
 C<lib/MyApp/Controller/Books.pm> would match on the URL 
 C<http://localhost:3000/books/list> but "C<:Path('/list')>" would match 
 on C<http://localhost:3000/list>.  You can use C<:Args()> to specify 
-how many arguments an action should except.  See 
+how many arguments an action should accept.  See 
 L<Catalyst::Manual::Intro/Action_types> for more information and a few 
 examples.
 
@@ -499,6 +499,7 @@ Then create C<root/src/books/list.tt2> in your editor and enter:
       <tr>
         <td>[% book.title %]</td>
         <td>[% book.rating %]</td>
+        <td></td>
       </tr>
     [% END -%]
     </table>
@@ -644,33 +645,161 @@ L<Appendix 2|Catalyst::Manual::Tutorial::Appendices>.
 
 =head1 DATABASE ACCESS WITH DBIx::Class
 
-Catalyst can be used with virtually any form of datastore available via
-Perl.  For example, L<Catalyst::Model::DBI|Catalyst::Model::DBI> can be
-used to access databases through the traditional Perl C<DBI>
-interface. However, most Catalyst applications use some form of
-object-relational mapping (ORM) technology to create objects associated
-with tables in a relational database.  Although L<Class::DBI|Class::DBI>
-has been a popular choice in the past, Matt Trout's
-L<DBIx::Class|DBIx::Class> (abbreviated as "DBIC") has rapidly emerged
-as the Perl-based ORM technology of choice. Most new Catalyst
-applications rely on DBIC, as will this tutorial.
+Catalyst can be used with virtually any form of datastore available 
+via Perl.  For example, L<Catalyst::Model::DBI|Catalyst::Model::DBI> 
+can be used to access databases through the traditional Perl C<DBI> 
+interface or you can use a model to access files of any type on the 
+filesystem.  However, most Catalyst applications use some form of 
+object-relational mapping (ORM) technology to create objects 
+associated with tables in a relational database.  Matt Trout's 
+L<DBIx::Class|DBIx::Class> (abbreviated as "DBIC") has rapidly emerged 
+as the Perl-based ORM technology of choice. Most new Catalyst 
+applications rely on DBIx::Class, as will this tutorial.
 
+Although DBIx::Class has included support for a C<create=dynamic> mode 
+to automatically read the database structure every time the 
+application starts, it's use is no longer recommended.  While it can 
+make for "flashy" demos, the use of the C<create=static> mode we use 
+below can be implemented just as quickly and provides many advantages 
+(such as the ability to add your own methods to the overall DBIC 
+framework, a technique that we see in Chapter 4).
 
-=head2 Create a Dynamic DBIC Model
 
-Use the C<create=dynamic> model helper option to build a model that
-dynamically reads your database structure every time the application
-starts:
+=head2 Make Sure You Have a Recent Version of the DBIx::Class Model
+
+First, let's be sure we have a recent version of the DBIC helper,
+L<Catalyst::Model::DBIC::Schema|Catalyst::Model::DBIC::Schema>, by
+running this command:
+
+    $ perl -MCatalyst::Model::DBIC::Schema -e \
+        'print "$Catalyst::Model::DBIC::Schema::VERSION\n"'
+    0.23
+
+If you don't have version 0.23 or higher, please run this command
+to install it directly from CPAN:
+
+    $ sudo cpan Catalyst::Model::DBIC::Schema
+
+And re-run the version print command to verify that you are now at 
+0.23 or higher.
+
+
+=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 C<create=static> option to read the database with 
+L<DBIx::Class::Schema::Loader|DBIx::Class::Schema::Loader> and 
+automatically build the required files for us:
 
     $ script/myapp_create.pl model DB DBIC::Schema MyApp::Schema \
-        create=dynamic dbi:SQLite:myapp.db
+        create=static components=TimeStamp dbi:SQLite:myapp.db
      exists "/home/me/MyApp/script/../lib/MyApp/Model"
      exists "/home/me/MyApp/script/../t"
-     exists "/home/me/MyApp/script/../lib/MyApp"
-    created "/home/me/MyApp/script/../lib/MyApp/Schema.pm"
+    Dumping manual schema for MyApp::Schema to directory /home/me/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"
 
+The C<script/myapp_create.pl> command breaks down like this:
+
+=over 4
+
+=item *
+
+C<DB> is the name of the model class to be created by the helper in 
+C<lib/MyApp/Model>.
+
+=item *
+
+C<DBIC::Schema> is the type of the model to create.
+
+=item *
+
+C<MyApp::Schema> is the name of the DBIC schema file written to
+C<lib/MyApp/Schema.pm>.
+
+=item *
+
+C<create=static> causes 
+L<DBIx::Class::Schema::Loader|DBIx::Class::Schema::Loader> to 
+load the schema as it runs and then write that information out
+into files.
+
+=item *
+
+C<components=TimeStamp> causes the help to include the 
+L<DBIx::Class::TimeStamp|DBIx::Class::TimeStamp> DBIC component.
+
+=item *
+
+And finally, C<dbi:SQLite:myapp.db> is the standard DBI connect string 
+for use with SQLite.
+
+=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 a subdirectory called "Result".  This "Result" subdirectory then 
+has files named according to each of the tables in our simple database 
+(C<Authors.pm>, C<BookAuthors.pm>, and C<Books.pm>).  These three 
+files are called "Result Classes" in DBIx::Class nomenclature. Although the 
+Result Class files are named after tables in our database, the classes 
+correspond to the I<row-level data> that is returned by DBIC (more on 
+this later, especially in 
+L<Catalyst::Manual::Tutorial::BasicCRUD/EXPLORING THE POWER OF DBIC>).
+
+The idea with the Result Source files created under 
+C<lib/MyApp/Schema/Result> by the C<create=static> option is to only 
+edit the files below the C<# DO NOT MODIFY THIS OR ANYTHING ABOVE!> 
+warning. If you place all of your changes below that point in the 
+file, you can regenerate the automatically created information at the 
+top of each file should your database structure get updated.
+
+Also note the "flow" of the model information across the various files 
+and directories.  Catalyst will initially load the model from 
+C<lib/MyApp/Model/DB.pm>.  This file contains a reference to 
+C<lib/MyApp/Schema.pm>, so that file is loaded next.  Finally, the 
+call to C<load_namespaces> in C<Schema.pm> will load each of the 
+"Result Class" files from the C<lib/MyApp/Schema/Result> subdirectory. 
+The final outcome is that Catalyst will dynamically create three 
+table-specific Catalyst models every time the application starts (you 
+can see these three model files listed in the debug output generated 
+when you launch the application).
+
+B<NOTE:> Older versions of 
+L<Catalyst::Model::DBIC::Schema|Catalyst::Model::DBIC::Schema> use the 
+deprecated DBIx::Class C<load_classes> technique instead of the newer 
+C<load_namspaces>.  For new applications, please try to use 
+C<load_namespaces> since it more easily supports a very useful DBIC 
+technique called "ResultSet Classes."  If you need to convert an 
+existing application from "load_classes" to "load_namespaces," you can 
+use this process to automate the migration (but first make sure you 
+have v0.23 C<Catalyst::Model::DBIC::Schema> as discussed above):
+
+    $ # First delete the existing schema file to disable "compatibility" mode
+    $ rm lib/MyApp/Schema.pm
+    $
+    $ # Then re-run the helper to build the files for "load_namespaces"
+    $ script/myapp_create.pl model DB DBIC::Schema MyApp::Schema \
+        create=static components=TimeStamp dbi:SQLite:myapp.db
+    $
+    $ # Now convert the existing files over
+    $ cd lib/MyApp/Schema
+    $ perl -MIO::All -e 'for (@ARGV) { my $s < io($_); $s =~ s/.*\n\# You can replace.*?\n//s;
+          $s =~ s/'MyApp::Schema::/'MyApp::Schema::Result::/g; my $d < io("Result/$_");
+          $d =~ s/1;\n?//; "$d$s" > io("Result/$_"); }' *.pm
+    $ cd ../../..
+    $
+    $ # And finally delete the old files
+    $ rm lib/MyApp/Schema/*.pm
+
+The "C<perl -MIO::ALL ...>" script will copy all the customized 
+relationship (and other) information below "C<# DO NOT MODIFY>" line 
+from the old files in C<lib/MyApp/Schema> to the new files in 
+C<lib/MyApp/Schema/Result> (we will be starting to add some 
+"customized relationship information in the section below).
 
 The C<script/myapp_create.pl> command breaks down like this:
 
@@ -704,11 +833,6 @@ for use with SQLite.
 
 =back
 
-B<NOTE:> Although the C<create=dynamic> option to the DBIC helper
-makes for a nifty demonstration, is only really suitable for very
-small applications. After this demonstration, you should almost always
-use the C<create=static> option that we will switch to below.
-
 
 =head1 ENABLE THE MODEL IN THE CONTROLLER
 
@@ -868,8 +992,8 @@ books loaded by the C<myapp01.sql> script above without any formatting.
 The rating for each book should appear on each row, but the "Author(s)"
 column will still be blank (we will fill that in later).
 
-Also notice in the output of the C<script/myapp_server.pl> that DBIC
-used the following SQL to retrieve the data:
+Also notice in the output of the C<script/myapp_server.pl> that 
+DBIx::Class used the following SQL to retrieve the data:
 
     SELECT me.id, me.title, me.rating FROM books me
 
@@ -1053,126 +1177,7 @@ provide a template that fills in the C<content> section of our wrapper
 template -- the wrapper will provide the overall feel of the page.
 
 
-=head1 A STATIC DATABASE MODEL WITH DBIx::Class
-
-First, let's be sure we have a recent version of the DBIC helper,
-L<Catalyst::Model::DBIC::Schema|Catalyst::Model::DBIC::Schema>, by
-running this command:
-
-    $ perl -MCatalyst::Model::DBIC::Schema -e \
-        'print "$Catalyst::Model::DBIC::Schema::VERSION\n"'
-    0.23
-
-If you don't have version 0.23 or higher, please run this command
-to install it directly from CPAN:
-
-    $ sudo cpan Catalyst::Model::DBIC::Schema
-
-And re-run the version print command to verify that you are now at 
-0.23 or higher.
-
-
-=head2 Create Static DBIC Schema Files
-
-Unlike the previous DBIC section where we had C<create=dynamic>
-automatically discover the structure of the database every time the
-application started, here we will use static schema files for more
-control.  This is typical of most "real world" applications.
-
-One option would be to manually create a separate schema file for each 
-table in the database. However, let's use the same 
-L<DBIx::Class::Schema::Loader|DBIx::Class::Schema::Loader> we used 
-earlier with C<create=dynamic> to build the static files for us. 
-First, let's remove the schema file created earlier:
-
-    $ rm lib/MyApp/Schema.pm
-
-Now regenerate the schema using the C<create=static> option:
-
-    $ script/myapp_create.pl model DB DBIC::Schema MyApp::Schema \
-        create=static components=TimeStamp dbi:SQLite:myapp.db
-     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 ...
-    Schema dump completed.
-     exists "/home/me/MyApp/script/../lib/MyApp/Model/DB.pm"
-
-We could have also deleted C<lib/MyApp/Model/DB.pm>, but it would
-have regenerated the same file (note the C<exists> in the output above).
-If you take a look at C<lib/MyApp/Model/DB.pm>, it simply contains
-a reference to the actual schema file in C<lib/MyApp/Schema.pm>
-along with the database connect string.
-
-If you look in the C<lib/MyApp/Schema.pm> file, you will find that it 
-is no longer using 
-L<DBIx::Class::Schema::Loader|DBIx::Class::Schema::Loader> as its base 
-class (L<DBIx::Class::Schema::Loader|DBIx::Class::Schema::Loader> is 
-only being used by the helper to load the schema once and then create 
-the static files for us) and C<Schema.pm> 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 a subdirectory 
-called "Result".  This "Result" subdirectory then has files named 
-according to each of the tables in our simple database (C<Authors.pm>, 
-C<BookAuthors.pm>, and C<Books.pm>).  These three files are called 
-"Result Classes" in DBIC nomenclature. Although the Result Class files 
-are named after tables in our database, the classes correspond to the 
-I<row-level data> that is returned by DBIC (more on this later, 
-especially in 
-L<Catalyst::Manual::Tutorial::BasicCRUD/EXPLORING THE POWER OF DBIC>).
-
-The idea with the Result Source files created under 
-C<lib/MyApp/Schema/Result> by the C<create=static> option is to only 
-edit the files below the C<# DO NOT MODIFY THIS OR ANYTHING ABOVE!> 
-warning. If you place all of your changes below that point in the 
-file, you can regenerate the automatically created information at the 
-top of each file should your database structure get updated.
-
-Also note the "flow" of the model information across the various files 
-and directories.  Catalyst will initially load the model from 
-C<lib/MyApp/Model/DB.pm>.  This file contains a reference to 
-C<lib/MyApp/Schema.pm>, so that file is loaded next.  Finally, the 
-call to C<load_namespaces> in C<Schema.pm> will load each of the 
-"Result Class" files from the C<lib/MyApp/Schema/Result> subdirectory. 
-The final outcome is that Catalyst will dynamically create three 
-table-specific Catalyst models every time the application starts (you 
-can see these three model files listed in the debug output generated 
-when you launch the application).
-
-B<NOTE:> Older versions of 
-L<Catalyst::Model::DBIC::Schema|Catalyst::Model::DBIC::Schema> use the 
-deprecated DBIC C<load_classes> technique instead of the newer 
-C<load_namspaces>.  For new applications, please try to use 
-C<load_namespaces> since it more easily supports a very useful DBIC 
-technique called "ResultSet Classes."  If you need to convert an 
-existing application from "load_classes" to "load_namespaces," you can 
-use this process to automate the migration (but first make sure you 
-have v0.23 C<Catalyst::Model::DBIC::Schema> as discussed above):
-
-    $ # First delete the existing schema file to disable "compatibility" mode
-    $ rm lib/MyApp/Schema.pm
-    $
-    $ # Then re-run the helper to build the files for "load_namespaces"
-    $ script/myapp_create.pl model DB DBIC::Schema MyApp::Schema \
-        create=static components=TimeStamp dbi:SQLite:myapp.db
-    $
-    $ # Now convert the existing files over
-    $ cd lib/MyApp/Schema
-    $ perl -MIO::All -e 'for (@ARGV) { my $s < io($_); $s =~ s/.*\n\# You can replace.*?\n//s;
-          $s =~ s/'MyApp::Schema::/'MyApp::Schema::Result::/g; my $d < io("Result/$_");
-          $d =~ s/1;\n?//; "$d$s" > io("Result/$_"); }' *.pm
-    $ cd ../../..
-    $
-    $ # And finally delete the old files
-    $ rm lib/MyApp/Schema/*.pm
-
-The "C<perl -MIO::ALL ...>" script will copy all the customized 
-relationship (and other) information below "C<# DO NOT MODIFY>" line 
-from the old files in C<lib/MyApp/Schema> to the new files in 
-C<lib/MyApp/Schema/Result> (we will be starting to add some 
-"customized relationship information in the section below).
-
-
-=head2 Updating the Generated DBIC Result Class Files
+=head2 Updating the Generated DBIx::Class Result Class Files
 
 Let's manually add some relationship information to the auto-generated 
 Result Class files. (Note: if you are using a database other than 
@@ -1209,26 +1214,26 @@ C<1;> on a line by itself.
 C<Important Note:> Although this tutorial uses plural names for both 
 the names of the SQL tables and therefore the Result Classes (after 
 all, C<Schema::Loader> automatically named the Result Classes from the 
-names of the SQL tables it found), DBIC users prefer singular names 
-for these items.  B<Please try to use singular table and DBIC 
+names of the SQL tables it found), DBIx::Class users prefer singular 
+names for these items.  B<Please try to use singular table and DBIC 
 model/Result Class names in your applications.>  This tutorial will 
 migrate to singular names as soon as possible (patches welcomed). 
 B<Note that while singular is preferred for the DBIC model, plural is 
 perfectly acceptable for the names of the controller classes.>  After 
 all, the C<Books.pm> controller operates on multiple books.
 
-This code defines both a C<has_many> and a C<many_to_many> relationship.
-The C<many_to_many> relationship is optional, but it makes it easier to
-map a book to its collection of authors.  Without it, we would have to
-"walk" though the C<book_authors> table as in 
-C<$book-E<gt>book_authors-E<gt>first-E<gt>author-E<gt>last_name> 
-(we will see examples on how to use DBIC objects in your code soon, 
+This code defines both a C<has_many> and a C<many_to_many> 
+relationship. The C<many_to_many> relationship is optional, but it 
+makes it easier to map a book to its collection of authors.  Without 
+it, we would have to "walk" though the C<book_authors> table as in 
+C<$book-E<gt>book_authors-E<gt>first-E<gt>author-E<gt>last_name> (we 
+will see examples on how to use DBIx::Class objects in your code soon, 
 but note that because C<$book-E<gt>book_authors> can return multiple 
 authors, we have to use C<first> to display a single author). 
-C<many_to_many> allows us to use the shorter 
-C<$book-E<gt>authors-E<gt>first-E<gt>last_name>. 
-Note that you cannot define a C<many_to_many> relationship without 
-also having the C<has_many> relationship in place.
+C<many_to_many> allows us to use the shorter C<$book-E<gt>authors-
+E<gt>first-E<gt>last_name>. Note that you cannot define a 
+C<many_to_many> relationship without also having the C<has_many> 
+relationship in place.
 
 Then edit C<lib/MyApp/Schema/Result/Authors.pm> and add relationship
 information as follows (again, be careful to put in above the C<1;> but
@@ -1301,11 +1306,8 @@ template to do that.
 
 Let's add a new column to our book list page that takes advantage of 
 the relationship information we manually added to our schema files in 
-the previous section.  Edit C<root/src/books/list.tt2> and add the 
-following code below the existing table cell that contains 
-C<book.rating> (IOW, add a new table cell below the existing two 
-C<E<lt>tdE<gt>> tags but above the closing C<E<lt>/trE<gt>> and 
-C<E<lt>/tableE<gt>> tags):
+the previous section.  Edit C<root/src/books/list.tt2> and replace
+the "empty" tabase cell with the following:
 
     ...
     <td>
@@ -1337,7 +1339,7 @@ browser window.)
 If you are still running the development server with C<DBIC_TRACE>
 enabled, you should also now see five more C<SELECT> statements in the
 debug output (one for each book as the authors are being retrieved by
-DBIC):
+DBIx::Class):
 
     SELECT me.id, me.title, me.rating FROM books me:
     SELECT author.id, author.first_name, author.last_name FROM book_authors me