From: Jess Robinson <castaway@desert-island.me.uk>
Date: Fri, 24 Mar 2006 21:24:23 +0000 (+0000)
Subject: Yet more docs ;)
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=d2113a6853f7ae702b922d936f5ac4d323c7da65;p=dbsrgits%2FDBIx-Class-Historic.git

Yet more docs ;)
---

diff --git a/lib/DBIx/Class/Relationship.pm b/lib/DBIx/Class/Relationship.pm
index b308555..c479e4c 100644
--- a/lib/DBIx/Class/Relationship.pm
+++ b/lib/DBIx/Class/Relationship.pm
@@ -19,6 +19,22 @@ DBIx::Class::Relationship - Inter-table relationships
 
 =head1 SYNOPSIS
 
+  MyDB::Schema::Actor->has_many('actorroles' => 'MyDB::Schema::ActorRole', 
+                                'actor');
+  MyDB::Schema::Role->has_many('actorroles' => 'MyDB::Schema::ActorRole', 
+                                'role');
+  MyDB::Schema::ActorRole->belongs_to('role' => 'MyDB::Schema::Role');
+  MyDB::Schema::ActorRole->belongs_to('actor' => 'MyDB::Schema::Actor');
+
+  MyDB::Schema::Role->many_to_many('actors' => 'actorroles', 'actor');
+  MyDB::Schema::Actor->many_to_many('roles' => 'actorroles', 'role');
+
+  $schema->resultset('Actor')->roles();
+  $schema->resultset('Role')->search_related('actors', { Name => 'Fred' });
+  $schema->resultset('ActorRole')->add_to_role({ Name => 'Sherlock Holmes'});
+
+See L<DBIx::Class::Manual::Cookbook> for more.
+
 =head1 DESCRIPTION
 
 This class provides methods to set up relationships between the tables
@@ -75,7 +91,8 @@ will produce a query something like:
 all without needing multiple fetches.
 
 Only the helper methods for setting up standard relationship types
-are documented here. For the basic, lower-level methods, see
+are documented here. For the basic, lower-level methods, and a description
+of all the useful *_related methods that you get for free, see
 L<DBIx::Class::Relationship::Base>.
 
 =head1 METHODS
@@ -91,7 +108,7 @@ See L<DBIx::Class::Relationship::Base> for a list of valid attributes.
 =head2 belongs_to
 
   # in a Book class (where Author has many Books)
-  My::DBIC::Schema::Book->belongs_to(author => 'Author');
+  My::DBIC::Schema::Book->belongs_to(author => 'My::DBIC::Schema::Author');
   my $author_obj = $obj->author;
   $obj->author($new_author_obj);
 
@@ -107,7 +124,7 @@ of C<has_a>.
 =head2 has_many
 
   # in an Author class (where Author has many Books)
-  My::DBIC::Schema::Author->has_many(books => 'Book', 'author');
+  My::DBIC::Schema::Author->has_many(books => 'My::DBIC::Schema::Book', 'author');
   my $booklist = $obj->books;
   my $booklist = $obj->books({
     name => { LIKE => '%macaroni%' },
@@ -122,13 +139,18 @@ foreign class store the calling class's primary key in one (or more) of its
 columns. You should pass the name of the column in the foreign class as the
 $cond argument, or specify a complete join condition.
 
+As well as the accessor method, a method named C<< add_to_<relname> >>
+will also be added to your Row items, this allows you to insert new
+related items, using the same mechanism as in L<DBIx::Class::Relationship::Base/"create_related">.
+
 If you delete an object in a class with a C<has_many> relationship, all
 related objects will be deleted as well. However, any database-level
 cascade or restrict will take precedence.
 
 =head2 might_have
 
-  My::DBIC::Schema::Author->might_have(pseudonym => 'Pseudonyms');
+  My::DBIC::Schema::Author->might_have(pseudonym => 
+                                       'My::DBIC::Schema::Pseudonyms');
   my $pname = $obj->pseudonym; # to get the Pseudonym object
 
 Creates an optional one-to-one relationship with a class, where the foreign
@@ -141,7 +163,7 @@ Any database-level update or delete constraints will override this behaviour.
 
 =head2 has_one
 
-  My::DBIC::Schema::Book->has_one(isbn => ISBN);
+  My::DBIC::Schema::Book->has_one(isbn => 'My::DBIC::Schema::ISBN');
   my $isbn_obj = $obj->isbn;
 
 Creates a one-to-one relationship with another class. This is just like
@@ -153,7 +175,16 @@ left join.
 
 =head2 many_to_many
 
-  My::DBIC::Schema::Actor->many_to_many( roles => 'actor_roles', 'Roles' );
+  My::DBIC::Schema::Actor->has_many( actor_roles => 
+                                     'My::DBIC::Schema::ActorRoles',
+                                     'actor' );
+  My::DBIC::Schema::ActorRoles->belongs_to( role => 
+                                            'My::DBIC::Schema::Role' );
+  My::DBIC::Schema::ActorRoles->belongs_to( actor => 
+                                            'My::DBIC::Schema::Actor' );
+
+  My::DBIC::Schema::Actor->many_to_many( roles => 'actor_roles',
+                                         'My::DBIC::Schema::Roles' );
 
   ...
 
@@ -162,6 +193,9 @@ left join.
 Creates an accessor bridging two relationships; not strictly a relationship
 in its own right, although the accessor will return a resultset or collection
 of objects just as a has_many would.
+To use many_to_many, existing relationships from the original table to the link
+table, and from the link table to the end table must already exist, these 
+relation names are then used in the many_to_many call.
 
 =cut