diff options
Diffstat (limited to 'activerecord/lib/active_record/nested_attributes.rb')
| -rw-r--r-- | activerecord/lib/active_record/nested_attributes.rb | 329 |
1 files changed, 329 insertions, 0 deletions
diff --git a/activerecord/lib/active_record/nested_attributes.rb b/activerecord/lib/active_record/nested_attributes.rb new file mode 100644 index 0000000000..e3122d195a --- /dev/null +++ b/activerecord/lib/active_record/nested_attributes.rb @@ -0,0 +1,329 @@ +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: + # <tt>author_attributes=(attributes)</tt> and + # <tt>pages_attributes=(attributes)</tt>. + # + # class Book < ActiveRecord::Base + # has_one :author + # has_many :pages + # + # accepts_nested_attributes_for :author, :pages + # end + # + # Note that the <tt>:autosave</tt> 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.id # => 2 + # member.avatar.icon # => 'smiling' + # + # It also allows you to update the avatar through the member: + # + # params = { :member' => { :avatar_attributes => { :id => '2', :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 + # <tt>:allow_destroy</tt> option. + # + # class Member < ActiveRecord::Base + # has_one :avatar + # accepts_nested_attributes_for :avatar, :allow_destroy => true + # end + # + # Now, when you add the <tt>_delete</tt> key to the attributes hash, with a + # value that evaluates to +true+, you will destroy the associated model: + # + # member.avatar_attributes = { :id => '2', :_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 + # end + # + # You can now set or update attributes on an associated post model through + # the attribute hash. + # + # 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>_delete</tt> key + # that evaluates to +true+. + # + # params = { :member => { + # :name => 'joe', :posts_attributes => [ + # { :title => 'Kari, the awesome Ruby documentation browser!' }, + # { :title => 'The egalitarian assumption of the modern citizen' }, + # { :title => '', :_delete => '1' } # this will be ignored + # ] + # }} + # + # 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' + # + # You may also set a :reject_if proc to silently ignore any new record + # 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 + # + # params = { :member => { + # :name => 'joe', :posts_attributes => [ + # { :title => 'Kari, the awesome Ruby documentation browser!' }, + # { :title => 'The egalitarian assumption of the modern citizen' }, + # { :title => '' } # this will be ignored because of the :reject_if proc + # ] + # }} + # + # 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' + # + # If the hash contains an <tt>id</tt> key that matches an already + # associated record, the matching record will be modified: + # + # member.attributes = { + # :name => 'Joe', + # :posts_attributes => [ + # { :id => 1, :title => '[UPDATED] An, as of yet, undisclosed awesome Ruby documentation browser!' }, + # { :id => 2, :title => '[UPDATED] other post' } + # ] + # } + # + # member.posts.first.title # => '[UPDATED] An, as of yet, undisclosed awesome Ruby documentation browser!' + # member.posts.second.title # => '[UPDATED] other post' + # + # By default the associated records are protected from being destroyed. If + # you want to destroy any of the associated records through the attributes + # hash, you have to enable it first using the <tt>:allow_destroy</tt> + # option. This will allow you to also use the <tt>_delete</tt> key to + # destroy existing records: + # + # class Member < ActiveRecord::Base + # has_many :posts + # accepts_nested_attributes_for :posts, :allow_destroy => true + # end + # + # params = { :member => { + # :posts_attributes => [{ :id => '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). If you + # are using <tt>attr_protected</tt> or <tt>attr_accessible</tt>, then you + # will need to add the attribute writer to the allowed list. + # + # Supported options: + # [:allow_destroy] + # If true, destroys any members from the attributes hash with a + # <tt>_delete</tt> key and a value that evaluates 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 that + # do not have a <tt>_delete</tt> that evaluates to true. + # + # Examples: + # # creates avatar_attributes= + # accepts_nested_attributes_for :avatar, :reject_if => proc { |attributes| attributes['name'].blank? } + # # creates avatar_attributes= and posts_attributes= + # accepts_nested_attributes_for :avatar, :posts, :allow_destroy => true + 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 + + # Attribute hash keys that should not be assigned as normal attributes. + # These hash keys are nested attributes implementation details. + UNASSIGNABLE_KEYS = %w{ id _delete } + + # Assigns the given attributes to the association. + # + # If the given attributes include an <tt>:id</tt> that matches the existing + # record’s id, then the existing record will be modified. Otherwise a new + # record will be built. + # + # If the given attributes include a matching <tt>:id</tt> attribute _and_ a + # <tt>:_delete</tt> key set to a truthy value, then the existing record + # will be marked for destruction. + def assign_nested_attributes_for_one_to_one_association(association_name, attributes, allow_destroy) + attributes = attributes.stringify_keys + + if attributes['id'].blank? + unless reject_new_record?(association_name, attributes) + send("build_#{association_name}", attributes.except(*UNASSIGNABLE_KEYS)) + end + elsif (existing_record = send(association_name)) && existing_record.id.to_s == attributes['id'].to_s + assign_to_or_mark_for_destruction(existing_record, attributes, allow_destroy) + end + end + + # Assigns the given attributes to the collection association. + # + # Hashes with an <tt>:id</tt> value matching an existing associated record + # will update that record. Hashes without an <tt>:id</tt> value will build + # a new record for the association. Hashes with a matching <tt>:id</tt> + # value and a <tt>:_delete</tt> key set to a truthy value will mark the + # matched record for destruction. + # + # For example: + # + # assign_nested_attributes_for_collection_association(:people, { + # '1' => { :id => '1', :name => 'Peter' }, + # '2' => { :name => 'John' }, + # '3' => { :id => '2', :_delete => true } + # }) + # + # Will update the name of the Person with ID 1, build a new associated + # person with the name `John', and mark the associatied Person with ID 2 + # for destruction. + # + # Also accepts an Array of attribute hashes: + # + # assign_nested_attributes_for_collection_association(:people, [ + # { :id => '1', :name => 'Peter' }, + # { :name => 'John' }, + # { :id => '2', :_delete => true } + # ]) + def assign_nested_attributes_for_collection_association(association_name, attributes_collection, allow_destroy) + unless attributes_collection.is_a?(Hash) || attributes_collection.is_a?(Array) + raise ArgumentError, "Hash or Array expected, got #{attributes_collection.class.name} (#{attributes_collection.inspect})" + end + + if attributes_collection.is_a? Hash + attributes_collection = attributes_collection.sort_by { |index, _| index.to_i }.map { |_, attributes| attributes } + end + + attributes_collection.each do |attributes| + attributes = attributes.stringify_keys + + if attributes['id'].blank? + unless reject_new_record?(association_name, attributes) + send(association_name).build(attributes.except(*UNASSIGNABLE_KEYS)) + end + elsif existing_record = send(association_name).detect { |record| record.id.to_s == attributes['id'].to_s } + assign_to_or_mark_for_destruction(existing_record, attributes, allow_destroy) + end + end + end + + # Updates a record with the +attributes+ or marks it for destruction if + # +allow_destroy+ is +true+ and has_delete_flag? returns +true+. + def assign_to_or_mark_for_destruction(record, attributes, allow_destroy) + if has_delete_flag?(attributes) && allow_destroy + record.mark_for_destruction + else + record.attributes = attributes.except(*UNASSIGNABLE_KEYS) + end + end + + # Determines if a hash contains a truthy _delete key. + def has_delete_flag?(hash) + ConnectionAdapters::Column.value_to_boolean hash['_delete'] + end + + # Determines if a new record should be build by checking for + # has_delete_flag? or if a <tt>:reject_if</tt> proc exists for this + # association and evaluates to +true+. + def reject_new_record?(association_name, attributes) + has_delete_flag?(attributes) || + self.class.reject_new_nested_attributes_procs[association_name].try(:call, attributes) + end + end +end |