docs updates to Relationship and ResultSet

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

=head1 NAME 

DBIx::Class::Manual::Cookbook - Misc recipes

=head1 DESCRIPTION

Things that could be handy

=head1 RECIPES

=item Input validation.

=item Using joins

=item Many-to-many relationships

This is not as easy as it could be, but it's possible. Here's an example to 
illustrate:

	# Set up inherited connection information
	package MyApp::DBIC; 
	use base qw/DBIx::Class/;

	__PACKAGE__->load_components(qw/PK::Auto::SQLite Core DB/);
	__PACKAGE__->connection(...);

	# Set up a class for the 'authors' table
	package MyApp::DBIC::Author;
	use base qw/MyApp::DBIC/;

	__PACKAGE__->table('authors');
	__PACKAGE__->add_columns(qw/authID first_name last_name/);
	__PACKAGE__->set_primary_key(qw/authID/);

	# Define relationship to the link table
	__PACKAGE__->has_many('b2a' => 'MyApp::DBIC::Book2Author', 'authID');

	# Create the accessor for books from the ::Author class
	sub books {
	  my ($self) = @_;
	  return MyApp::DBIC::Book->search(
		{ 'b2a.authID' => $self->authID }, # WHERE clause
		{ join => 'b2a' } # join condition (part of search attrs)
	    # '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.  
	  );
	}

	# define the link table class
	package MyApp::DBIC::Book2Author;
	use base qw/MyApp::DBIC/;

	__PACKAGE__->table('book2author');
	__PACKAGE__->add_columns(qw/bookID authID/);
	__PACKAGE__->set_primary_key(qw/bookID authID/);

	__PACKAGE__->belongs_to('authID' => 'MyApp::DBIC::Author');
	__PACKAGE__->belongs_to('bookID' => 'MyApp::DBIC::Book');

	package MyApp::DBIC::Book;
	use base qw/MyApp::DBIC/;

	__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 authors {
	 my ($self) = @_;
	 return MyApp::DBIC::Author->search(
	   { 'b2a.bookID' => $self->bookID }, # WHERE clause
	   { join => 'b2a' }); # join condition (part of search attrs)
	}

	# 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

=item Transactions

=back