From 20f7c767e5e1b6ca6619cd078be10406164efd56 Mon Sep 17 00:00:00 2001 From: Jon Atack Date: Thu, 17 Jul 2014 11:36:17 +0200 Subject: Grammar pass [ci skip] Add improvements from @eileencodes [skip ci] --- activerecord/lib/active_record/associations.rb | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) (limited to 'activerecord/lib/active_record/associations.rb') diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb index 7ec7eb1b24..6ac457a2cd 100644 --- a/activerecord/lib/active_record/associations.rb +++ b/activerecord/lib/active_record/associations.rb @@ -447,9 +447,11 @@ module ActiveRecord # # Possible callbacks are: +before_add+, +after_add+, +before_remove+ and +after_remove+. # - # Should any of the +before_add+ callbacks throw an exception, the object does not get - # added to the collection. Same with the +before_remove+ callbacks; if an exception is - # thrown the object doesn't get removed. + # If any of the +before_add+ callbacks throw an exception, the object will not be + # added to the collection. + # + # Similarly, if any of the +before_remove+ callbacks throw an exception, the object + # will not be removed from the collection. # # == Association extensions # @@ -647,7 +649,7 @@ module ActiveRecord # belongs_to :commenter # end # - # When using nested association, you will not be able to modify the association because there + # When using a nested association, you will not be able to modify the association because there # is not enough information to know what modification to make. For example, if you tried to # add a Commenter in the example above, there would be no way to tell how to set up the # intermediate Post and Comment objects. @@ -717,7 +719,7 @@ module ActiveRecord # == Eager loading of associations # # Eager loading is a way to find objects of a certain class and a number of named associations. - # This is one of the easiest ways of to prevent the dreaded N+1 problem in which fetching 100 + # It is one of the easiest ways to prevent the dreaded N+1 problem in which fetching 100 # posts that each need to display their author triggers 101 database queries. Through the # use of eager loading, the number of queries will be reduced from 101 to 2. # @@ -749,16 +751,16 @@ module ActiveRecord # Post.includes(:author, :comments).each do |post| # # This will load all comments with a single query. This reduces the total number of queries - # to 3. More generally the number of queries will be 1 plus the number of associations + # to 3. In general, the number of queries will be 1 plus the number of associations # named (except if some of the associations are polymorphic +belongs_to+ - see below). # # To include a deep hierarchy of associations, use a hash: # - # Post.includes(:author, {comments: {author: :gravatar}}).each do |post| + # Post.includes(:author, { comments: { author: :gravatar } }).each do |post| # - # That'll grab not only all the comments but all their authors and gravatar pictures. - # You can mix and match symbols, arrays and hashes in any combination to describe the - # associations you want to load. + # The above code will load all the comments and all of their associated + # authors and gravatars. You can mix and match any combination of symbols, + # arrays, and hashes to retrieve the associations you want to load. # # All of this power shouldn't fool you into thinking that you can pull out huge amounts # of data with no performance penalty just because you've reduced the number of queries. @@ -767,8 +769,8 @@ module ActiveRecord # cut down on the number of queries in a situation as the one described above. # # Since only one table is loaded at a time, conditions or orders cannot reference tables - # other than the main one. If this is the case Active Record falls back to the previously - # used LEFT OUTER JOIN based strategy. For example + # other than the main one. If this is the case, Active Record falls back to the previously + # used LEFT OUTER JOIN based strategy. For example: # # Post.includes([:author, :comments]).where(['comments.approved = ?', true]) # -- cgit v1.2.3 From b64cfac9318b09cb6acbc31bdfd309d2e28f86d0 Mon Sep 17 00:00:00 2001 From: Tom Kadwill Date: Wed, 20 Aug 2014 07:58:59 +0100 Subject: [ci skip] Added documentation for has_many scope parameter --- activerecord/lib/active_record/associations.rb | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'activerecord/lib/active_record/associations.rb') diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb index 945f22d3c8..114e327926 100644 --- a/activerecord/lib/active_record/associations.rb +++ b/activerecord/lib/active_record/associations.rb @@ -1133,6 +1133,17 @@ module ActiveRecord # * Firm#clients.create! (similar to c = Client.new("firm_id" => id); c.save!) # The declaration can also include an +options+ hash to specialize the behavior of the association. # + # === Scopes + # + # You can pass a second argument +scope+ as a callable (i.e. proc or + # lambda) to retrieve a specific set of records or customize the generated + # query when you access the associated collection. + # + # Scope examples: + # has_many :comments, -> { where(author_id: 1) } + # has_many :employees, -> { joins(:address) } + # has_many :posts, ->(post) { where("max_post_length > ?", post.length) } + # # === Options # [:class_name] # Specify the class name of the association. Use it only if that name can't be inferred -- cgit v1.2.3 From af3b2c4addb275e4829df225d7015decfa14a4e6 Mon Sep 17 00:00:00 2001 From: Tom Kadwill Date: Thu, 21 Aug 2014 17:51:47 +0100 Subject: [ci skip] Added documentation for has_one scope parameter --- activerecord/lib/active_record/associations.rb | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'activerecord/lib/active_record/associations.rb') diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb index 114e327926..02114fd4d6 100644 --- a/activerecord/lib/active_record/associations.rb +++ b/activerecord/lib/active_record/associations.rb @@ -1268,6 +1268,17 @@ module ActiveRecord # * Account#create_beneficiary (similar to b = Beneficiary.new("account_id" => id); b.save; b) # * Account#create_beneficiary! (similar to b = Beneficiary.new("account_id" => id); b.save!; b) # + # === Scopes + # + # You can pass a second argument +scope+ as a callable (i.e. proc or + # lambda) to retrieve a specific record or customize the generated query + # when you access the associated object. + # + # Scope examples: + # has_one :auther, -> { where(comment_id: 1) } + # has_one :employer, -> { joins(:company) } + # has_one :dob, ->(dob) { where("Date.new(2000, 01, 01) > ?", dob) } + # # === Options # # The declaration can also include an +options+ hash to specialize the behavior of the association. -- cgit v1.2.3 From 525cbd4c2f1257f131e38caaecf01c7674b1130a Mon Sep 17 00:00:00 2001 From: Tom Kadwill Date: Fri, 22 Aug 2014 08:07:07 +0100 Subject: [ci skip] Added documentation for has_and_belongs_to_many scope parameter --- activerecord/lib/active_record/associations.rb | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'activerecord/lib/active_record/associations.rb') diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb index fb8cf1cecc..4ec1c8d545 100644 --- a/activerecord/lib/active_record/associations.rb +++ b/activerecord/lib/active_record/associations.rb @@ -1578,6 +1578,18 @@ module ActiveRecord # * Developer#projects.create (similar to c = Project.new("developer_id" => id); c.save; c) # The declaration may include an +options+ hash to specialize the behavior of the association. # + # === Scopes + # + # You can pass a second argument +scope+ as a callable (i.e. proc or + # lambda) to retrieve a specific set of records or customize the generated + # query when you access the associated collection. + # + # Scope examples: + # has_and_belongs_to_many :projects, -> { includes :milestones, :manager } + # has_and_belongs_to_many :categories, ->(category) { + # where("default_category = ?", category.name) + # } + # # === Options # # [:class_name] -- cgit v1.2.3 From a5ae5fc85161c26741e64273fd1620a7a8f4d296 Mon Sep 17 00:00:00 2001 From: Tom Kadwill Date: Sun, 24 Aug 2014 17:03:57 +0100 Subject: [ci skip] Added documentation for has_many extension parameter --- activerecord/lib/active_record/associations.rb | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'activerecord/lib/active_record/associations.rb') diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb index 4ec1c8d545..54390e612f 100644 --- a/activerecord/lib/active_record/associations.rb +++ b/activerecord/lib/active_record/associations.rb @@ -1146,6 +1146,20 @@ module ActiveRecord # has_many :employees, -> { joins(:address) } # has_many :posts, ->(post) { where("max_post_length > ?", post.length) } # + # === Extensions + # + # The +extension+ argument allows you to pass a block into a has_many + # association. This is useful for adding new finders, creators and other + # factory-type methods to be used as part of the association. + # + # Extension examples: + # has_many :employees do + # def find_or_create_by_name(name) + # first_name, last_name = name.split(" ", 2) + # find_or_create_by(first_name: first_name, last_name: last_name) + # end + # end + # # === Options # [:class_name] # Specify the class name of the association. Use it only if that name can't be inferred -- cgit v1.2.3 From f3b8a0d375fe441d70b9c77bd9c20347c71a70cb Mon Sep 17 00:00:00 2001 From: Robin Dupret Date: Sun, 24 Aug 2014 18:33:59 +0200 Subject: Fix a few typos [ci skip] --- activerecord/lib/active_record/associations.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'activerecord/lib/active_record/associations.rb') diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb index 54390e612f..18d4291599 100644 --- a/activerecord/lib/active_record/associations.rb +++ b/activerecord/lib/active_record/associations.rb @@ -1291,7 +1291,7 @@ module ActiveRecord # when you access the associated object. # # Scope examples: - # has_one :auther, -> { where(comment_id: 1) } + # has_one :author, -> { where(comment_id: 1) } # has_one :employer, -> { joins(:company) } # has_one :dob, ->(dob) { where("Date.new(2000, 01, 01) > ?", dob) } # -- cgit v1.2.3 From 64d3b5edd11f5d96d4ac3393247d04c9e225878f Mon Sep 17 00:00:00 2001 From: Tom Kadwill Date: Tue, 26 Aug 2014 07:49:37 +0100 Subject: [ci skip] Added documentation for has_and_belongs_to_many extension parameter --- activerecord/lib/active_record/associations.rb | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'activerecord/lib/active_record/associations.rb') diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb index 18d4291599..18da28d480 100644 --- a/activerecord/lib/active_record/associations.rb +++ b/activerecord/lib/active_record/associations.rb @@ -1604,6 +1604,21 @@ module ActiveRecord # where("default_category = ?", category.name) # } # + # === Extensions + # + # The +extension+ argument allows you to pass a block into a + # has_and_belongs_to_many association. This is useful for adding new + # finders, creators and other factory-type methods to be used as part of + # the association. + # + # Extension examples: + # has_and_belongs_to_many :contractors do + # def find_or_create_by_name(name) + # first_name, last_name = name.split(" ", 2) + # find_or_create_by(first_name: first_name, last_name: last_name) + # end + # end + # # === Options # # [:class_name] -- cgit v1.2.3