module ActiveRecord module NestedAttributes #:nodoc: def self.included(base) base.extend(ClassMethods) base.class_inheritable_accessor :reject_new_nested_attributes_procs, :instance_writer => false base.reject_new_nested_attributes_procs = {} end # == Nested Attributes # # Nested attributes allow you to save attributes on associated records # through the parent. By default nested attribute updating is turned off, # you can enable it using the accepts_nested_attributes_for class method. # When you enable nested attributes an attribute writer is defined on # the model. # # The attribute writer is named after the association, which means that # in the following example, two new methods are added to your model: # author_attributes=(attributes) and # pages_attributes=(attributes). # # class Book < ActiveRecord::Base # has_one :author # has_many :pages # # accepts_nested_attributes_for :author, :pages # end # # Note that the :autosave option is automatically enabled on every # association that accepts_nested_attributes_for is used for. # # === One-to-one # # Consider a Member model that has one Avatar: # # class Member < ActiveRecord::Base # has_one :avatar # accepts_nested_attributes_for :avatar # end # # Enabling nested attributes on a one-to-one association allows you to # create the member and avatar in one go: # # params = { 'member' => { 'name' => 'Jack', 'avatar_attributes' => { 'icon' => 'smiling' } } } # member = Member.create(params) # member.avatar.icon #=> 'smiling' # # It also allows you to update the avatar through the member: # # params = { 'member' => { 'avatar_attributes' => { 'icon' => 'sad' } } } # member.update_attributes params['member'] # member.avatar.icon #=> 'sad' # # By default you will only be able to set and update attributes on the # associated model. If you want to destroy the associated model through the # attributes hash, you have to enable it first using the # :allow_destroy option. # # class Member < ActiveRecord::Base # has_one :avatar # accepts_nested_attributes_for :avatar, :allow_destroy => true # end # # Now, when you add the _delete key to the attributes hash, with a # value that evaluates to +true+, you will destroy the associated model: # # member.avatar_attributes = { '_delete' => '1' } # member.avatar.marked_for_destruction? # => true # member.save # member.avatar #=> nil # # Note that the model will _not_ be destroyed until the parent is saved. # # === One-to-many # # Consider a member that has a number of posts: # # class Member < ActiveRecord::Base # has_many :posts # accepts_nested_attributes_for :posts, :reject_if => proc { |attributes| attributes['title'].blank? } # end # # You can now set or update attributes on an associated post model through # the attribute hash. # # For each key in the hash that starts with the string 'new' a new model # will be instantiated. When the proc given with the :reject_if # option evaluates to +false+ for a certain attribute hash no record will # be built for that hash. # # params = { 'member' => { # 'name' => 'joe', 'posts_attributes' => { # 'new_12345' => { 'title' => 'Kari, the awesome Ruby documentation browser!' }, # 'new_54321' => { 'title' => 'The egalitarian assumption of the modern citizen' }, # 'new_67890' => { 'title' => '' } # This one matches the :reject_if proc and will not be instantiated. # } # }} # # member = Member.create(params['member']) # member.posts.length #=> 2 # member.posts.first.title #=> 'Kari, the awesome Ruby documentation browser!' # member.posts.second.title #=> 'The egalitarian assumption of the modern citizen' # # When the key for post attributes is an integer, the associated post with # that ID will be updated: # # member.attributes = { # 'name' => 'Joe', # 'posts_attributes' => { # '1' => { 'title' => '[UPDATED] An, as of yet, undisclosed awesome Ruby documentation browser!' }, # '2' => { 'title' => '[UPDATED] other post' } # } # } # # By default the associated models are protected from being destroyed. If # you want to destroy any of the associated models through the attributes # hash, you have to enable it first using the :allow_destroy # option. # # This will allow you to specify which models to destroy in the attributes # hash by setting the '_delete' attribute to a value that evaluates to # +true+: # # class Member < ActiveRecord::Base # has_many :posts # accepts_nested_attributes_for :posts, :allow_destroy => true # end # # params = {'member' => { 'name' => 'joe', 'posts_attributes' => { # '2' => { '_delete' => '1' } # }}} # member.attributes = params['member'] # member.posts.detect { |p| p.id == 2 }.marked_for_destruction? # => true # member.posts.length #=> 2 # member.save # member.posts.length # => 1 # # === Saving # # All changes to models, including the destruction of those marked for # destruction, are saved and destroyed automatically and atomically when # the parent model is saved. This happens inside the transaction initiated # by the parents save method. See ActiveRecord::AutosaveAssociation. module ClassMethods # Defines an attributes writer for the specified association(s). # # Supported options: # [:allow_destroy] # If true, destroys any members from the attributes hash with a # _delete key and a value that converts to +true+ # (eg. 1, '1', true, or 'true'). This option is off by default. # [:reject_if] # Allows you to specify a Proc that checks whether a record should be # built for a certain attribute hash. The hash is passed to the Proc # and the Proc should return either +true+ or +false+. When no Proc # is specified a record will be built for all attribute hashes. # # Examples: # accepts_nested_attributes_for :avatar # accepts_nested_attributes_for :avatar, :allow_destroy => true # accepts_nested_attributes_for :avatar, :reject_if => proc { ... } # accepts_nested_attributes_for :avatar, :posts, :allow_destroy => true, :reject_if => proc { ... } def accepts_nested_attributes_for(*attr_names) options = { :allow_destroy => false } options.update(attr_names.extract_options!) options.assert_valid_keys(:allow_destroy, :reject_if) attr_names.each do |association_name| if reflection = reflect_on_association(association_name) type = case reflection.macro when :has_one, :belongs_to :one_to_one when :has_many, :has_and_belongs_to_many :collection end reflection.options[:autosave] = true self.reject_new_nested_attributes_procs[association_name.to_sym] = options[:reject_if] # def pirate_attributes=(attributes) # assign_nested_attributes_for_one_to_one_association(:pirate, attributes, false) # end class_eval %{ def #{association_name}_attributes=(attributes) assign_nested_attributes_for_#{type}_association(:#{association_name}, attributes, #{options[:allow_destroy]}) end }, __FILE__, __LINE__ else raise ArgumentError, "No association found for name `#{association_name}'. Has it been defined yet?" end end end end # Returns ActiveRecord::AutosaveAssociation::marked_for_destruction? # It's used in conjunction with fields_for to build a form element # for the destruction of this association. # # See ActionView::Helpers::FormHelper::fields_for for more info. def _delete marked_for_destruction? end private # Assigns the given attributes to the association. An association will be # build if it doesn't exist yet. def assign_nested_attributes_for_one_to_one_association(association_name, attributes, allow_destroy) if should_destroy_nested_attributes_record?(allow_destroy, attributes) send(association_name).mark_for_destruction else (send(association_name) || send("build_#{association_name}")).attributes = attributes end end # Assigns the given attributes to the collection association. # # Keys containing an ID for an associated record will update that record. # Keys starting with new will instantiate a new record for that # association. # # For example: # # assign_nested_attributes_for_collection_association(:people, { # '1' => { 'name' => 'Peter' }, # 'new_43' => { 'name' => 'John' } # }) # # Will update the name of the Person with ID 1 and create a new associated # person with the name 'John'. def assign_nested_attributes_for_collection_association(association_name, attributes, allow_destroy) unless attributes.is_a?(Hash) raise ArgumentError, "Hash expected, got #{attributes.class.name} (#{attributes.inspect})" end # Make sure any new records sorted by their id before they're build. sorted_by_id = attributes.sort_by { |id, _| id.is_a?(String) ? id.sub(/^new_/, '').to_i : id } sorted_by_id.each do |id, record_attributes| if id.acts_like?(:string) && id.starts_with?('new_') build_new_nested_attributes_record(association_name, record_attributes) else assign_to_or_destroy_nested_attributes_record(association_name, id, record_attributes, allow_destroy) end end end # Returns +true+ if allow_destroy is enabled and the attributes # contains a truthy value for the key '_delete'. # # It will _always_ remove the '_delete' key, if present. def should_destroy_nested_attributes_record?(allow_destroy, attributes) ConnectionAdapters::Column.value_to_boolean(attributes.delete('_delete')) && allow_destroy end # Builds a new record with the given attributes. # # If a :reject_if proc exists for this association, it will be # called with the attributes as its argument. If the proc returns a truthy # value, the record is _not_ build. def build_new_nested_attributes_record(association_name, attributes) if reject_proc = self.class.reject_new_nested_attributes_procs[association_name] return if reject_proc.call(attributes) end send(association_name).build(attributes) end # Assigns the attributes to the record specified by +id+. Or marks it for # destruction if #should_destroy_nested_attributes_record? returns +true+. def assign_to_or_destroy_nested_attributes_record(association_name, id, attributes, allow_destroy) record = send(association_name).detect { |record| record.id == id.to_i } if should_destroy_nested_attributes_record?(allow_destroy, attributes) record.mark_for_destruction else record.attributes = attributes end end end end