guides/source/association_basics.textile in railties-3.1.12 vs guides/source/association_basics.textile in railties-3.2.0.rc1

@@ -209,11 +209,11 @@
 
 !images/habtm.png(has_and_belongs_to_many Association Diagram)!
 
 h4. Choosing Between +belongs_to+ and +has_one+
 
-If you want to set up a 1–1 relationship between two models, you'll need to add +belongs_to+ to one, and +has_one+ to the other. How do you know which is which?
+If you want to set up a one-to-one relationship between two models, you'll need to add +belongs_to+ to one, and +has_one+ to the other. How do you know which is which?
 
 The distinction is in where you place the foreign key (it goes on the table for the class declaring the +belongs_to+ association), but you should give some thought to the actual meaning of the data as well. The +has_one+ relationship says that one of something is yours - that is, that something points back to you. For example, it makes more sense to say that a supplier owns an account than that an account owns a supplier. This suggests that the correct relationships are like this:
 
 <ruby>
 class Supplier < ActiveRecord::Base
@@ -564,21 +564,21 @@
   :customer_name => "John Doe")
 </ruby>
 
 h6(#belongs_to-create_association). <tt>create_<em>association</em>(attributes = {})</tt>
 
-The <tt>create_<em>association</em></tt> method returns a new object of the associated type. This object will be instantiated from the passed attributes, and the link through this object's foreign key will be set. In addition, the associated object _will_ be saved (assuming that it passes any validations).
+The <tt>create_<em>association</em></tt> method returns a new object of the associated type. This object will be instantiated from the passed attributes, the link through this object's foreign key will be set, and, once it passes all of the validations specified on the associated model, the associated object _will_ be saved.
 
 <ruby>
 @customer = @order.create_customer(:customer_number => 123,
   :customer_name => "John Doe")
 </ruby>
 
 
 h5. Options for +belongs_to+
 
-In many situations, you can use the default behavior of +belongs_to+ without any customization. But despite Rails' emphasis of convention over customization, you can alter that behavior in a number of ways. This section covers the options that you can pass when you create a +belongs_to+ association. For example, an association with several options might look like this:
+While Rails uses intelligent defaults that will work well in most situations, there may be times when you want to customize the behavior of the +belongs_to+ association reference. Such customizations can easily be accomplished by passing options when you create the association. For example, this assocation uses two such options:
 
 <ruby>
 class Order < ActiveRecord::Base
   belongs_to :customer, :counter_cache => true,
     :conditions => "active = 1"
@@ -669,11 +669,11 @@
 
 WARNING: You should not specify this option on a +belongs_to+ association that is connected with a +has_many+ association on the other class. Doing so can lead to orphaned records in your database.
 
 h6(#belongs_to-foreign_key). +:foreign_key+
 
-By convention, Rails guesses that the column used to hold the foreign key on this model is the name of the association with the suffix +_id+ added. The +:foreign_key+ option lets you set the name of the foreign key directly:
+By convention, Rails assumes that the column used to hold the foreign key on this model is the name of the association with the suffix +_id+ added. The +:foreign_key+ option lets you set the name of the foreign key directly:
 
 <ruby>
 class Order < ActiveRecord::Base
   belongs_to :customer, :class_name => "Patron",
     :foreign_key => "patron_id"
@@ -758,13 +758,13 @@
 
 h6(#belongs_to-validate). +:validate+
 
 If you set the +:validate+ option to +true+, then associated objects will be validated whenever you save this object. By default, this is +false+: associated objects will not be validated when this object is saved.
 
-h5(#belongs_to-how_to_know_whether_theres_an_associated_object). How To Know Whether There's an Associated Object?
+h5(#belongs_to-do_any_associated_objects_exist). Do Any Associated Objects Exist?
 
-To know whether there's and associated object just check <tt><em>association</em>.nil?</tt>:
+You can see if any associated objects exist by using the <tt><em>association</em>.nil?</tt> method:
 
 <ruby>
 if @order.customer.nil?
   @msg = "No customer found for this order"
 end
@@ -832,19 +832,19 @@
 @account = @supplier.build_account(:terms => "Net 30")
 </ruby>
 
 h6(#has_one-create_association). <tt>create_<em>association</em>(attributes = {})</tt>
 
-The <tt>create_<em>association</em></tt> method returns a new object of the associated type. This object will be instantiated from the passed attributes, and the link through its foreign key will be set. In addition, the associated object _will_ be saved (assuming that it passes any validations).
+The <tt>create_<em>association</em></tt> method returns a new object of the associated type. This object will be instantiated from the passed attributes, the link through its foreign key will be set, and, once it passes all of the validations specified on the associated model, the associated object _will_ be saved.
 
 <ruby>
 @account = @supplier.create_account(:terms => "Net 30")
 </ruby>
 
 h5. Options for +has_one+
 
-In many situations, you can use the default behavior of +has_one+ without any customization. But despite Rails' emphasis of convention over customization, you can alter that behavior in a number of ways. This section covers the options that you can pass when you create a +has_one+ association. For example, an association with several options might look like this:
+While Rails uses intelligent defaults that will work well in most situations, there may be times when you want to customize the behavior of the +has_one+ association reference. Such customizations can easily be accomplished by passing options when you create the association. For example, this assocation uses two such options:
 
 <ruby>
 class Supplier < ActiveRecord::Base
   has_one :account, :class_name => "Billing", :dependent => :nullify
 end
@@ -900,11 +900,11 @@
 
 If you set the +:dependent+ option to +:destroy+, then deleting this object will call the +destroy+ method on the associated object to delete that object. If you set the +:dependent+ option to +:delete+, then deleting this object will delete the associated object _without_ calling its +destroy+ method. If you set the +:dependent+ option to +:nullify+, then deleting this object will set the foreign key in the association object to +NULL+.
 
 h6(#has_one-foreign_key). +:foreign_key+
 
-By convention, Rails guesses that the column used to hold the foreign key on the other model is the name of this model with the suffix +_id+ added. The +:foreign_key+ option lets you set the name of the foreign key directly:
+By convention, Rails assumes that the column used to hold the foreign key on the other model is the name of this model with the suffix +_id+ added. The +:foreign_key+ option lets you set the name of the foreign key directly:
 
 <ruby>
 class Supplier < ActiveRecord::Base
   has_one :account, :foreign_key => "supp_id"
 end
@@ -952,11 +952,11 @@
 
 The +:order+ option dictates the order in which associated objects will be received (in the syntax used by an SQL +ORDER BY+ clause). Because a +has_one+ association will only retrieve a single associated object, this option should not be needed.
 
 h6(#has_one-primary_key). +:primary_key+
 
-By convention, Rails guesses that the column used to hold the primary key of this model is +id+. You can override this and explicitly specify the primary key with the +:primary_key+ option.
+By convention, Rails assumes that the column used to hold the primary key of this model is +id+. You can override this and explicitly specify the primary key with the +:primary_key+ option.
 
 h6(#has_one-readonly). +:readonly+
 
 If you set the +:readonly+ option to +true+, then the associated object will be read-only when retrieved via the association.
 
@@ -978,13 +978,13 @@
 
 h6(#has_one-validate). +:validate+
 
 If you set the +:validate+ option to +true+, then associated objects will be validated whenever you save this object. By default, this is +false+: associated objects will not be validated when this object is saved.
 
-h5(#has_one-how_to_know_whether_theres_an_associated_object). How To Know Whether There's an Associated Object?
+h5(#has_one-do_any_associated_objects_exist). Do Any Associated Objects Exist?
 
-To know whether there's and associated object just check <tt><em>association</em>.nil?</tt>:
+You can see if any associated objects exist by using the <tt><em>association</em>.nil?</tt> method:
 
 <ruby>
 if @supplier.account.nil?
   @msg = "No account found for this supplier"
 end
@@ -1145,20 +1145,20 @@
   :order_number => "A12345")
 </ruby>
 
 h6(#has_many-collection-create). <tt><em>collection</em>.create(attributes = {})</tt>
 
-The <tt><em>collection</em>.create</tt> method returns a new object of the associated type. This object will be instantiated from the passed attributes, the link through its foreign key will be created, and the associated object _will_ be saved (assuming that it passes any validations).
+The <tt><em>collection</em>.create</tt> method returns a new object of the associated type. This object will be instantiated from the passed attributes, the link through its foreign key will be created, and, once it passes all of the validations specified on the associated model, the associated object _will_ be saved.
 
 <ruby>
 @order = @customer.orders.create(:order_date => Time.now,
   :order_number => "A12345")
 </ruby>
 
 h5. Options for +has_many+
 
-In many situations, you can use the default behavior for +has_many+ without any customization. But you can alter that behavior in a number of ways. This section covers the options that you can pass when you create a +has_many+ association. For example, an association with several options might look like this:
+While Rails uses intelligent defaults that will work well in most situations, there may be times when you want to customize the behavior of the +has_many+ association reference. Such customizations can easily be accomplished by passing options when you create the association. For example, this assocation uses two such options:
 
 <ruby>
 class Customer < ActiveRecord::Base
   has_many :orders, :dependent => :delete_all, :validate => :false
 end
@@ -1258,11 +1258,11 @@
 
 Normally Rails automatically generates the proper SQL to fetch the association members. With the +:finder_sql+ option, you can specify a complete SQL statement to fetch them yourself. If fetching objects requires complex multi-table SQL, this may be necessary.
 
 h6(#has_many-foreign_key). +:foreign_key+
 
-By convention, Rails guesses that the column used to hold the foreign key on the other model is the name of this model with the suffix +_id+ added. The +:foreign_key+ option lets you set the name of the foreign key directly:
+By convention, Rails assumes that the column used to hold the foreign key on the other model is the name of this model with the suffix +_id+ added. The +:foreign_key+ option lets you set the name of the foreign key directly:
 
 <ruby>
 class Customer < ActiveRecord::Base
   has_many :orders, :foreign_key => "cust_id"
 end
@@ -1341,11 +1341,11 @@
 end
 </ruby>
 
 h6(#has_many-primary_key). +:primary_key+
 
-By convention, Rails guesses that the column used to hold the primary key of the association is +id+. You can override this and explicitly specify the primary key with the +:primary_key+ option.
+By convention, Rails assumes that the column used to hold the primary key of the association is +id+. You can override this and explicitly specify the primary key with the +:primary_key+ option.
 
 h6(#has_many-readonly). +:readonly+
 
 If you set the +:readonly+ option to +true+, then the associated objects will be read-only when retrieved via the association.
 
@@ -1547,11 +1547,11 @@
 <ruby>
 @new_assemblies = @part.assemblies.all(
   :conditions => ["created_at > ?", 2.days.ago])
 </ruby>
 
-NOTE: Starting Rails 3, supplying options to +ActiveRecord::Base.find+ method is discouraged. Use <tt><em>collection</em>.where</tt> instead when you need to pass conditions.
+NOTE: Beginning with Rails 3, supplying options to the +ActiveRecord::Base.find+ method is discouraged. Use <tt><em>collection</em>.where</tt> instead when you need to pass conditions.
 
 h6(#has_and_belongs_to_many-collection-where). <tt><em>collection</em>.where(...)</tt>
 
 The <tt><em>collection</em>.where</tt> method finds objects within the collection based on the conditions supplied but the objects are loaded lazily meaning that the database is queried only when the object(s) are accessed. It also adds the additional condition that the object must be in the collection.
 
@@ -1572,20 +1572,20 @@
   {:assembly_name => "Transmission housing"})
 </ruby>
 
 h6(#has_and_belongs_to_many-create-attributes). <tt><em>collection</em>.create(attributes = {})</tt>
 
-The <tt><em>collection</em>.create</tt> method returns a new object of the associated type. This object will be instantiated from the passed attributes, the link through the join table will be created, and the associated object _will_ be saved (assuming that it passes any validations).
+The <tt><em>collection</em>.create</tt> method returns a new object of the associated type. This object will be instantiated from the passed attributes, the link through the join table will be created, and, once it passes all of the validations specified on the associated model, the associated object _will_ be saved.
 
 <ruby>
 @assembly = @part.assemblies.create(
   {:assembly_name => "Transmission housing"})
 </ruby>
 
 h5. Options for +has_and_belongs_to_many+
 
-In many situations, you can use the default behavior for +has_and_belongs_to_many+ without any customization. But you can alter that behavior in a number of ways. This section covers the options that you can pass when you create a +has_and_belongs_to_many+ association. For example, an association with several options might look like this:
+While Rails uses intelligent defaults that will work well in most situations, there may be times when you want to customize the behavior of the +has_and_belongs_to_many+ association reference. Such customizations can easily be accomplished by passing options when you create the association. For example, this assocation uses two such options:
 
 <ruby>
 class Parts < ActiveRecord::Base
   has_and_belongs_to_many :assemblies, :uniq => true,
     :read_only => true
@@ -1615,11 +1615,11 @@
 * +:uniq+
 * +:validate+
 
 h6(#has_and_belongs_to_many-association_foreign_key). +:association_foreign_key+
 
-By convention, Rails guesses that the column in the join table used to hold the foreign key pointing to the other model is the name of that model with the suffix +_id+ added. The +:association_foreign_key+ option lets you set the name of the foreign key directly:
+By convention, Rails assumes that the column in the join table used to hold the foreign key pointing to the other model is the name of that model with the suffix +_id+ added. The +:association_foreign_key+ option lets you set the name of the foreign key directly:
 
 TIP: The +:foreign_key+ and +:association_foreign_key+ options are useful when setting up a many-to-many self-join. For example:
 
 <ruby>
 class User < ActiveRecord::Base
@@ -1683,11 +1683,11 @@
 
 Normally Rails automatically generates the proper SQL to fetch the association members. With the +:finder_sql+ option, you can specify a complete SQL statement to fetch them yourself. If fetching objects requires complex multi-table SQL, this may be necessary.
 
 h6(#has_and_belongs_to_many-foreign_key). +:foreign_key+
 
-By convention, Rails guesses that the column in the join table used to hold the foreign key pointing to this model is the name of this model with the suffix +_id+ added. The +:foreign_key+ option lets you set the name of the foreign key directly:
+By convention, Rails assumes that the column in the join table used to hold the foreign key pointing to this model is the name of this model with the suffix +_id+ added. The +:foreign_key+ option lets you set the name of the foreign key directly:
 
 <ruby>
 class User < ActiveRecord::Base
   has_and_belongs_to_many :friends, :class_name => "User",
     :foreign_key => "this_user_id",
@@ -1851,19 +1851,10 @@
   has_many :orders,
     :extend => [FindRecentExtension, FindActiveExtension]
 end
 </ruby>
 
-Extensions can refer to the internals of the association proxy using these three accessors:
+Extensions can refer to the internals of the association proxy using these three attributes of the +proxy_association+ accessor:
 
-* +proxy_owner+ returns the object that the association is a part of.
-* +proxy_reflection+ returns the reflection object that describes the association.
-* +proxy_target+ returns the associated object for +belongs_to+ or +has_one+, or the collection of associated objects for +has_many+ or +has_and_belongs_to_many+.
-
-h3. Changelog
-
-* April 7, 2010: Fixed document to validate XHTML 1.0 Strict. "Jaime Iniesta":http://jaimeiniesta.com
-* April 19, 2009: Added +:touch+ option to +belongs_to+ associations by "Mike Gunderloy":credits.html#mgunderloy
-* February 1, 2009: Added +:autosave+ option "Mike Gunderloy":credits.html#mgunderloy
-* September 28, 2008: Corrected +has_many :through+ diagram, added polymorphic diagram, some reorganization by "Mike Gunderloy":credits.html#mgunderloy . First release version.
-* September 22, 2008: Added diagrams, misc. cleanup by "Mike Gunderloy":credits.html#mgunderloy (not yet approved for publication)
-* September 14, 2008: initial version by "Mike Gunderloy":credits.html#mgunderloy (not yet approved for publication)
+* +proxy_association.owner+ returns the object that the association is a part of.
+* +proxy_association.reflection+ returns the reflection object that describes the association.
+* +proxy_association.target+ returns the associated object for +belongs_to+ or +has_one+, or the collection of associated objects for +has_many+ or +has_and_belongs_to_many+.