This patch fixes a couple small formatting glitches, plus two errors
In the pod for Relationship.pm.
In three spots the join condition column names were wrong, e.g.
My::DBIC::Schema::Author->has_many( books =>
'My::DBIC::Schema::Book', {
- 'foreign.author' => 'self.author',
+ 'foreign.author' => 'self.id',
});
And in the description for belongs_to() the foreign key was
mistakenly identified as being in the "related class". Unlike the
other relationships, the key described for belongs_to() is in the
"calling class".
I saw _somewhere_ a nice cheatsheet for "what that dang third
argument could be". And I know it has come up on the maillist. The
constant description is that the third argument is always the
"foreign key column name" (unless it is a join condition). But it is
darn hard to remember who/to/from/where correctly each time.
has_many
might_have
has_one
the foreign key column name in the *other* table that
references the primary key of *this* table
belongs_to
the foreign key column name in *this* table that references
the primary key of the *other* table--- Relationship.pm.rev_2802 Sat Sep 30 21:39:07 2006
+++ Relationship.pm Sat Sep 30 23:14:44 2006
@@ -23,6 +23,7 @@
'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');
@@ -60,6 +61,7 @@
my $fred = $schema->resultset('Author')->find({ Name => 'Fred' });
my $fredsbooks = $schema->resultset('Book')->search({ Author => $fred->ID });
+
With a has_many relationship called "books" on Author (see below for details),
we can do this instead:
@@ -69,9 +71,9 @@
L<DBIx::Class::Manual::Glossary/"Row"> objects that represent the items
of your table. From L<DBIx::Class::Manual::Glossary/"ResultSet"> objects,
the relationships can be searched using the "search_related" method.
-In list context, each returns a list of Row objects for the related class,
+In list context, each call returns a list of Row objects for the related class,
in scalar context, a new ResultSet representing the joined tables is
-returned. Thus, the calls can be chained to produce complex queries.
+returned. Thus the calls can be chained to produce complex queries.
Since the database is not actually queried until you attempt to retrieve
the data for an actual item, no time is wasted producing them.
@@ -99,8 +101,8 @@
All helper methods take the following arguments:
- __PACKAGE__>$method_name('relname', 'Foreign::Class', $cond, $attrs);
-
+ __PACKAGE__->$method_name('relname', 'Foreign::Class', $cond, $attrs);
+
Both C<$cond> and C<$attrs> are optional. Pass C<undef> for C<$cond> if
you want to use the default value for it, but still want to set C<$attrs>.
@@ -121,17 +123,23 @@
my $author_obj = $obj->author; # get author object
$obj->author( $new_author_obj ); # set author object
-The above belongs_to relationship could also have been specified as,
+The above belongs_to relationship defaults to the same as
- My::DBIC::Schema::Book->belongs_to( author,
- 'My::DBIC::Schema::Author',
- { 'self.author' => 'foreign.author' } );
-
-Creates a relationship where the calling class stores the foreign class's
-primary key in one (or more) of its columns. This relationship defaults to
-using C<$accessor_name> as the foreign key in C<$related_class> to resolve the
-join, unless C<$foreign_key_column> specifies the foreign key column in
-C<$related_class> or C<$cond> specifies a reference to a join condition hash.
+ My::DBIC::Schema::Book->belongs_to( 'author' => 'My::DBIC::Schema::Author',
+ 'author' );
+
+or to explicitly describe the join relationship could have been written
+
+ My::DBIC::Schema::Book->belongs_to( 'author' => 'My::DBIC::Schema::Author',
+ { 'foreign.id' => 'self.author' } );
+
+Creates a relationship description where this class stores the foreign class's
+primary key value in one (or more) of its columns. If the third argument
+isn't specified, then C<$accessor_name> will be used as the default column
+name for this classes' foreign key value. The third argument can be used to
+specify the foreign key column name as C<$foreign_key_column>, when the
+accessor name doesn't match the table column name. Finally, the third
+argument C<$cond> can specify the full join condition hash.
If the relationship is optional -- i.e. the column containing the foreign key
can be NULL -- then the belongs_to relationship does the right thing. Thus, in
@@ -181,7 +189,7 @@
explicit join condition:
My::DBIC::Schema::Author->has_many( books => 'My::DBIC::Schema::Book', {
- 'foreign.author' => 'self.author',
+ 'foreign.author' => 'self.id',
});
Creates a one-to-many relationship, where the corresponding elements of the
@@ -232,9 +240,7 @@
My::DBIC::Schema::Author->might_have( pseudonym =>
'My::DBIC::Schema::Pseudonym',
- { 'foreign.author' => 'self.author' }
);
-
-Assuming the Pseudonym table has
+ { 'foreign.author' => 'self.id' } );
Creates an optional one-to-one relationship with a class. This relationship
defaults to using C<$accessor_name> as the foreign key in C<$related_class> to
_______________________________________________
List: http://lists.rawmode.org/cgi-bin/mailman/listinfo/dbix-class
Wiki: http://dbix-class.shadowcatsystems.co.uk/
IRC: irc.perl.org#dbix-class
SVN: http://dev.catalyst.perl.org/repos/bast/trunk/DBIx-Class/
Searchable Archive: http://www.mail-archive.com/[email protected]/
