module ActiveModel::Dirty
Active Model Dirty¶ ↑
Provides a way to track changes in your object in the same way as Active Record does.
The requirements for implementing ActiveModel::Dirty
are:
-
include ActiveModel::Dirty
in your object. -
Call
define_attribute_methods
passing each method you want to track. -
Call
*_will_change!
before each change to the tracked attribute. -
Call
changes_applied
after the changes are persisted. -
Call
clear_changes_information
when you want to reset the changes information. -
Call
restore_attributes
when you want to restore previous data.
A minimal implementation could be:
class Person include ActiveModel::Dirty define_attribute_methods :name def initialize @name = nil end def name @name end def name=(val) name_will_change! unless val == @name @name = val end def save # do persistence work changes_applied end def reload! # get the values from the persistence layer clear_changes_information end def rollback! restore_attributes end end
A newly instantiated Person
object is unchanged:
person = Person.new person.changed? # => false
Change the name:
person.name = 'Bob' person.changed? # => true person.name_changed? # => true person.name_changed?(from: nil, to: "Bob") # => true person.name_was # => nil person.name_change # => [nil, "Bob"] person.name = 'Bill' person.name_change # => [nil, "Bill"]
Save the changes:
person.save person.changed? # => false person.name_changed? # => false
Reset the changes:
person.previous_changes # => {"name" => [nil, "Bill"]} person.name_previously_changed? # => true person.name_previously_changed?(from: nil, to: "Bill") # => true person.name_previous_change # => [nil, "Bill"] person.name_previously_was # => nil person.reload! person.previous_changes # => {}
Rollback the changes:
person.name = "Uncle Bob" person.rollback! person.name # => "Bill" person.name_changed? # => false
Assigning the same value leaves the attribute unchanged:
person.name = 'Bill' person.name_changed? # => false person.name_change # => nil
Which attributes have changed?
person.name = 'Bob' person.changed # => ["name"] person.changes # => {"name" => ["Bill", "Bob"]}
If an attribute is modified in-place then make use of *_will_change! to mark that the attribute is changing. Otherwise Active Model can’t track changes to in-place attributes. Note that Active Record can detect in-place modifications automatically. You do not need to call *_will_change!
on Active Record models.
person.name_will_change! person.name_change # => ["Bill", "Bill"] person.name << 'y' person.name_change # => ["Bill", "Billy"]
Methods can be invoked as name_changed?
or by passing an argument to the generic method attribute_changed?("name")
.
Public Instance Methods
Source
# File lib/active_model/dirty.rb, line 155
This method is generated for each attribute.
Returns the old and the new value of the attribute.
person = Person.new person.name = 'Nick' person.name_change # => [nil, 'Nick']
Source
# File lib/active_model/dirty.rb, line 144
This method is generated for each attribute.
Returns true if the attribute has unsaved changes.
person = Person.new person.name = 'Andrew' person.name_changed? # => true
Source
# File lib/active_model/dirty.rb, line 193
This method is generated for each attribute.
Returns the old and the new value of the attribute before the last save.
person = Person.new person.name = 'Emmanuel' person.save person.name_previous_change # => [nil, 'Emmanuel']
Source
# File lib/active_model/dirty.rb, line 129
This method is generated for each attribute.
Returns true if the attribute previously had unsaved changes.
person = Person.new person.name = 'Britanny' person.save person.name_previously_changed? # => true person.name_previously_changed?(from: nil, to: 'Britanny') # => true
Source
# File lib/active_model/dirty.rb, line 205
This method is generated for each attribute.
Returns the old value of the attribute before the last save.
person = Person.new person.name = 'Sage' person.save person.name_previously_was # => nil
Source
# File lib/active_model/dirty.rb, line 182
This method is generated for each attribute.
Returns the old value of the attribute.
person = Person.new(name: 'Steph') person.name = 'Stephanie' person.name_was # => 'Steph'
Source
# File lib/active_model/dirty.rb, line 166
This method is generated for each attribute.
If an attribute is modified in-place then make use of *_will_change!
to mark that the attribute is changing. Otherwise Active Model
can’t track changes to in-place attributes. Note that Active Record can detect in-place modifications automatically. You do not need to call *_will_change!
on Active Record models.
person = Person.new('Sandy') person.name_will_change! person.name_change # => ['Sandy', 'Sandy']
Source
# File lib/active_model/dirty.rb, line 300 def attribute_changed?(attr_name, **options) mutations_from_database.changed?(attr_name.to_s, **options) end
Dispatch target for *_changed? attribute methods.
Source
# File lib/active_model/dirty.rb, line 310 def attribute_previously_changed?(attr_name, **options) mutations_before_last_save.changed?(attr_name.to_s, **options) end
Dispatch target for *_previously_changed? attribute methods.
Source
# File lib/active_model/dirty.rb, line 315 def attribute_previously_was(attr_name) mutations_before_last_save.original_value(attr_name.to_s) end
Dispatch target for *_previously_was attribute methods.
Source
# File lib/active_model/dirty.rb, line 305 def attribute_was(attr_name) mutations_from_database.original_value(attr_name.to_s) end
Dispatch target for *_was attribute methods.
Source
# File lib/active_model/dirty.rb, line 295 def changed mutations_from_database.changed_attribute_names end
Returns an array with the name of the attributes with unsaved changes.
person.changed # => [] person.name = 'bob' person.changed # => ["name"]
Source
# File lib/active_model/dirty.rb, line 286 def changed? mutations_from_database.any_changes? end
Returns true
if any of the attributes has unsaved changes, false
otherwise.
person.changed? # => false person.name = 'bob' person.changed? # => true
Source
# File lib/active_model/dirty.rb, line 343 def changed_attributes mutations_from_database.changed_values end
Returns a hash of the attributes with unsaved changes indicating their original values like attr => original value
.
person.name # => "bob" person.name = 'robert' person.changed_attributes # => {"name" => "bob"}
Source
# File lib/active_model/dirty.rb, line 353 def changes mutations_from_database.changes end
Returns a hash of changed attributes indicating their original and new values like attr => [original value, new value]
.
person.changes # => {} person.name = 'bob' person.changes # => { "name" => ["bill", "bob"] }
Source
# File lib/active_model/dirty.rb, line 272 def changes_applied unless defined?(@attributes) mutations_from_database.finalize_changes end @mutations_before_last_save = mutations_from_database forget_attribute_assignments @mutations_from_database = nil end
Clears dirty data and moves changes
to previous_changes
and mutations_from_database
to mutations_before_last_save
respectively.
Source
# File lib/active_model/dirty.rb, line 241 attribute_method_suffix "_previously_changed?", "_changed?", parameters: "**options"
This method is generated for each attribute.
Clears all dirty data of the attribute: current changes and previous changes.
person = Person.new(name: 'Chris') person.name = 'Jason' person.name_change # => ['Chris', 'Jason'] person.clear_name_change person.name_change # => nil
Source
# File lib/active_model/dirty.rb, line 331 def clear_attribute_changes(attr_names) attr_names.each do |attr_name| clear_attribute_change(attr_name) end end
Source
# File lib/active_model/dirty.rb, line 325 def clear_changes_information @mutations_before_last_save = nil forget_attribute_assignments @mutations_from_database = nil end
Clears all dirty data: current changes and previous changes.
Source
# File lib/active_model/dirty.rb, line 363 def previous_changes mutations_before_last_save.changes end
Returns a hash of attributes that were changed before the model was saved.
person.name # => "bob" person.name = 'robert' person.save person.previous_changes # => {"name" => ["bob", "robert"]}
Source
# File lib/active_model/dirty.rb, line 217
This method is generated for each attribute.
Restores the attribute to the old value.
person = Person.new person.name = 'Amanda' person.restore_name! person.name # => nil
Source
# File lib/active_model/dirty.rb, line 320 def restore_attributes(attr_names = changed) attr_names.each { |attr_name| restore_attribute!(attr_name) } end
Restore all previous data of the provided attributes.
Private Instance Methods
Source
# File lib/active_model/dirty.rb, line 399 def attribute_change(attr_name) mutations_from_database.change_to_attribute(attr_name.to_s) end
Dispatch target for *_change
attribute methods.
Source
# File lib/active_model/dirty.rb, line 404 def attribute_previous_change(attr_name) mutations_before_last_save.change_to_attribute(attr_name.to_s) end
Dispatch target for *_previous_change
attribute methods.
Source
# File lib/active_model/dirty.rb, line 409 def attribute_will_change!(attr_name) mutations_from_database.force_change(attr_name.to_s) end
Dispatch target for *_will_change!
attribute methods.
Source
# File lib/active_model/dirty.rb, line 378 def clear_attribute_change(attr_name) mutations_from_database.forget_change(attr_name.to_s) end
Source
# File lib/active_model/dirty.rb, line 390 def forget_attribute_assignments @attributes = @attributes.map(&:forgetting_assignment) if defined?(@attributes) end
Source
# File lib/active_model/dirty.rb, line 372 def init_internals super @mutations_before_last_save = nil @mutations_from_database = nil end
Source
# File lib/active_model/dirty.rb, line 394 def mutations_before_last_save @mutations_before_last_save ||= ActiveModel::NullMutationTracker.instance end
Source
# File lib/active_model/dirty.rb, line 382 def mutations_from_database @mutations_from_database ||= if defined?(@attributes) ActiveModel::AttributeMutationTracker.new(@attributes) else ActiveModel::ForcedMutationTracker.new(self) end end
Source
# File lib/active_model/dirty.rb, line 414 def restore_attribute!(attr_name) attr_name = attr_name.to_s if attribute_changed?(attr_name) __send__("#{attr_name}=", attribute_was(attr_name)) clear_attribute_change(attr_name) end end
Dispatch target for restore_*!
attribute methods.