From 910f7aab50321b2a8b347864782d8dc4f09915d8 Mon Sep 17 00:00:00 2001 From: Aditya Sanghi Date: Sat, 18 Feb 2012 11:38:30 +0530 Subject: Add a note about :dependent => :restrict on has_one and has_many's options --- railties/guides/source/association_basics.textile | 2 ++ 1 file changed, 2 insertions(+) (limited to 'railties/guides/source/association_basics.textile') diff --git a/railties/guides/source/association_basics.textile b/railties/guides/source/association_basics.textile index a55ed38d1b..a01c24bf74 100644 --- a/railties/guides/source/association_basics.textile +++ b/railties/guides/source/association_basics.textile @@ -899,6 +899,7 @@ end h6(#has_one-dependent). +:dependent+ 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+. +If you set the +:dependent+ option to +:restrict+, then the deletion of the object is restricted if a dependent associated object exist and an error is added to the base model. h6(#has_one-foreign_key). +:foreign_key+ @@ -1247,6 +1248,7 @@ NOTE: If you specify +:finder_sql+ but not +:counter_sql+, then the counter SQL h6(#has_many-dependent). +:dependent+ If you set the +:dependent+ option to +:destroy+, then deleting this object will call the +destroy+ method on the associated objects to delete those objects. If you set the +:dependent+ option to +:delete_all+, then deleting this object will delete the associated objects _without_ calling their +destroy+ method. If you set the +:dependent+ option to +:nullify+, then deleting this object will set the foreign key in the associated objects to +NULL+. +If you set the +:dependent+ option to +:restrict+, then the deletion of the object is restricted if any dependent associated objects exist and an error is added to the base model. NOTE: This option is ignored when you use the +:through+ option on the association. -- cgit v1.2.3 From abcaa9be82277f96e7ddeaf4e32e6efb39edec02 Mon Sep 17 00:00:00 2001 From: Aditya Sanghi Date: Sat, 18 Feb 2012 11:45:52 +0530 Subject: Add note about Rails 4.0 changes --- railties/guides/source/association_basics.textile | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'railties/guides/source/association_basics.textile') diff --git a/railties/guides/source/association_basics.textile b/railties/guides/source/association_basics.textile index a01c24bf74..76bf9d10d4 100644 --- a/railties/guides/source/association_basics.textile +++ b/railties/guides/source/association_basics.textile @@ -901,6 +901,8 @@ h6(#has_one-dependent). +:dependent+ 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+. If you set the +:dependent+ option to +:restrict+, then the deletion of the object is restricted if a dependent associated object exist and an error is added to the base model. +NOTE: Before Rails 4.0, using +:restrict+ with +:dependent: option used to raise a +DeleteRestrictionError+. This functionality has since been deprecated. If your code still depends on the exception being raised, then you should add the +:config.active_record.dependent_restrict_raises = true+ to your application config. + h6(#has_one-foreign_key). +:foreign_key+ 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: @@ -1252,6 +1254,8 @@ If you set the +:dependent+ option to +:restrict+, then the deletion of the obje NOTE: This option is ignored when you use the +:through+ option on the association. +NOTE: Before Rails 4.0, using +:restrict+ with +:dependent: option used to raise a +DeleteRestrictionError+. This functionality has since been deprecated. If your code still depends on the exception being raised, then you should add the +:config.active_record.dependent_restrict_raises = true+ to your application config. + h6(#has_many-extend). +:extend+ The +:extend+ option specifies a named module to extend the association proxy. Association extensions are discussed in detail later in this guide. -- cgit v1.2.3 From f49ec92866f6d8f27617b5723bff99ac0f7ca92f Mon Sep 17 00:00:00 2001 From: Aditya Sanghi Date: Sat, 18 Feb 2012 11:58:43 +0530 Subject: Do get it right this time. Fixing the documentation around :dependent => :restrict option --- railties/guides/source/association_basics.textile | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'railties/guides/source/association_basics.textile') diff --git a/railties/guides/source/association_basics.textile b/railties/guides/source/association_basics.textile index 76bf9d10d4..da4f965c79 100644 --- a/railties/guides/source/association_basics.textile +++ b/railties/guides/source/association_basics.textile @@ -899,9 +899,9 @@ end h6(#has_one-dependent). +:dependent+ 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+. -If you set the +:dependent+ option to +:restrict+, then the deletion of the object is restricted if a dependent associated object exist and an error is added to the base model. +If you set the +:dependent+ option to +:restrict+, then the deletion of the object is restricted if a dependent associated object exist and a +DeleteRestrictionError+ exception is raised. -NOTE: Before Rails 4.0, using +:restrict+ with +:dependent: option used to raise a +DeleteRestrictionError+. This functionality has since been deprecated. If your code still depends on the exception being raised, then you should add the +:config.active_record.dependent_restrict_raises = true+ to your application config. +NOTE: The default behavior for +:dependent => :restrict+ is to raise a +DeleteRestrictionError+ when associated objects exist. Since Rails 4.0 this behavior is being deprecated in favor of adding an error to the base model. To silence the warning in Rails 4.0, you should fix your code to not expect this Exception and add +:config.active_record.dependent_restrict_raises = false+ to you application config. h6(#has_one-foreign_key). +:foreign_key+ @@ -1250,11 +1250,11 @@ NOTE: If you specify +:finder_sql+ but not +:counter_sql+, then the counter SQL h6(#has_many-dependent). +:dependent+ If you set the +:dependent+ option to +:destroy+, then deleting this object will call the +destroy+ method on the associated objects to delete those objects. If you set the +:dependent+ option to +:delete_all+, then deleting this object will delete the associated objects _without_ calling their +destroy+ method. If you set the +:dependent+ option to +:nullify+, then deleting this object will set the foreign key in the associated objects to +NULL+. -If you set the +:dependent+ option to +:restrict+, then the deletion of the object is restricted if any dependent associated objects exist and an error is added to the base model. +If you set the +:dependent+ option to +:restrict+, then the deletion of the object is restricted if a dependent associated object exist and a +DeleteRestrictionError+ exception is raised. -NOTE: This option is ignored when you use the +:through+ option on the association. +NOTE: The default behavior for +:dependent => :restrict+ is to raise a +DeleteRestrictionError+ when associated objects exist. Since Rails 4.0 this behavior is being deprecated in favor of adding an error to the base model. To silence the warning in Rails 4.0, you should fix your code to not expect this Exception and add +:config.active_record.dependent_restrict_raises = false+ to you application config. -NOTE: Before Rails 4.0, using +:restrict+ with +:dependent: option used to raise a +DeleteRestrictionError+. This functionality has since been deprecated. If your code still depends on the exception being raised, then you should add the +:config.active_record.dependent_restrict_raises = true+ to your application config. +NOTE: This option is ignored when you use the +:through+ option on the association. h6(#has_many-extend). +:extend+ -- cgit v1.2.3 From 1cb6417a8574848b4df96b8c7b7757a0eb65bef4 Mon Sep 17 00:00:00 2001 From: Mike Gunderloy Date: Sat, 18 Feb 2012 05:58:52 -0600 Subject: Documenting the :inverse_of option for associations --- railties/guides/source/association_basics.textile | 99 +++++++++++++++++++++++ 1 file changed, 99 insertions(+) (limited to 'railties/guides/source/association_basics.textile') diff --git a/railties/guides/source/association_basics.textile b/railties/guides/source/association_basics.textile index da4f965c79..9a69ec45f7 100644 --- a/railties/guides/source/association_basics.textile +++ b/railties/guides/source/association_basics.textile @@ -358,6 +358,7 @@ Here are a few things you should know to make efficient use of Active Record ass * Avoiding name collisions * Updating the schema * Controlling association scope +* Bi-drectional associations h4. Controlling Caching @@ -501,6 +502,59 @@ module MyApplication end +h4. Bi-directional Associations + +It's normal for associations to work in two directions, requiring declaration on two different models: + + +class Customer < ActiveRecord::Base + has_many :orders +end + +class Order < ActiveRecord::Base + belongs_to :customer +end + + +By default, Active Record doesn't know about the connection between these associations. This can lead to two copies of an object getting out of sync: + + +c = Customer.first +o = c.orders.first +c.first_name == o.customer.first_name # => true +c.first_name = 'Manny' +c.first_name == o.customer.first_name # => false + + +This happens because c and o.customer are two different in-memory representations of the same data, and neither one is automatically refreshed from changes to the other. Active Record provides the +:inverse_of+ option so that you can inform it of these relations: + + +class Customer < ActiveRecord::Base + has_many :orders, :inverse_of => :customer +end + +class Order < ActiveRecord::Base + belongs_to :customer, :inverse_of => :orders +end + + +With these changes, Active Record will only load one copy of the customer object, preventing inconsistencies and making your application more efficient: + + +c = Customer.first +o = c.orders.first +c.first_name == o.customer.first_name # => true +c.first_name = 'Manny' +c.first_name == o.customer.first_name # => true + + +There are a few limitations to +inverse_of+ support: + +* They do not work with :through associations. +* They do not work with :polymorphic associations. +* They do not work with :as associations. +* For +belongs_to+ associations, +has_many+ inverse associations are ignored. + h3. Detailed Association Reference The following sections give the details of each type of association, including the methods that they add and the options that you can use when declaring an association. @@ -594,6 +648,7 @@ The +belongs_to+ association supports these options: * +:dependent+ * +:foreign_key+ * +:include+ +* +:inverse_of+ * +:polymorphic+ * +:readonly+ * +:select+ @@ -720,6 +775,20 @@ end NOTE: There's no need to use +:include+ for immediate associations - that is, if you have +Order belongs_to :customer+, then the customer is eager-loaded automatically when it's needed. +h6(#belongs_to-inverse_of). +:inverse_of+ + +The +:inverse_of+ option specifies the name of the +has_many+ or +has_one+ association that is the inverse of this association. Does not work in combination with the +:polymorphic+ options. + + +class Customer < ActiveRecord::Base + has_many :orders, :inverse_of => :customer +end + +class Order < ActiveRecord::Base + belongs_to :customer, :inverse_of => :orders +end + + h6(#belongs_to-polymorphic). +:polymorphic+ Passing +true+ to the +:polymorphic+ option indicates that this is a polymorphic association. Polymorphic associations were discussed in detail earlier in this guide. @@ -859,6 +928,7 @@ The +has_one+ association supports these options: * +:dependent+ * +:foreign_key+ * +:include+ +* +:inverse_of+ * +:order+ * +:primary_key+ * +:readonly+ @@ -951,6 +1021,20 @@ class Representative < ActiveRecord::Base end +h6(#has_one-inverse_of). +:inverse_of+ + +The +:inverse_of+ option specifies the name of the +belongs_to+ association that is the inverse of this association. Does not work in combination with the +:through+ or +:as+ options. + + +class Supplier < ActiveRecord::Base + has_one :account, :inverse_of => :supplier +end + +class Account < ActiveRecord::Base + belongs_to :supplier, :inverse_of => :account +end + + h6(#has_one-order). +:order+ 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. @@ -1180,6 +1264,7 @@ The +has_many+ association supports these options: * +:foreign_key+ * +:group+ * +:include+ +* +:inverse_of+ * +:limit+ * +:offset+ * +:order+ @@ -1322,6 +1407,20 @@ class LineItem < ActiveRecord::Base end +h6(#has_many-inverse_of). +:inverse_of+ + +The +:inverse_of+ option specifies the name of the +belongs_to+ association that is the inverse of this association. Does not work in combination with the +:through+ or +:as+ options. + + +class Customer < ActiveRecord::Base + has_many :orders, :inverse_of => :customer +end + +class Order < ActiveRecord::Base + belongs_to :customer, :inverse_of => :orders +end + + h6(#has_many-limit). +:limit+ The +:limit+ option lets you restrict the total number of objects that will be fetched through an association. -- cgit v1.2.3 From 709f33d6042463bd4dbfb16f6f8946785556d5ab Mon Sep 17 00:00:00 2001 From: Vijay Dev Date: Sat, 18 Feb 2012 21:58:33 +0530 Subject: fix some typos [ci skip] --- railties/guides/source/association_basics.textile | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'railties/guides/source/association_basics.textile') diff --git a/railties/guides/source/association_basics.textile b/railties/guides/source/association_basics.textile index 9a69ec45f7..ba92aedbd0 100644 --- a/railties/guides/source/association_basics.textile +++ b/railties/guides/source/association_basics.textile @@ -358,7 +358,7 @@ Here are a few things you should know to make efficient use of Active Record ass * Avoiding name collisions * Updating the schema * Controlling association scope -* Bi-drectional associations +* Bi-directional associations h4. Controlling Caching @@ -971,7 +971,7 @@ h6(#has_one-dependent). +:dependent+ 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+. If you set the +:dependent+ option to +:restrict+, then the deletion of the object is restricted if a dependent associated object exist and a +DeleteRestrictionError+ exception is raised. -NOTE: The default behavior for +:dependent => :restrict+ is to raise a +DeleteRestrictionError+ when associated objects exist. Since Rails 4.0 this behavior is being deprecated in favor of adding an error to the base model. To silence the warning in Rails 4.0, you should fix your code to not expect this Exception and add +:config.active_record.dependent_restrict_raises = false+ to you application config. +NOTE: The default behavior for +:dependent => :restrict+ is to raise a +DeleteRestrictionError+ when associated objects exist. Since Rails 4.0 this behavior is being deprecated in favor of adding an error to the base model. To silence the warning in Rails 4.0, you should fix your code to not expect this Exception and add +config.active_record.dependent_restrict_raises = false+ to your application config. h6(#has_one-foreign_key). +:foreign_key+ @@ -1337,7 +1337,7 @@ h6(#has_many-dependent). +:dependent+ If you set the +:dependent+ option to +:destroy+, then deleting this object will call the +destroy+ method on the associated objects to delete those objects. If you set the +:dependent+ option to +:delete_all+, then deleting this object will delete the associated objects _without_ calling their +destroy+ method. If you set the +:dependent+ option to +:nullify+, then deleting this object will set the foreign key in the associated objects to +NULL+. If you set the +:dependent+ option to +:restrict+, then the deletion of the object is restricted if a dependent associated object exist and a +DeleteRestrictionError+ exception is raised. -NOTE: The default behavior for +:dependent => :restrict+ is to raise a +DeleteRestrictionError+ when associated objects exist. Since Rails 4.0 this behavior is being deprecated in favor of adding an error to the base model. To silence the warning in Rails 4.0, you should fix your code to not expect this Exception and add +:config.active_record.dependent_restrict_raises = false+ to you application config. +NOTE: The default behavior for +:dependent => :restrict+ is to raise a +DeleteRestrictionError+ when associated objects exist. Since Rails 4.0 this behavior is being deprecated in favor of adding an error to the base model. To silence the warning in Rails 4.0, you should fix your code to not expect this Exception and add +config.active_record.dependent_restrict_raises = false+ to your application config. NOTE: This option is ignored when you use the +:through+ option on the association. -- cgit v1.2.3