From 190e270db2e2cc802216b4eb7e300bed372259cf Mon Sep 17 00:00:00 2001 From: Neeraj Singh Date: Mon, 9 Aug 2010 13:37:36 -0400 Subject: adding more documentation for autosave option --- activerecord/lib/active_record/associations.rb | 3 +- .../lib/active_record/autosave_association.rb | 50 ++++++++++++++++------ 2 files changed, 39 insertions(+), 14 deletions(-) (limited to 'activerecord/lib/active_record') diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb index 73c0900c8b..cf75d2dc9b 100644 --- a/activerecord/lib/active_record/associations.rb +++ b/activerecord/lib/active_record/associations.rb @@ -311,7 +311,8 @@ module ActiveRecord # You can set the :autosave option on a has_one, belongs_to, # has_many, or has_and_belongs_to_many association. Setting it # to +true+ will _always_ save the members, whereas setting it to +false+ will - # _never_ save the members. + # _never_ save the members. More details about :autosave option is available at + # autosave_association.rb . # # === One-to-one associations # diff --git a/activerecord/lib/active_record/autosave_association.rb b/activerecord/lib/active_record/autosave_association.rb index 2c7afe3c9f..c661d68869 100644 --- a/activerecord/lib/active_record/autosave_association.rb +++ b/activerecord/lib/active_record/autosave_association.rb @@ -18,6 +18,10 @@ module ActiveRecord # Note that it also means that associations marked for destruction won't # be destroyed directly. They will however still be marked for destruction. # + # Do note that :autosave => false is not same as not declaring :autosave + # option. When :autosave option is not declared then it works in + # theoreticall :new_only mode. Look at has_many example discused below for details. + # # === One-to-one Example # # class Post @@ -57,27 +61,45 @@ module ActiveRecord # # === One-to-many Example # + # When autosave is not declared then also children will get saved when parent is saved + # in certain conditions. + # # Consider a Post model with many Comments: # # class Post - # has_many :comments, :autosave => true + # has_many :comments # :autosave option is no declared # end # - # Saving changes to the parent and its associated model can now be performed - # automatically _and_ atomically: + # post = Post.new(:title => 'ruby rocks') + # post.comments.build(:body => 'hello world') + # post.save #=> will save both post and comment # - # post = Post.find(1) - # post.title # => "The current global position of migrating ducks" - # post.comments.first.body # => "Wow, awesome info thanks!" - # post.comments.last.body # => "Actually, your article should be named differently." + # post = Post.create(:title => 'ruby rocks') + # post.comments.build(:body => 'hello world') + # post.save #=> will save both post and comment # - # post.title = "On the migration of ducks" - # post.comments.last.body = "Actually, your article should be named differently. [UPDATED]: You are right, thanks." + # post = Post.create(:title => 'ruby rocks') + # post.comments.create(:body => 'hello world') + # post.save #=> will save both post and comment # - # post.save - # post.reload - # post.title # => "On the migration of ducks" - # post.comments.last.body # => "Actually, your article should be named differently. [UPDATED]: You are right, thanks." + # post = Post.create(:title => 'ruby rocks') + # post.comments.build(:body => 'hello world') + # post.comments[0].body = 'hi everyone' + # post.save #=> will save both post and comment and comment will have 'hi everyone' + # + # In the above cases even without autosave option children got updated. + # + # class Post + # has_many :comments, :autosave => true + # end + # + # :autosave declaration is required if an attempt is made to change an existing + # associatin in memory. + # + # post = Post.create(:title => 'ruby rocks') + # post.comments.create(:body => 'hello world') + # post.comments[0].body = 'hi everyone' + # post.save #=> will save both post and comment and comment will have 'hi everyone' # # Destroying one of the associated models members, as part of the parent's # save action, is as simple as marking it for destruction: @@ -125,6 +147,8 @@ module ActiveRecord # post = Post.find(1) # post.author.name = '' # post.save(:validate => false) # => true + # + # Note that validation will be perfomend even if autosave option is not declared. module AutosaveAssociation extend ActiveSupport::Concern -- cgit v1.2.3 From cfad74cfef51888321c042623c9e2fb9663640f3 Mon Sep 17 00:00:00 2001 From: Neeraj Singh Date: Thu, 12 Aug 2010 10:23:20 -0400 Subject: updating documentation for named_scope and default_scope --- activerecord/lib/active_record/base.rb | 10 ++++++++++ activerecord/lib/active_record/named_scope.rb | 9 +++++++++ 2 files changed, 19 insertions(+) (limited to 'activerecord/lib/active_record') diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb index 8da4fbcba7..a464b65c19 100644 --- a/activerecord/lib/active_record/base.rb +++ b/activerecord/lib/active_record/base.rb @@ -1147,6 +1147,16 @@ MSG # class Person < ActiveRecord::Base # default_scope order('last_name, first_name') # end + # + # default_scope is also applied while creating/building a record. It is not + # applied while updating a record. + # + # class Article < ActiveRecord::Base + # default_scope where(:published => true) + # end + # + # Article.new.published #=> true + # Article.create.published #=> true def default_scope(options = {}) self.default_scoping << construct_finder_arel(options, default_scoping.pop) end diff --git a/activerecord/lib/active_record/named_scope.rb b/activerecord/lib/active_record/named_scope.rb index 0e560418dc..c95060126e 100644 --- a/activerecord/lib/active_record/named_scope.rb +++ b/activerecord/lib/active_record/named_scope.rb @@ -88,6 +88,15 @@ module ActiveRecord # end # end # end + # + # Scopes can also be used while creating/building a record. + # + # class Article < ActiveRecord::Base + # scope :published, where(:published => true) + # end + # + # Article.published.new.published #=> true + # Article.published.create.published #=> true def scope(name, scope_options = {}, &block) name = name.to_sym valid_scope_name?(name) -- cgit v1.2.3 From 599c50583784537eec454f5e91dac89f88e54da3 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Thu, 12 Aug 2010 16:41:34 +0200 Subject: commit review: applies guidelines to "# =>" --- activerecord/lib/active_record/base.rb | 4 ++-- activerecord/lib/active_record/named_scope.rb | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'activerecord/lib/active_record') diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb index a464b65c19..4b550eb446 100644 --- a/activerecord/lib/active_record/base.rb +++ b/activerecord/lib/active_record/base.rb @@ -1155,8 +1155,8 @@ MSG # default_scope where(:published => true) # end # - # Article.new.published #=> true - # Article.create.published #=> true + # Article.new.published # => true + # Article.create.published # => true def default_scope(options = {}) self.default_scoping << construct_finder_arel(options, default_scoping.pop) end diff --git a/activerecord/lib/active_record/named_scope.rb b/activerecord/lib/active_record/named_scope.rb index c95060126e..bffc450f8e 100644 --- a/activerecord/lib/active_record/named_scope.rb +++ b/activerecord/lib/active_record/named_scope.rb @@ -95,8 +95,8 @@ module ActiveRecord # scope :published, where(:published => true) # end # - # Article.published.new.published #=> true - # Article.published.create.published #=> true + # Article.published.new.published # => true + # Article.published.create.published # => true def scope(name, scope_options = {}, &block) name = name.to_sym valid_scope_name?(name) -- cgit v1.2.3 From 8a2b69b7273379f3c9f68ff7903b653801951ac3 Mon Sep 17 00:00:00 2001 From: Paco Guzman Date: Thu, 12 Aug 2010 17:09:58 +0200 Subject: applied guidelines to "# =>" --- activerecord/lib/active_record/autosave_association.rb | 10 +++++----- activerecord/lib/active_record/reflection.rb | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) (limited to 'activerecord/lib/active_record') diff --git a/activerecord/lib/active_record/autosave_association.rb b/activerecord/lib/active_record/autosave_association.rb index c661d68869..dc6352ab12 100644 --- a/activerecord/lib/active_record/autosave_association.rb +++ b/activerecord/lib/active_record/autosave_association.rb @@ -72,20 +72,20 @@ module ActiveRecord # # post = Post.new(:title => 'ruby rocks') # post.comments.build(:body => 'hello world') - # post.save #=> will save both post and comment + # post.save # => will save both post and comment # # post = Post.create(:title => 'ruby rocks') # post.comments.build(:body => 'hello world') - # post.save #=> will save both post and comment + # post.save # => will save both post and comment # # post = Post.create(:title => 'ruby rocks') # post.comments.create(:body => 'hello world') - # post.save #=> will save both post and comment + # post.save # => will save both post and comment # # post = Post.create(:title => 'ruby rocks') # post.comments.build(:body => 'hello world') # post.comments[0].body = 'hi everyone' - # post.save #=> will save both post and comment and comment will have 'hi everyone' + # post.save # => will save both post and comment and comment will have 'hi everyone' # # In the above cases even without autosave option children got updated. # @@ -99,7 +99,7 @@ module ActiveRecord # post = Post.create(:title => 'ruby rocks') # post.comments.create(:body => 'hello world') # post.comments[0].body = 'hi everyone' - # post.save #=> will save both post and comment and comment will have 'hi everyone' + # post.save # => will save both post and comment and comment will have 'hi everyone' # # Destroying one of the associated models members, as part of the parent's # save action, is as simple as marking it for destruction: diff --git a/activerecord/lib/active_record/reflection.rb b/activerecord/lib/active_record/reflection.rb index 7f47a812eb..8295fd68b3 100644 --- a/activerecord/lib/active_record/reflection.rb +++ b/activerecord/lib/active_record/reflection.rb @@ -41,7 +41,7 @@ module ActiveRecord # Returns the AggregateReflection object for the named +aggregation+ (use the symbol). # - # Account.reflect_on_aggregation(:balance) #=> the balance AggregateReflection + # Account.reflect_on_aggregation(:balance) # => the balance AggregateReflection # def reflect_on_aggregation(aggregation) reflections[aggregation].is_a?(AggregateReflection) ? reflections[aggregation] : nil -- cgit v1.2.3 From 8af2186d26c77f6fcb0787f50941ebe1a2905c5f Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Thu, 12 Aug 2010 17:29:42 +0200 Subject: revises some autosave docs, style and content --- activerecord/lib/active_record/associations.rb | 3 +- .../lib/active_record/autosave_association.rb | 79 ++++++---------------- 2 files changed, 23 insertions(+), 59 deletions(-) (limited to 'activerecord/lib/active_record') diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb index cf75d2dc9b..8be36482d4 100644 --- a/activerecord/lib/active_record/associations.rb +++ b/activerecord/lib/active_record/associations.rb @@ -957,8 +957,7 @@ module ActiveRecord # If false, don't validate the associated objects when saving the parent object. true by default. # [:autosave] # If true, always save the associated objects or destroy them if marked for destruction, - # when saving the parent object. - # If false, never save or destroy the associated objects. + # when saving the parent object. If false, never save or destroy the associated objects. # By default, only save associated objects that are new records. # [:inverse_of] # Specifies the name of the belongs_to association on the associated object diff --git a/activerecord/lib/active_record/autosave_association.rb b/activerecord/lib/active_record/autosave_association.rb index dc6352ab12..131591405c 100644 --- a/activerecord/lib/active_record/autosave_association.rb +++ b/activerecord/lib/active_record/autosave_association.rb @@ -3,13 +3,13 @@ require 'active_support/core_ext/array/wrap' module ActiveRecord # = Active Record Autosave Association # - # AutosaveAssociation is a module that takes care of automatically saving - # associacted records when parent is saved. In addition to saving, it + # +AutosaveAssociation+ is a module that takes care of automatically saving + # associacted records when their parent is saved. In addition to saving, it # also destroys any associated records that were marked for destruction. - # (See mark_for_destruction and marked_for_destruction?) + # (See +mark_for_destruction+ and marked_for_destruction?). # # Saving of the parent, its associations, and the destruction of marked - # associations, all happen inside 1 transaction. This should never leave the + # associations, all happen inside a transaction. This should never leave the # database in an inconsistent state. # # If validations for any of the associations fail, their error messages will @@ -18,9 +18,8 @@ module ActiveRecord # Note that it also means that associations marked for destruction won't # be destroyed directly. They will however still be marked for destruction. # - # Do note that :autosave => false is not same as not declaring :autosave - # option. When :autosave option is not declared then it works in - # theoreticall :new_only mode. Look at has_many example discused below for details. + # Note that :autosave => false is not same as not declaring :autosave. + # When the :autosave option is not present new associations are saved. # # === One-to-one Example # @@ -32,7 +31,7 @@ module ActiveRecord # automatically _and_ atomically: # # post = Post.find(1) - # post.title # => "The current global position of migrating ducks" + # post.title # => "The current global position of migrating ducks" # post.author.name # => "alloy" # # post.title = "On the migration of ducks" @@ -40,7 +39,7 @@ module ActiveRecord # # post.save # post.reload - # post.title # => "On the migration of ducks" + # post.title # => "On the migration of ducks" # post.author.name # => "Eloy Duran" # # Destroying an associated model, as part of the parent's save action, is as @@ -50,6 +49,7 @@ module ActiveRecord # post.author.marked_for_destruction? # => true # # Note that the model is _not_ yet removed from the database: + # # id = post.author.id # Author.find_by_id(id).nil? # => false # @@ -57,14 +57,12 @@ module ActiveRecord # post.reload.author # => nil # # Now it _is_ removed from the database: + # # Author.find_by_id(id).nil? # => true # # === One-to-many Example # - # When autosave is not declared then also children will get saved when parent is saved - # in certain conditions. - # - # Consider a Post model with many Comments: + # When :autosave is not declared new children are saved when their parent is saved: # # class Post # has_many :comments # :autosave option is no declared @@ -72,43 +70,36 @@ module ActiveRecord # # post = Post.new(:title => 'ruby rocks') # post.comments.build(:body => 'hello world') - # post.save # => will save both post and comment + # post.save # => saves both post and comment # # post = Post.create(:title => 'ruby rocks') # post.comments.build(:body => 'hello world') - # post.save # => will save both post and comment + # post.save # => saves both post and comment # # post = Post.create(:title => 'ruby rocks') # post.comments.create(:body => 'hello world') - # post.save # => will save both post and comment - # - # post = Post.create(:title => 'ruby rocks') - # post.comments.build(:body => 'hello world') - # post.comments[0].body = 'hi everyone' - # post.save # => will save both post and comment and comment will have 'hi everyone' + # post.save # => saves both post and comment # - # In the above cases even without autosave option children got updated. + # When :autosave is true all children is saved, no matter whether they are new records: # # class Post # has_many :comments, :autosave => true # end # - # :autosave declaration is required if an attempt is made to change an existing - # associatin in memory. - # # post = Post.create(:title => 'ruby rocks') # post.comments.create(:body => 'hello world') # post.comments[0].body = 'hi everyone' - # post.save # => will save both post and comment and comment will have 'hi everyone' + # post.save # => saves both post and comment, with 'hi everyone' as title # - # Destroying one of the associated models members, as part of the parent's - # save action, is as simple as marking it for destruction: + # Destroying one of the associated models as part of the parent's save action + # is as simple as marking it for destruction: # # post.comments.last.mark_for_destruction # post.comments.last.marked_for_destruction? # => true # post.comments.length # => 2 # # Note that the model is _not_ yet removed from the database: + # # id = post.comments.last.id # Comment.find_by_id(id).nil? # => false # @@ -116,39 +107,13 @@ module ActiveRecord # post.reload.comments.length # => 1 # # Now it _is_ removed from the database: + # # Comment.find_by_id(id).nil? # => true # # === Validation # - # Validation is performed on the parent as usual, but also on all autosave - # enabled associations. If any of the associations fail validation, its - # error messages will be applied on the parents errors object and validation - # of the parent will fail. - # - # Consider a Post model with Author which validates the presence of its name - # attribute: - # - # class Post - # has_one :author, :autosave => true - # end - # - # class Author - # validates_presence_of :name - # end - # - # post = Post.find(1) - # post.author.name = '' - # post.save # => false - # post.errors # => #["can't be blank"]}, @base=#> - # - # No validations will be performed on the associated models when validations - # are skipped for the parent: - # - # post = Post.find(1) - # post.author.name = '' - # post.save(:validate => false) # => true - # - # Note that validation will be perfomend even if autosave option is not declared. + # Validations on children records are run or not depending on the :validate + # option of the association. module AutosaveAssociation extend ActiveSupport::Concern -- cgit v1.2.3