Permalink
Browse files

add CollectionProxy#build documentation

  • Loading branch information...
1 parent 63f094b commit 2c62dd64dbaf1b3c758e7259fa8fefbafbbdcf81 Francesco Rodriguez committed May 22, 2012
Showing with 31 additions and 0 deletions.
  1. +31 −0 activerecord/lib/active_record/associations/collection_proxy.rb
View
31 activerecord/lib/active_record/associations/collection_proxy.rb
@@ -168,6 +168,37 @@ class CollectionProxy < Relation
# another_person_without.pets.last(3) # => []
##
+ # :method: build
+ #
+ # :call-seq:
+ # build(attributes = {}, options = {}, &block)
+ #
+ # Returns a new object of the collection type that has been instantiated
+ # with +attributes+ and linked to this object, but have not yet been saved.
+ # You can pass an array of attributes hashes, this will return an array
+ # with the new objects.
+ #
+ # class Person
+ # has_many :pets
+ # end
+ #
+ # person.pets.build
+ # # => #<Pet id: nil, name: nil, person_id: 1>
+ #
+ # person.pets.build(name: 'Fancy-Fancy')
+ # # => #<Pet id: nil, name: "Fancy-Fancy", person_id: 1>
+ #
+ # person.pets.build([{name: 'Spook'}, {name: 'Choo-Choo'}, {name: 'Brain'}])
+ # # => [
+ # # #<Pet id: nil, name: "Spook", person_id: 1>,
+ # # #<Pet id: nil, name: "Choo-Choo", person_id: 1>,
+ # # #<Pet id: nil, name: "Brain", person_id: 1>
+ # # ]
+ #
+ # person.pets.size # => 5 # size of the collection
+ # person.pets.count # => 0 # count from database
+
+ ##
# :method: concat
# Add one or more records to the collection by setting their foreign keys
# to the association's primary key. Since << flattens its argument list and

0 comments on commit 2c62dd6

Please sign in to comment.