Merge 'trunk' into 'DBIx-Class-current'

r12287@haferschleim (orig r1900):  jester | 2006-06-02 21:28:09 +0200
fixed trivial perldoc error
r12293@haferschleim (orig r1906):  castaway | 2006-06-03 13:18:55 +0200
Added "The DBIX::Class way" by Adam Jacob

r12508@haferschleim (orig r1952):  castaway | 2006-06-08 14:55:46 +0200
Fix insert overloading example

diff --git a/lib/DBIx/Class.pm b/lib/DBIx/Class.pm
index 5d7a166..9336d27 100644 (file)
--- a/lib/DBIx/Class.pm
+++ b/lib/DBIx/Class.pm
@@ -87,7 +87,7 @@ Then you can use these classes in your application's code:
   # Create a result set to search for artists.
   # This does not query the DB.
   my $johns_rs = $schema->resultset('Artist')->search(
-    # Build your WHERE using an L<SQL::Abstract> structure:
+    # Build your WHERE using an SQL::Abstract structure:
     { name => { like => 'John%' } }
   );
 

diff --git a/lib/DBIx/Class/Manual/Cookbook.pod b/lib/DBIx/Class/Manual/Cookbook.pod
index 9f2a8fa..7e9a810 100644 (file)
--- a/lib/DBIx/Class/Manual/Cookbook.pod
+++ b/lib/DBIx/Class/Manual/Cookbook.pod
@@ -716,11 +716,11 @@ redispatches your call to store_column to the superclass(es).
 
 You might have a class C<Artist> which has many C<CD>s.  Further, you
 want to create a C<CD> object every time you insert an C<Artist> object.
-You can accomplish this by overriding C<insert>:
+You can accomplish this by overriding C<insert> on your objects:
 
   sub insert {
-    my ( $class, $args_ref ) = @_;
-    my $self = $class->next::method($args_ref);
+    my ( $self, @args ) = @_;
+    $self->next::method(@args);
     $self->cds->new({})->fill_from_artist($self)->insert;
     return $self;
   }

diff --git a/lib/DBIx/Class/Manual/Intro.pod b/lib/DBIx/Class/Manual/Intro.pod
index 737848f..62b0fd2 100644 (file)
--- a/lib/DBIx/Class/Manual/Intro.pod
+++ b/lib/DBIx/Class/Manual/Intro.pod
@@ -7,6 +7,66 @@ DBIx::Class::Manual::Intro - Introduction to DBIx::Class
 So, you are bored with SQL, and want a native Perl interface for your
 database?  Or you've been doing this for a while with L<Class::DBI>,
 and think there's a better way?  You've come to the right place.
+
+=head1 THE DBIx::Class WAY
+
+Here are a few simple tips that will help you get your bearings 
+with DBIx::Class.  
+
+=head2 Tables become ResultSources
+
+DBIx::Class needs to know what your Table structure looks like.  You do that
+by defining L<DBIx::Class::ResultSource>s.  Each table get's a ResultSource,
+which defines the Columns it has, along with any Relationships it has to
+other tables.  (And oh, so much more besides)  The important thing to 
+understand:
+  
+  A ResultSource == Table
+  
+(most of the time, but just bear with my simplification)
+
+=head2 It's all about the ResultSet
+
+So, we've got some ResultSources defined.  Now, we want to actually use 
+those definitions to help us translate the queries we need into
+handy perl objects!  
+
+Let's say we defined a ResultSource for an "album" table with three 
+columns: "albumid", "artist", and "title".  Any time we want to query
+this table, we'll be creating a L<DBIx::Class::ResultSet> from it's
+ResultSource.  For example, the results of:
+
+    SELECT albumid, artist, title FROM album;
+    
+Would be retrieved by creating a ResultSet object from the album
+table's ResultSource, likely by using the "search" method.  
+
+DBIx::Class doesn't limit you to creating only simple ResultSets --
+if you wanted to do something like:
+
+    SELECT title FROM album GROUP BY title;
+   
+You could easily achieve it. 
+
+The important thing to understand: 
+
+   Any time you would reach for a SQL query in DBI, you are 
+   creating a DBIx::Class::ResultSet.
+
+=head2 Search is like "prepare"
+
+DBIx::Class tends to wait until it absolutely must fetch information
+from the database.  If you are returning a ResultSet, the query won't
+execute until you use a method that wants to access the data. (Such
+as "next", or "first")
+
+The important thing to understand:
+
+   Setting up a ResultSet does not execute the query; retrieving
+   the data does.
+
+=head1 SETTING UP DBIx::Class
+
 Let's look at how you can set and use your first native L<DBIx::Class>
 tree.