Permalink
Browse files

adding more documentation for autosave option

  • Loading branch information...
1 parent 30ea923 commit 06af2913466acb88d46fc18b60c13f5c071395b1 Neeraj Singh committed with fxn Aug 9, 2010
@@ -311,7 +311,8 @@ def association_instance_set(name, association)
# You can set the :autosave option on a <tt>has_one</tt>, <tt>belongs_to</tt>,
# <tt>has_many</tt>, or <tt>has_and_belongs_to_many</tt> 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
#
@@ -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 <tt>:autosave => false</tt> is not same as not declaring <tt>:autosave</tt>
+ # option. When <tt>:autosave</tt> option is not declared then it works in
+ # theoreticall <tt>:new_only</tt> 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 <tt>autosave</tt> 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 <tt>autosave</tt> option children got updated.
+ #
+ # class Post
+ # has_many :comments, :autosave => true
+ # end
+ #
+ # <tt>:autosave</tt> declaration is required if an attempt is made to change an existing
+ # associatin in memory.
@vesan
vesan Aug 24, 2010 Contributor

There's a typo. "associatin" should be "association".

@fxn
fxn Aug 24, 2010 Member

Excellent! Would you like to correct it yourself in docrails?

@vesan
vesan Aug 24, 2010 Contributor

I would but don't know how to do it properly. The file in http://github.com/lifo/docrails/blob/master/activerecord/lib/active_record/autosave_association.rb has different version of the documentation.

@fxn
fxn Aug 24, 2010 Member

I see, there was a revision later and that misspelling is no longer there http://github.com/rails/rails/commit/8af2186d26c77f6fcb0787f50941ebe1a2905c5f

Thank you anyway.

@vesan
vesan Aug 24, 2010 Contributor

I'm so sorry I wasted your time with this. I fixed another small typo in the same file though :-) http://github.com/vesan/docrails/commit/3de0c6d006a6e8c66031be0f95ad3f165c604cf2

@fxn
fxn Aug 24, 2010 Member

No problem :), on the contrary really appreciate the comment.

Thanks for the other fix, all those pesky typos must die!

+ #
+ # 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 <tt>autosave</tt> option is not declared.
module AutosaveAssociation
extend ActiveSupport::Concern

1 comment on commit 06af291

@vesan
Contributor
vesan commented on 06af291 Aug 24, 2010

There's a typo. "associatin" should be "association".

Please sign in to comment.