From 51d840e272941023ad62d021fa2b4a491fe9953a Mon Sep 17 00:00:00 2001 From: Michael Koziarski Date: Mon, 15 Jan 2007 06:43:47 +0000 Subject: Improve association documentation, closes #7022. [hasmanyjosh] git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@5939 5ecf4fe2-1ee6-0310-87b1-e25e094e27de --- activerecord/lib/active_record/associations.rb | 66 +++++++++++++++++++++++++- 1 file changed, 65 insertions(+), 1 deletion(-) (limited to 'activerecord/lib') diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb index 56086693d2..f1c274af42 100755 --- a/activerecord/lib/active_record/associations.rb +++ b/activerecord/lib/active_record/associations.rb @@ -93,7 +93,71 @@ module ActiveRecord # # link:files/examples/associations.png # - # == Is it belongs_to or has_one? + # == Cardinality and associations + # + # ActiveRecord associations can be used to describe relations with one-to-one, one-to-many + # and many-to-many cardinality. Each model uses an association to describe its role in + # the relation. In each case, the belongs_to association is used in the model that has + # the foreign key + # + # === One-to-one + # + # Use has_one in the base, and belongs_to in the associated model. + # + # class Employee < ActiveRecord::Base + # has_one :office + # end + # class Office < ActiveRecord::Base + # belongs_to :employee # foreign key - employee_id + # end + # + # === One-to-many + # + # Use has_many in the base, and belongs_to in the associated model. + # + # class Manager < ActiveRecord::Base + # has_many :employees + # end + # class Employee < ActiveRecord::Base + # belongs_to :manager # foreign key - employee_id + # end + # + # === Many-to-many + # + # There are two ways to build a many-to-many relationship. + # + # The first way uses a has_many association with the :through option and a join model, so + # there are two stages of associations. + # + # class Assignment < ActiveRecord::Base + # belongs_to :programmer # foreign key - programmer_id + # belongs_to :project # foreign key - project_id + # end + # class Programmer < ActiveRecord::Base + # has_many :assignments + # has_many :projects, :through => :assignments + # end + # class Project < ActiveRecord::Base + # has_many :assignments + # has_many :programmers, :through => :assignments + # end + # + # For the second way, use has_and_belongs_to_many in both models. This requires a join table + # that has no corresponding model or primary key. + # + # class Programmer < ActiveRecord::Base + # has_and_belongs_to_many :projects # foreign keys in the join table + # end + # class Project < ActiveRecord::Base + # has_and_belongs_to_many :programmers # foreign keys in the join table + # end + # + # It is not always a simple decision which way of building a many-to-many relationship is best. + # But if you need to work with the relationship model as its own entity, then you'll need to + # use has_many :through. Use has_and_belongs_to_many when working with legacy schemas or when + # you never work directly with the relationship itself. + # + # == Is it a belongs_to or has_one association? # # Both express a 1-1 relationship, the difference is mostly where to place the foreign key, which goes on the table for the class # saying belongs_to. Example: -- cgit v1.2.3