diff options
Diffstat (limited to 'activemodel/lib/active_model')
-rw-r--r-- | activemodel/lib/active_model/dirty.rb | 59 |
1 files changed, 35 insertions, 24 deletions
diff --git a/activemodel/lib/active_model/dirty.rb b/activemodel/lib/active_model/dirty.rb index 3f2fd12db7..7014d8114f 100644 --- a/activemodel/lib/active_model/dirty.rb +++ b/activemodel/lib/active_model/dirty.rb @@ -11,14 +11,14 @@ module ActiveModel # # The requirements for implementing ActiveModel::Dirty are: # - # * <tt>include ActiveModel::Dirty</tt> in your object + # * <tt>include ActiveModel::Dirty</tt> in your object. # * Call <tt>define_attribute_methods</tt> passing each method you want to - # track + # track. # * Call <tt>attr_name_will_change!</tt> before each change to the tracked - # attribute + # attribute. # # If you wish to also track previous changes on save or update, you need to - # add + # add: # # @previously_changed = changes # @@ -27,7 +27,6 @@ module ActiveModel # A minimal implementation could be: # # class Person - # # include ActiveModel::Dirty # # define_attribute_methods :name @@ -45,47 +44,49 @@ module ActiveModel # @previously_changed = changes # @changed_attributes.clear # end - # # end # - # == Examples: - # # A newly instantiated object is unchanged: + # # person = Person.find_by_name('Uncle Bob') # person.changed? # => false # # Change the name: + # # person.name = 'Bob' # person.changed? # => true # person.name_changed? # => true - # person.name_was # => 'Uncle Bob' - # person.name_change # => ['Uncle Bob', 'Bob'] + # person.name_was # => "Uncle Bob" + # person.name_change # => ["Uncle Bob", "Bob"] # person.name = 'Bill' - # person.name_change # => ['Uncle Bob', 'Bill'] + # person.name_change # => ["Uncle Bob", "Bill"] # # Save the changes: + # # person.save # person.changed? # => false # 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'] } + # person.changed # => ["name"] + # person.changes # => {"name" => ["Bill", "Bob"]} # # If an attribute is modified in-place then make use of <tt>[attribute_name]_will_change!</tt> # to mark that the attribute is changing. Otherwise ActiveModel can't track changes to # in-place attributes. # # person.name_will_change! - # person.name_change # => ['Bill', 'Bill'] + # person.name_change # => ["Bill", "Bill"] # person.name << 'y' - # person.name_change # => ['Bill', 'Billy'] + # person.name_change # => ["Bill", "Billy"] module Dirty extend ActiveSupport::Concern include ActiveModel::AttributeMethods @@ -95,7 +96,8 @@ module ActiveModel attribute_method_affix :prefix => 'reset_', :suffix => '!' end - # Returns true if any attribute have unsaved changes, false otherwise. + # Returns +true+ if any attribute have unsaved changes, +false+ otherwise. + # # person.changed? # => false # person.name = 'bob' # person.changed? # => true @@ -103,32 +105,41 @@ module ActiveModel changed_attributes.present? end - # List of attributes with unsaved changes. + # Returns an array with the name of the attributes with unsaved changes. + # # person.changed # => [] # person.name = 'bob' - # person.changed # => ['name'] + # person.changed # => ["name"] def changed changed_attributes.keys end - # Map of changed attrs => [original value, new value]. + # Returns a hash of changed attributes indicating their original + # and new values like <tt>attr => [original value, new value]</tt>. + # # person.changes # => {} # person.name = 'bob' - # person.changes # => { 'name' => ['bill', 'bob'] } + # person.changes # => { "name" => ["bill", "bob"] } def changes HashWithIndifferentAccess[changed.map { |attr| [attr, attribute_change(attr)] }] end - # Map of attributes that were changed when the model was saved. - # person.name # => 'bob' + # 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']} + # person.previous_changes # => {"name" => ["bob", "robert"]} def previous_changes @previously_changed end - # Map of change <tt>attr => original value</tt>. + # Returns a hash of the attributes with unsaved changes indicating their original + # values like <tt>attr => original value</tt>. + # + # person.name # => "bob" + # person.name = 'robert' + # person.changed_attributes # => {"name" => "bob"} def changed_attributes @changed_attributes ||= {} end |