docs patch from dopplecoder with cleanups to Cookbook example

[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / Manual / Cookbook.pod

diff --git a/lib/DBIx/Class/Manual/Cookbook.pod b/lib/DBIx/Class/Manual/Cookbook.pod
index ee5ea22..8bacb76 100644 (file)
--- a/lib/DBIx/Class/Manual/Cookbook.pod
+++ b/lib/DBIx/Class/Manual/Cookbook.pod
@@ -13,55 +13,68 @@ DBIx::Class::Manual::Cookbook - Misc receipes
 This is not as easy as it could be, but it's possible. Here's an example to 
 illustrate:
 
-    package Base; 
+       # Set up inherited connection information
+       package MyApp::DBIC; 
 
-    use base qw/DBIx::Class/;
+       use base qw/DBIx::Class/;
 
-    __PACKAGE__->load_components(qw/Core DB/);
-    __PACKAGE__->connection(...);
+       __PACKAGE__->load_components(qw/PK::Auto::SQLite Core DB/);
+       __PACKAGE__->connection(...);
 
-    package Left;
+       # Set up a class for the 'authors' table
+       package MyApp::DBIC::Author;
+       use base qw/MyApp::DBIC/;
 
-    use base qw/Base/;
+       __PACKAGE__->table('authors');
+       __PACKAGE__->add_columns(qw/authID first_name last_name/);
+       __PACKAGE__->set_primary_key(qw/authID/);
 
-    __PACKAGE__->table('left');
-    __PACKAGE__->add_columns(qw/id left_stuff/);
-    __PACKAGE__->set_primary_key(qw/id/);
-    __PACKAGE__->has_many('mid' => 'Mid');
+       # Define relationship to the link table
+       __PACKAGE__->has_many('b2a' => 'MyApp::DBIC::Book2Author', 'authID');
 
-    sub right {
-     my ($self) = @_;
-     return Right->search(
-       { 'left.id' => $self->id },
-       { join => { 'mid' => 'left' }});
-    }
+       # Create the accessor for books from the ::Author class
+       sub books {
+         my ($self) = @_;
+         return MyApp::DBIC::Book->search(
+               { 'b2a.authID' => $self->authID }, { join => 'b2a' }
+         );
+           # 'b2a' refers to the relationship named earlier in the Author class.
+               # 'b2a.authID' refers to the authID column of the b2a relationship,
+               # which becomes accessible in the search by being joined.  
+       }
 
-    package Mid;
+       # define the link table class
+       package MyApp::DBIC::Book2Author;
 
-    use base qw/Base/;
+       use base qw/MyApp::DBIC/;
 
-    __PACKAGE__->table('mid');
-    __PACKAGE__->add_columns(qw/left right/);
-    __PACKAGE__->set_primary_key(qw/left right/);
+       __PACKAGE__->table('book2author');
+       __PACKAGE__->add_columns(qw/bookID authID/);
+       __PACKAGE__->set_primary_key(qw/bookID authID/);
 
-    __PACKAGE__->belongs_to('left' => 'Left');
-    __PACKAGE__->belongs_to('right' => 'Right');
+       __PACKAGE__->belongs_to('authID' => 'MyApp::DBIC::Author');
+       __PACKAGE__->belongs_to('bookID' => 'MyApp::DBIC::Book');
 
-    package Right;
+       package MyApp::DBIC::Book;
 
-    use base qw/Base/;
+       use base qw/MyApp::DBIC/;
 
-    __PACKAGE__->table('right');
-    __PACKAGE__->add_columns(qw/id right_stuff/);
-    __PACKAGE__->set_primary_key(qw/id/);
-    __PACKAGE__->has_many('mid' => 'Mid');
+       __PACKAGE__->table('books');
+       __PACKAGE__->add_columns(qw/bookID title edition isbn publisher year/);
+       __PACKAGE__->set_primary_key(qw/bookID/);
+       
+       __PACKAGE__->has_many('b2a' => 'MyApp::DBIC::Book2Author', 'bookID');
 
-    sub left {
-     my ($self) = @_;
-     return Left->search(
-       { 'right.id' => $self->id },
-       { join => { 'mid' => 'right' });
-    }
+       sub authors {
+        my ($self) = @_;
+        return MyApp::DBIC::Author->search(
+          { 'b2a.bookID' => $self->bookID }, # WHERE clause
+          { join => 'b2a' }); # Join condition
+       }
+
+       # So the above search returns an author record where the bookID field of the
+       # book2author table equals the bookID of the books (using the bookID 
+       # relationship table
 
 =item Advanced Exception handling