Browse files

Document nested attributes as hash of hashes

Document the possibility to use a hash of hashes for nested attributes for a one-to-many association (in addition to the documented possibility to use an array of hashes).

Align indentation in comments.
  • Loading branch information...
1 parent 6823948 commit efd86315a71231f7cfa6510151c6f8cd792f3a22 @alexeymuranov alexeymuranov committed Mar 12, 2013
Showing with 41 additions and 17 deletions.
  1. +41 −17 activerecord/lib/active_record/nested_attributes.rb
View
58 activerecord/lib/active_record/nested_attributes.rb
@@ -92,8 +92,9 @@ class TooManyRecords < ActiveRecordError
# accepts_nested_attributes_for :posts
# end
#
- # You can now set or update attributes on an associated post model through
- # the attribute hash.
+ # You can now set or update attributes on the associated posts through
+ # an attribute hash for a member: include the key +:posts_attributes+
+ # with an array of hashes of post attributes as a value.
#
# For each hash that does _not_ have an <tt>id</tt> key a new record will
# be instantiated, unless the hash also contains a <tt>_destroy</tt> key
@@ -116,10 +117,10 @@ class TooManyRecords < ActiveRecordError
# hashes if they fail to pass your criteria. For example, the previous
# example could be rewritten as:
#
- # class Member < ActiveRecord::Base
- # has_many :posts
- # accepts_nested_attributes_for :posts, :reject_if => proc { |attributes| attributes['title'].blank? }
- # end
+ # class Member < ActiveRecord::Base
+ # has_many :posts
+ # accepts_nested_attributes_for :posts, :reject_if => proc { |attributes| attributes['title'].blank? }
+ # end
#
# params = { :member => {
# :name => 'joe', :posts_attributes => [
@@ -136,19 +137,19 @@ class TooManyRecords < ActiveRecordError
#
# Alternatively, :reject_if also accepts a symbol for using methods:
#
- # class Member < ActiveRecord::Base
- # has_many :posts
- # accepts_nested_attributes_for :posts, :reject_if => :new_record?
- # end
+ # class Member < ActiveRecord::Base
+ # has_many :posts
+ # accepts_nested_attributes_for :posts, :reject_if => :new_record?
+ # end
#
- # class Member < ActiveRecord::Base
- # has_many :posts
- # accepts_nested_attributes_for :posts, :reject_if => :reject_posts
+ # class Member < ActiveRecord::Base
+ # has_many :posts
+ # accepts_nested_attributes_for :posts, :reject_if => :reject_posts
#
- # def reject_posts(attributed)
- # attributed['title'].blank?
- # end
- # end
+ # def reject_posts(attributed)
+ # attributed['title'].blank?
+ # end
+ # end
#
# If the hash contains an <tt>id</tt> key that matches an already
# associated record, the matching record will be modified:
@@ -185,6 +186,29 @@ class TooManyRecords < ActiveRecordError
# member.save
# member.reload.posts.length # => 1
#
+ # Nested attributes for an associated collection can also be passed in
+ # the form of a hash of hashes instead of an array of hashes:
+ #
+ # Member.create(:name => 'joe',
+ # :posts_attributes => { :first => { :title => 'Foo' },
+ # :second => { :title => 'Bar' } })
+ #
+ # has the same effect as
+ #
+ # Member.create(:name => 'joe',
+ # :posts_attributes => [ { :title => 'Foo' },
+ # { :title => 'Bar' } ])
+ #
+ # The keys of the hash which is the value for +:posts_attributes+ are
+ # ignored in this case.
+ # However, it is not allowed to use +'id'+ or +:id+ for one of
+ # such keys, otherwise the hash will be wrapped in an array and
+ # interpreted as an attribute hash for a single post.
+ #
+ # Passing attributes for an associated collection in the form of a hash
+ # of hashes can be used with hashes generated from HTTP/HTML parameters,
+ # where there maybe no natural way to submit an array of hashes.
+ #
# === Saving
#
# All changes to models, including the destruction of those marked for

0 comments on commit efd8631

Please sign in to comment.