module ActiveRecord::AutosaveAssociation - activerecord-4.2.3 Documentation

# module ActiveRecord::AutosaveAssociation

# Active Record Autosave Association¶ ↑

`AutosaveAssociation` is a module that takes care of automatically saving associated records when their parent is saved. In addition to saving, it also destroys any associated records that were marked for destruction. (See `mark_for_destruction` and `marked_for_destruction?`).

Saving of the parent, its associations, and the destruction of marked associations, all happen inside a transaction. This should never leave the database in an inconsistent state.

If validations for any of the associations fail, their error messages will be applied to the parent.

Note that it also means that associations marked for destruction won't be destroyed directly. They will however still be marked for destruction.

Note that `autosave: false` is not same as not declaring `:autosave`. When the `:autosave` option is not present then new association records are saved but the updated association records are not saved.

## Validation¶ ↑

Children records are validated unless `:validate` is `false`.

## Callbacks¶ ↑

Association with autosave option defines several callbacks on your model (before_save, after_create, after_update). Please note that callbacks are executed in the order they were defined in model. You should avoid modifying the association content, before autosave callbacks are executed. Placing your callbacks after associations is usually a good practice.

### One-to-one Example¶ ↑

    class Post < ActiveRecord::Base
      has_one :author, autosave: true
    end

Saving changes to the parent and its associated model can now be performed automatically and atomically:

    post = Post.find(1)
    post.title       # => "The current global position of migrating ducks"
    post.author.name # => "alloy"

    post.title = "On the migration of ducks"
    post.author.name = "Eloy Duran"

    post.save
    post.reload
    post.title       # => "On the migration of ducks"
    post.author.name # => "Eloy Duran"

Destroying an associated model, as part of the parent's save action, is as simple as marking it for destruction:

    post.author.mark_for_destruction
    post.author.marked_for_destruction? # => true

Note that the model is not yet removed from the database:

    id = post.author.id
    Author.find_by(id: id).nil? # => false

    post.save
    post.reload.author # => nil

Now it is removed from the database:

    Author.find_by(id: id).nil? # => true

### One-to-many Example¶ ↑

When `:autosave` is not declared new children are saved when their parent is saved:

    class Post < ActiveRecord::Base
      has_many :comments # :autosave option is not declared
    end

    post = Post.new(title: 'ruby rocks')
    post.comments.build(body: 'hello world')
    post.save # => saves both post and comment

    post = Post.create(title: 'ruby rocks')
    post.comments.build(body: 'hello world')
    post.save # => saves both post and comment

    post = Post.create(title: 'ruby rocks')
    post.comments.create(body: 'hello world')
    post.save # => saves both post and comment

When `:autosave` is true all children are saved, no matter whether they are new records or not:

    class Post < ActiveRecord::Base
      has_many :comments, autosave: true
    end

    post = Post.create(title: 'ruby rocks')
    post.comments.create(body: 'hello world')
    post.comments[0].body = 'hi everyone'
    post.comments.build(body: "good morning.")
    post.title += "!"
    post.save # => saves both post and comments.

Destroying one of the associated models as part of the parent's save action is as simple as marking it for destruction:

    post.comments # => [#<Comment id: 1, ...>, #<Comment id: 2, ...]>
    post.comments[1].mark_for_destruction
    post.comments[1].marked_for_destruction? # => true
    post.comments.length # => 2

Note that the model is not yet removed from the database:

    id = post.comments.last.id
    Comment.find_by(id: id).nil? # => false

    post.save
    post.reload.comments.length # => 1

Now it is removed from the database:

    Comment.find_by(id: id).nil? # => true

### Public Instance Methods

changed_for_autosave?() click to toggle source

Returns whether or not this record has been changed in any way (including whether any of its nested autosave associations are likewise changed)

    # File lib/active_record/autosave_association.rb, line 261
    def changed_for_autosave?
      new_record? || changed? || marked_for_destruction? || nested_records_changed_for_autosave?
    end

destroyed_by_association() click to toggle source

Returns the association for the parent being destroyed.

Used to avoid updating the counter cache unnecessarily.

    # File lib/active_record/autosave_association.rb, line 255
    def destroyed_by_association
      @destroyed_by_association
    end

destroyed_by_association=(reflection) click to toggle source

Records the association that is being destroyed and destroying this record in the process.

    # File lib/active_record/autosave_association.rb, line 248
    def destroyed_by_association=(reflection)
      @destroyed_by_association = reflection
    end

mark_for_destruction() click to toggle source

Marks this record to be destroyed as part of the parents save transaction. This does not actually destroy the record instantly, rather child record will be destroyed when `parent.save` is called.

Only useful if the `:autosave` option on the parent is enabled for this associated model.

    # File lib/active_record/autosave_association.rb, line 235
    def mark_for_destruction
      @marked_for_destruction = true
    end

marked_for_destruction?() click to toggle source

Returns whether or not this record will be destroyed as part of the parents save transaction.

Only useful if the `:autosave` option on the parent is enabled for this associated model.

    # File lib/active_record/autosave_association.rb, line 242
    def marked_for_destruction?
      @marked_for_destruction
    end

reload(options = nil) click to toggle source

Reloads the attributes of the object as usual and clears `marked_for_destruction` flag.

Calls superclass method

    # File lib/active_record/autosave_association.rb, line 224
    def reload(options = nil)
      @marked_for_destruction = false
      @destroyed_by_association = nil
      super
    end

### Private Instance Methods

associated_records_to_validate_or_save(association, new_record, autosave) click to toggle source

Returns the record for an association collection that should be validated or saved. If `autosave` is `false` only new records will be returned, unless the parent is/was a new record itself.

    # File lib/active_record/autosave_association.rb, line 270
    def associated_records_to_validate_or_save(association, new_record, autosave)
      if new_record
        association && association.target
      elsif autosave
        association.target.find_all { |record| record.changed_for_autosave? }
      else
        association.target.find_all { |record| record.new_record? }
      end
    end

association_valid?(reflection, record) click to toggle source

Returns whether or not the association is valid and applies any errors to the parent, `self`, if it wasn't. Skips any `:autosave` enabled records if they're marked_for_destruction? or destroyed.

    # File lib/active_record/autosave_association.rb, line 320
    def association_valid?(reflection, record)
      return true if record.destroyed? || record.marked_for_destruction?

      validation_context = self.validation_context unless [:create, :update].include?(self.validation_context)
      unless valid = record.valid?(validation_context)
        if reflection.options[:autosave]
          record.errors.each do |attribute, message|
            attribute = "#{reflection.name}.#{attribute}"
            errors[attribute] << message
            errors[attribute].uniq!
          end
        else
          errors.add(reflection.name)
        end
      end
      valid
    end

before_save_collection_association() click to toggle source

Is used as a before_save callback to check while saving a collection association whether or not the parent was a new record before saving.

    # File lib/active_record/autosave_association.rb, line 340
    def before_save_collection_association
      @new_record_before_save = new_record?
      true
    end

nested_records_changed_for_autosave?() click to toggle source

go through nested autosave associations that are loaded in memory (without loading any new ones), and return true if is changed for autosave

    # File lib/active_record/autosave_association.rb, line 282
    def nested_records_changed_for_autosave?
      @_nested_records_changed_for_autosave_already_called ||= false
      return false if @_nested_records_changed_for_autosave_already_called
      begin
        @_nested_records_changed_for_autosave_already_called = true
        self.class._reflections.values.any? do |reflection|
          if reflection.options[:autosave]
            association = association_instance_get(reflection.name)
            association && Array.wrap(association.target).any?(&:changed_for_autosave?)
          end
        end
      ensure
        @_nested_records_changed_for_autosave_already_called = false
      end
    end

record_changed?(reflection, record, key) click to toggle source

If the record is new or it has changed, returns true.

    # File lib/active_record/autosave_association.rb, line 422
    def record_changed?(reflection, record, key)
      record.new_record? ||
        (record.has_attribute?(reflection.foreign_key) && record[reflection.foreign_key] != key) ||
        record.attribute_changed?(reflection.foreign_key)
    end

save_belongs_to_association(reflection) click to toggle source

Saves the associated record if it's new or `:autosave` is enabled.

In addition, it will destroy the association if it was marked for destruction.

    # File lib/active_record/autosave_association.rb, line 431
    def save_belongs_to_association(reflection)
      association = association_instance_get(reflection.name)
      record      = association && association.load_target
      if record && !record.destroyed?
        autosave = reflection.options[:autosave]

        if autosave && record.marked_for_destruction?
          self[reflection.foreign_key] = nil
          record.destroy
        elsif autosave != false
          saved = record.save(:validate => !autosave) if record.new_record? || (autosave && record.changed_for_autosave?)

          if association.updated?
            association_id = record.send(reflection.options[:primary_key] || :id)
            self[reflection.foreign_key] = association_id
            association.loaded!
          end

          saved if autosave
        end
      end
    end

save_collection_association(reflection) click to toggle source

Saves any new associated records, or all loaded autosave associations if `:autosave` is enabled on the association.

In addition, it destroys all children that were marked for destruction with mark_for_destruction.

This all happens inside a transaction, if the Transactions module is included into ActiveRecord::Base after the AutosaveAssociation module, which it does by default.

    # File lib/active_record/autosave_association.rb, line 353
    def save_collection_association(reflection)
      if association = association_instance_get(reflection.name)
        autosave = reflection.options[:autosave]

        if records = associated_records_to_validate_or_save(association, @new_record_before_save, autosave)
          if autosave
            records_to_destroy = records.select(&:marked_for_destruction?)
            records_to_destroy.each { |record| association.destroy(record) }
            records -= records_to_destroy
          end

          records.each do |record|
            next if record.destroyed?

            saved = true

            if autosave != false && (@new_record_before_save || record.new_record?)
              if autosave
                saved = association.insert_record(record, false)
              else
                association.insert_record(record) unless reflection.nested?
              end
            elsif autosave
              saved = record.save(:validate => false)
            end

            raise ActiveRecord::Rollback unless saved
          end
        end

        # reconstruct the scope now that we know the owner's id
        association.reset_scope if association.respond_to?(:reset_scope)
      end
    end

save_has_one_association(reflection) click to toggle source

Saves the associated record if it's new or `:autosave` is enabled on the association.

In addition, it will destroy the association if it was marked for destruction with mark_for_destruction.

This all happens inside a transaction, if the Transactions module is included into ActiveRecord::Base after the AutosaveAssociation module, which it does by default.

    # File lib/active_record/autosave_association.rb, line 396
    def save_has_one_association(reflection)
      association = association_instance_get(reflection.name)
      record      = association && association.load_target

      if record && !record.destroyed?
        autosave = reflection.options[:autosave]

        if autosave && record.marked_for_destruction?
          record.destroy
        elsif autosave != false
          key = reflection.options[:primary_key] ? send(reflection.options[:primary_key]) : id

          if (autosave && record.changed_for_autosave?) || new_record? || record_changed?(reflection, record, key)
            unless reflection.through_reflection
              record[reflection.foreign_key] = key
            end

            saved = record.save(:validate => !autosave)
            raise ActiveRecord::Rollback if !saved && autosave
            saved
          end
        end
      end
    end

validate_collection_association(reflection) click to toggle source

Validate the associated records if `:validate` or `:autosave` is turned on for the association specified by `reflection`.

    # File lib/active_record/autosave_association.rb, line 309
    def validate_collection_association(reflection)
      if association = association_instance_get(reflection.name)
        if records = associated_records_to_validate_or_save(association, new_record?, reflection.options[:autosave])
          records.each { |record| association_valid?(reflection, record) }
        end
      end
    end

validate_single_association(reflection) click to toggle source

Validate the association if `:validate` or `:autosave` is turned on for the association.

    # File lib/active_record/autosave_association.rb, line 300
    def validate_single_association(reflection)
      association = association_instance_get(reflection.name)
      record      = association && association.reader
      association_valid?(reflection, record) if record
    end