Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

update ActiveModel::Dirty documentation

  • Loading branch information...
commit f87820d00acc4a699f2bb405fa33d4f1054ec52d 1 parent da0ef60
@frodsan frodsan authored
Showing with 35 additions and 24 deletions.
  1. +35 −24 activemodel/lib/active_model/dirty.rb
View
59 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 Dirty
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 @@ def changed?
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
Please sign in to comment.
Something went wrong with that request. Please try again.