From: Kennedy Clark <hkclark@gmail.com>
Date: Sun, 3 May 2009 19:27:11 +0000 (+0000)
Subject: Convert to more of a mixture of "DBIC" and "DBIx::Class" as per suggestion from Castaway
X-Git-Tag: v5.8005~158
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=commitdiff_plain;h=a46b474eb241c3eac09ac0cd8af400a864de3ee5

Convert to more of a mixture of "DBIC" and "DBIx::Class" as per suggestion from Castaway
Remove out of date XSUB hack from Authorization.pod
Other minor adjustments
---

diff --git a/lib/Catalyst/Manual/Tutorial/Authorization.pod b/lib/Catalyst/Manual/Tutorial/Authorization.pod
index e1d5496..7eb2a4e 100644
--- a/lib/Catalyst/Manual/Tutorial/Authorization.pod
+++ b/lib/Catalyst/Manual/Tutorial/Authorization.pod
@@ -174,14 +174,6 @@ updating C<url_create> to match the following code:
             # Assign the Book object to the stash for display in the view
             $c->stash->{book} = $book;
     
-            # This is a hack to disable XSUB processing in Data::Dumper
-            # (it's used in the view).  This is a work-around for a bug in
-            # the interaction of some versions or Perl, Data::Dumper & DBIC.
-            # You won't need this if you aren't using Data::Dumper (or if
-            # you are running DBIC 0.06001 or greater), but adding it doesn't
-            # hurt anything either.
-            $Data::Dumper::Useperl = 1;
-    
             # Set the TT template to use
             $c->stash->{template} = 'books/create_done.tt2';
         } else {
diff --git a/lib/Catalyst/Manual/Tutorial/BasicCRUD.pod b/lib/Catalyst/Manual/Tutorial/BasicCRUD.pod
index 74f7f2a..57e9419 100644
--- a/lib/Catalyst/Manual/Tutorial/BasicCRUD.pod
+++ b/lib/Catalyst/Manual/Tutorial/BasicCRUD.pod
@@ -953,7 +953,7 @@ This will modify the C<books> table to include the two new fields
 and populate those fields with the current time.
 
 
-=head2 Update DBIC to Automatically Handle the Datetime Columns
+=head2 Update DBIx::Class to Automatically Handle the Datetime Columns
 
 Next, we should re-run the DBIC helper to update the Result Classes
 with the new fields:
@@ -991,10 +991,11 @@ B<above> the C<1;> on the last line):
         { data_type => 'datetime', set_on_create => 1, set_on_update => 1 },
     );
 
-This will override the definition for these fields that Schema::Loader
-placed at the top of the file.  The C<set_on_create> and
-C<set_on_update> options will cause DBIC to automatically update the
-timestamps in these columns whenever a row is created or modified.
+This will override the definition for these fields that Schema::Loader 
+placed at the top of the file.  The C<set_on_create> and 
+C<set_on_update> options will cause DBIx::Class to automatically 
+update the timestamps in these columns whenever a row is created or 
+modified.
 
 To test this out, restart the development server using the
 C<DBIC_TRACE=1> option:
@@ -1039,7 +1040,7 @@ controller code.
 
 To illustrate the concept with a fairly simple example, let's create a
 method that returns books added in the last 10 minutes.  Start by
-making a directory where DBIC will look for our ResultSet Class:
+making a directory where DBIx::Class will look for our ResultSet Class:
 
     mkdir lib/MyApp/Schema/ResultSet
 
@@ -1115,20 +1116,20 @@ try a higher or lower value.
 
 =head2 Chaining ResultSets
 
-One of the most helpful and powerful features in DBIC is that it allows
-you to "chain together" a series of queries (note that this has nothing
-to do with the "Chained Dispatch" for Catalyst that we were discussing
-above).  Because each ResultSet returns another ResultSet, you can take
-an initial query and immediately feed that into a second query (and so
-on for as many queries you need). Note that no matter how many
-ResultSets you chain together, the database itself will not be hit until
-you use a method that attempts to access the data. And, because this
-technique carries over to the ResultSet Class feature we implemented in
-the previous section for our "canned search", we can combine the two
-capabilities.  For example, let's add an action to our C<Books>
-controller that lists books that are both recent I<and> have "TCP" in
-the title.  Open up C<lib/MyApp/Controller/Books.pm> and add the
-following method:
+One of the most helpful and powerful features in DBIx::Class is that 
+it allows you to "chain together" a series of queries (note that this 
+has nothing to do with the "Chained Dispatch" for Catalyst that we 
+were discussing above).  Because each ResultSet returns another 
+ResultSet, you can take an initial query and immediately feed that 
+into a second query (and so on for as many queries you need). Note 
+that no matter how many ResultSets you chain together, the database 
+itself will not be hit until you use a method that attempts to access 
+the data. And, because this technique carries over to the ResultSet 
+Class feature we implemented in the previous section for our "canned 
+search", we can combine the two capabilities.  For example, let's add 
+an action to our C<Books> controller that lists books that are both 
+recent I<and> have "TCP" in the title.  Open up 
+C<lib/MyApp/Controller/Books.pm> and add the following method:
 
     =head2 list_recent_tcp
 
@@ -1233,16 +1234,16 @@ more flexible at the same time.
 
 =head2 Adding Methods to Result Classes
 
-In the previous two sections we saw a good example of how we could use
-DBIC ResultSet Classes to clean up our code for an entire query (for
-example, our "canned searches" that filtered the entire query).  We
-can do a similar improvement when working with individual rows as
-well.  Whereas the ResultSet construct is used in DBIC to correspond
-to an entire query, the Result Class construct is used to represent a
-row. Therefore, we can add row-specific "helper methods" to our Result
-Classes stored in C<lib/MyApp/Schema/Result/>. For example, open
-C<lib/MyApp/Schema/Result/Authors.pm> and add the following method
-(as always, it must be above the closing "C<1;>"):
+In the previous two sections we saw a good example of how we could use 
+DBIx::Class ResultSet Classes to clean up our code for an entire query 
+(for example, our "canned searches" that filtered the entire query). 
+We can do a similar improvement when working with individual rows as 
+well.  Whereas the ResultSet construct is used in DBIC to correspond 
+to an entire query, the Result Class construct is used to represent a 
+row. Therefore, we can add row-specific "helper methods" to our Result 
+Classes stored in C<lib/MyApp/Schema/Result/>. For example, open 
+C<lib/MyApp/Schema/Result/Authors.pm> and add the following method (as 
+always, it must be above the closing "C<1;>"):
 
     #
     # Helper methods
diff --git a/lib/Catalyst/Manual/Tutorial/Intro.pod b/lib/Catalyst/Manual/Tutorial/Intro.pod
index b51f252..1a091a4 100644
--- a/lib/Catalyst/Manual/Tutorial/Intro.pod
+++ b/lib/Catalyst/Manual/Tutorial/Intro.pod
@@ -602,7 +602,7 @@ with the following commands:
     wget http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/MyApp_Chapter8.tgz
     tar zxvf MyApp_Chapter8.tgz
     cd MyApp
-    CATALYST_DEBUG=0 prove --lib lib  t
+    CATALYST_DEBUG=0 prove --lib lib t
 
 If you wish to include the L<HTML::FormFu|HTML::FormFu> section in 
 your tests, substitute C<MyApp_Chapter9_FormFu.tgz> for 
diff --git a/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod b/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod
index b6f9e72..f3ff00e 100644
--- a/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod
+++ b/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod
@@ -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>
@@ -653,18 +654,18 @@ 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 DBIC, as will this tutorial.
+applications rely on DBIx::Class, as will this tutorial.
 
-Although DBIC 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).
+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 Make Sure You Have a Recent Version of the DBIC Model
+=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
@@ -683,7 +684,7 @@ And re-run the version print command to verify that you are now at
 0.23 or higher.
 
 
-=head2 Create Static DBIC Schema Files
+=head2 Create Static DBIx::Class Schema Files
 
 Use the model helper with the C<create=static> option to read the 
 database with 
@@ -742,7 +743,7 @@ 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 
+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 
@@ -768,7 +769,7 @@ 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 
+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 
@@ -990,8 +991,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
 
@@ -1175,7 +1176,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.
 
 
-=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 
@@ -1212,26 +1213,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
@@ -1304,11 +1305,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>
@@ -1340,7 +1338,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