preferences 0.3.1 → 0.4.0

data/CHANGELOG.rdoc

@@ -1,5 +1,22 @@
 == master
 
+== 0.4.0 / 2010-03-07
+
+* Add {preference}_changed?, {preference}_was, {preference}_changed, {preference}_will_change!, and reset_{preference}!
+* Add #preferences_changed?, #preferences_changed, and #preference_changes
+* Fix preferences that are reverted externally still getting stored
+* Fix preference definition types not being used to typecast values
+* No longer allow both group and non-group preferences to be looked up at once (except for named scopes)
+* Add support for using Symbols to reference groups
+* Fix #reload not causing unsaved preferences to get reset
+* Raise exception if unknown preference is accessed
+* Rename #set_preference to #write_preference
+* Add caching of preference lookups
+* Fix preferences being stored even if they didn't change
+* Release gems via rake-gemcutter instead of rubyforge
+* Add a generator for db migration to make installation a bit easier [Tim Lowrimore]
+* Add named scopes: #with_preferences and #without_preferences
+
 == 0.3.1 / 2009-04-25
 
 * Rename Preference#attribute to #name to avoid conflicts with reserved methods in ActiveRecord

data/README.rdoc

@@ -40,6 +40,17 @@ a separate table and making it dead-simple to define and manage preferences.
 
 == Usage
 
+=== Installation
+
++preferences+ requires an additional database table to work.  You can generate
+a migration for this table like so:
+
+  script/generate preferences
+
+Then simply migrate your database:
+
+  rake db:migrate
+
 === Defining preferences
 
 To define the preferences for a model, you can do so right within the model:
@@ -101,8 +112,8 @@ Reader method:
   user.preferred(:language)     # => "English"
 
 Write method:
-  user.set_preference(:hot_salsa, false)      # => false
-  user.set_preference(:language, "English")   # => "English"
+  user.write_preference(:hot_salsa, false)      # => false
+  user.write_preference(:language, "English")   # => "English"
 
 === Accessing all preferences
 
@@ -135,7 +146,7 @@ through an example:
   car = Car.find(:first)
   
   user.preferred_color = 'red', car
-  # user.set_preference(:color, 'red', car) # The generic way
+  # user.write_preference(:color, 'red', car) # The generic way
 
 This will create a color preference of "red" for the given car.  In this way,
 you can have "color" preferences for different records.
@@ -151,14 +162,13 @@ preferences by name.  For example,
 
   user = User.find(:first)
   
-  user.preferred_color = 'red', 'automobiles'
-  user.preferred_color = 'tan', 'clothing'
+  user.preferred_color = 'red', :automobiles
+  user.preferred_color = 'tan', :clothing
   
-  user.preferred_color('automobiles')   # => "red"
-  user.preferred_color('clothing')      # => "tan"
-
-  user.preferences                # => {"color"=>nil, "automobiles"=>{"color"=>"red"}, "clothing=>{"color=>"tan"}}
-  user.preferences('automobiles') # => {"color"=>"red"}
+  user.preferred_color(:automobiles)  # => "red"
+  user.preferred_color(:clothing)     # => "tan"
+  
+  user.preferences(:automobiles)      # => {"color"=>"red"}
 
 === Saving preferences
 
@@ -171,6 +181,27 @@ Preferences are treated in a similar fashion to attributes.  For example,
 
 Preferences are stored in a separate table called "preferences".
 
+=== Tracking changes
+
+Similar to ActiveRecord attributes, unsaved changes to preferences can be
+tracked.  For example,
+
+  user.preferred_language               # => "English"
+  user.preferred_language_changed?      # => false
+  user.preferred_language = 'Spanish'
+  user.preferred_language_changed?      # => true
+  user.preferred_language_was           # => "English"
+  user.preferred_language_change        # => ["English", "Spanish"]
+  user.reset_preferred_language!
+  user.preferred_language               # => "English"
+
+Assigning the same value leaves the preference unchanged:
+
+  user.preferred_language               # => "English"
+  user.preferred_language = 'English'
+  user.preferred_language_changed?      # => false
+  user.preferred_language_change        # => nil
+
 == Testing
 
 Before you can run any tests, the following gem must be installed:

data/Rakefile

@@ -1,15 +1,17 @@
+require 'rubygems'
+require 'rake'
 require 'rake/testtask'
 require 'rake/rdoctask'
 require 'rake/gempackagetask'
-require 'rake/contrib/sshpublisher'
 
 spec = Gem::Specification.new do |s|
   s.name              = 'preferences'
-  s.version           = '0.3.1'
+  s.version           = '0.4.0'
   s.platform          = Gem::Platform::RUBY
-  s.summary           = 'Adds support for easily creating custom preferences for models'
+  s.summary           = 'Adds support for easily creating custom preferences for ActiveRecord models'
+  s.description       = s.summary
   
-  s.files             = FileList['{app,lib,test}/**/*'] + %w(CHANGELOG.rdoc init.rb LICENSE Rakefile README.rdoc) - FileList['test/app_root/{log,log/*,script,script/*}']
+  s.files             = FileList['{app,generators,lib,test}/**/*'] + %w(CHANGELOG.rdoc init.rb LICENSE Rakefile README.rdoc) - FileList['test/app_root/{log,log/*,script,script/*}']
   s.require_path      = 'lib'
   s.has_rdoc          = true
   s.test_files        = Dir['test/**/*_test.rb']
@@ -52,20 +54,27 @@ Rake::RDocTask.new(:rdoc) do |rdoc|
   rdoc.options << '--line-numbers' << '--inline-source'
   rdoc.rdoc_files.include('README.rdoc', 'CHANGELOG.rdoc', 'LICENSE', 'lib/**/*.rb', 'app/**/*.rb')
 end
-  
+
+desc 'Generate a gemspec file.'
+task :gemspec do
+  File.open("#{spec.name}.gemspec", 'w') do |f|
+    f.write spec.to_ruby
+  end
+end
+
 Rake::GemPackageTask.new(spec) do |p|
   p.gem_spec = spec
-  p.need_tar = true
-  p.need_zip = true
 end
 
 desc 'Publish the beta gem.'
 task :pgem => [:package] do
+  require 'rake/contrib/sshpublisher'
   Rake::SshFilePublisher.new('aaron@pluginaweek.org', '/home/aaron/gems.pluginaweek.org/public/gems', 'pkg', "#{spec.name}-#{spec.version}.gem").upload
 end
 
 desc 'Publish the API documentation.'
 task :pdoc => [:rdoc] do
+  require 'rake/contrib/sshpublisher'
   Rake::SshDirPublisher.new('aaron@pluginaweek.org', "/home/aaron/api.pluginaweek.org/public/#{spec.name}", 'rdoc').upload
 end
 
@@ -74,15 +83,8 @@ task :publish => [:pgem, :pdoc, :release]
 
 desc 'Publish the release files to RubyForge.'
 task :release => [:gem, :package] do
-  require 'rubyforge'
-  
-  ruby_forge = RubyForge.new.configure
-  ruby_forge.login
+  require 'rake/gemcutter'
   
-  %w(gem tgz zip).each do |ext|
-    file = "pkg/#{spec.name}-#{spec.version}.#{ext}"
-    puts "Releasing #{File.basename(file)}..."
-    
-    ruby_forge.add_release(spec.rubyforge_project, spec.name, spec.version, file)
-  end
+  Rake::Gemcutter::Tasks.new(spec)
+  Rake::Task['gem:push'].invoke
 end

data/app/models/preference.rb

@@ -29,7 +29,7 @@ class Preference < ActiveRecord::Base
       if group.is_a?(ActiveRecord::Base)
         group_id, group_type = group.id, group.class.base_class.name.to_s
       else
-        group_id, group_type = nil, group
+        group_id, group_type = nil, group.is_a?(Symbol) ? group.to_s : group
       end
       
       [group_id, group_type]

data/generators/preferences/USAGE

@@ -0,0 +1,5 @@
+Usage:
+
+  script/generate preferences
+
+This will create a migration that will add the proper table to store preferences.

data/generators/preferences/preferences_generator.rb

@@ -0,0 +1,7 @@
+class PreferencesGenerator < Rails::Generator::Base
+  def manifest
+    record do |m|
+      m.migration_template '001_create_preferences.rb', 'db/migrate', :migration_file_name => 'create_preferences'
+    end
+  end
+end

data/generators/preferences/templates/001_create_preferences.rb

@@ -0,0 +1,16 @@
+class CreatePreferences < ActiveRecord::Migration
+  def self.up
+    create_table :preferences do |t|
+      t.string :name, :null => false
+      t.references :owner, :polymorphic => true, :null => false
+      t.references :group, :polymorphic => true
+      t.string :value
+      t.timestamps
+    end
+    add_index :preferences, [:owner_id, :owner_type, :name, :group_id, :group_type], :unique => true, :name => 'index_preferences_on_owner_and_name_and_preference'
+  end
+  
+  def self.down
+    drop_table :preferences
+  end
+end

data/lib/preferences.rb

@@ -74,6 +74,27 @@ module Preferences
     #   specified for a record.  This will not include default preferences
     #   unless they have been explicitly set.
     # 
+    # == Named scopes
+    # 
+    # In addition to the above associations, the following named scopes get
+    # generated for the model:
+    # * +with_preferences+ - Finds all records with a given set of preferences
+    # * +without_preferences+ - Finds all records without a given set of preferences
+    # 
+    # In addition to utilizing preferences stored in the database, each of the
+    # above scopes also take into account the defaults that have been defined
+    # for each preference.
+    # 
+    # Example:
+    # 
+    #   User.with_preferences(:notifications => true)
+    #   User.with_preferences(:notifications => true, :color => 'blue')
+    #   
+    #   # Searching with group preferences
+    #   car = Car.find(:first)
+    #   User.with_preferences(car => {:color => 'blue'})
+    #   User.with_preferences(:notifications => true, car => {:color => 'blue'})
+    # 
     # == Generated accessors
     # 
     # In addition to calling <tt>prefers?</tt> and +preferred+ on a record,
@@ -87,10 +108,22 @@ module Preferences
     # ...generates the following methods:
     # * <tt>prefers_notifications?</tt> - Whether a value has been specified, i.e. <tt>record.prefers?(:notifications)</tt>
     # * <tt>prefers_notifications</tt> - The actual value stored, i.e. <tt>record.prefers(:notifications)</tt>
-    # * <tt>prefers_notifications=(value)</tt> - Sets a new value, i.e. <tt>record.set_preference(:notifications, value)</tt>
-    # * <tt>preferred_notifications?</tt> - Whether a value has been specified, i.e. <tt>record.preferred?(:notifications)</tt>
-    # * <tt>preferred_notifications</tt> - The actual value stored, i.e. <tt>record.preferred(:notifications)</tt>
-    # * <tt>preferred_notifications=(value)</tt> - Sets a new value, i.e. <tt>record.set_preference(:notifications, value)</tt>
+    # * <tt>prefers_notifications=(value)</tt> - Sets a new value, i.e. <tt>record.write_preference(:notifications, value)</tt>
+    # * <tt>prefers_notifications_changed?</tt> - Whether the preference has unsaved changes
+    # * <tt>prefers_notifications_was</tt> - The last saved value for the preference
+    # * <tt>prefers_notifications_change</tt> - A list of [original_value, new_value] if the preference has changed
+    # * <tt>prefers_notifications_will_change!</tt> - Forces the preference to get updated
+    # * <tt>reset_prefers_notifications!</tt> - Reverts any unsaved changes to the preference
+    # 
+    # ...and the equivalent +preferred+ methods:
+    # * <tt>preferred_notifications?</tt>
+    # * <tt>preferred_notifications</tt>
+    # * <tt>preferred_notifications=(value)</tt>
+    # * <tt>preferred_notifications_changed?</tt>
+    # * <tt>preferred_notifications_was</tt>
+    # * <tt>preferred_notifications_change</tt>
+    # * <tt>preferred_notifications_will_change!</tt>
+    # * <tt>reset_preferred_notifications!</tt>
     # 
     # Notice that there are two tenses used depending on the context of the
     # preference.  Conventionally, <tt>prefers_notifications?</tt> is better
@@ -126,6 +159,11 @@ module Preferences
         
         after_save :update_preferences
         
+        # Named scopes
+        named_scope :with_preferences, lambda {|preferences| build_preference_scope(preferences)}
+        named_scope :without_preferences, lambda {|preferences| build_preference_scope(preferences, true)}
+        
+        extend Preferences::ClassMethods
         include Preferences::InstanceMethods
       end
       
@@ -153,14 +191,93 @@ module Preferences
       
       # Writer
       define_method("preferred_#{name}=") do |*args|
-        set_preference(*([name] + [args].flatten))
+        write_preference(*args.flatten.unshift(name))
       end
       alias_method "prefers_#{name}=", "preferred_#{name}="
       
+      # Changes
+      define_method("preferred_#{name}_changed?") do |*group|
+        preference_changed?(name, group.first)
+      end
+      alias_method "prefers_#{name}_changed?", "preferred_#{name}_changed?"
+      
+      define_method("preferred_#{name}_was") do |*group|
+        preference_was(name, group.first)
+      end
+      alias_method "prefers_#{name}_was", "preferred_#{name}_was"
+      
+      define_method("preferred_#{name}_change") do |*group|
+        preference_change(name, group.first)
+      end
+      alias_method "prefers_#{name}_change", "preferred_#{name}_change"
+      
+      define_method("preferred_#{name}_will_change!") do |*group|
+        preference_will_change!(name, group.first)
+      end
+      alias_method "prefers_#{name}_will_change!", "preferred_#{name}_will_change!"
+      
+      define_method("reset_preferred_#{name}!") do |*group|
+        reset_preference!(name, group.first)
+      end
+      alias_method "reset_prefers_#{name}!", "reset_preferred_#{name}!"
+      
       definition
     end
   end
   
+  module ClassMethods #:nodoc:
+    # Generates the scope for looking under records with a specific set of
+    # preferences associated with them.
+    # 
+    # Note thate this is a bit more complicated than usual since the preference
+    # definitions aren't in the database for joins, defaults need to be accounted
+    # for, and querying for the the presence of multiple preferences requires
+    # multiple joins.
+    def build_preference_scope(preferences, inverse = false)
+      joins = []
+      statements = []
+      values = []
+      
+      # Flatten the preferences for easier processing
+      preferences = preferences.inject({}) do |result, (group, value)|
+        if value.is_a?(Hash)
+          value.each {|preference, value| result[[group, preference]] = value}
+        else
+          result[[nil, group]] = value
+        end
+        result
+      end
+      
+      preferences.each do |(group, preference), value|
+        preference = preference.to_s
+        value = preference_definitions[preference.to_s].type_cast(value)
+        is_default = default_preferences[preference.to_s] == value
+        
+        group_id, group_type = Preference.split_group(group)
+        table = "preferences_#{group_id}_#{group_type}_#{preference}"
+        
+        # Since each preference is a different record, they need their own
+        # join so that the proper conditions can be set
+        joins << "LEFT JOIN preferences AS #{table} ON #{table}.owner_id = #{table_name}.#{primary_key} AND " + sanitize_sql(
+          "#{table}.owner_type" => base_class.name.to_s,
+          "#{table}.group_id" => group_id,
+          "#{table}.group_type" => group_type,
+          "#{table}.name" => preference
+        )
+        
+        if inverse
+          statements << "#{table}.id IS NOT NULL AND #{table}.value " + (value.nil? ? ' IS NOT NULL' : ' != ?') + (!is_default ? " OR #{table}.id IS NULL" : '')
+        else
+          statements << "#{table}.id IS NOT NULL AND #{table}.value " + (value.nil? ? ' IS NULL' : ' = ?') + (is_default ? " OR #{table}.id IS NULL" : '')
+        end
+        values << value unless value.nil?
+      end
+      
+      sql = statements.map! {|statement| "(#{statement})"} * ' AND '
+      {:joins => joins, :conditions => values.unshift(sql)}
+    end
+  end
+  
   module InstanceMethods
     def self.included(base) #:nodoc:
       base.class_eval do
@@ -169,8 +286,8 @@ module Preferences
     end
     
     # Finds all preferences, including defaults, for the current record.  If
-    # any custom group preferences have been stored, then this will include
-    # all default preferences within that particular group.
+    # looking up custom group preferences, then this will include all default
+    # preferences within that particular group as well.
     # 
     # == Examples
     # 
@@ -182,46 +299,23 @@ module Preferences
     #   
     # A user with stored values for a particular group:
     # 
-    #   user.preferred_color = 'red', 'cars'
-    #   user.preferences
-    #   => {"language"=>"English", "color"=>nil, "cars"=>{"language=>"English", "color"=>"red"}}
-    #   
-    # Getting preference values *just* for the owning record (i.e. excluding groups):
-    # 
-    #   user.preferences(nil)
-    #   => {"language"=>"English", "color"=>nil}
-    #   
-    # Getting preference values for a particular group:
-    # 
-    #   user.preferences('cars')
-    #   => {"language"=>"English", "color"=>"red"}
-    def preferences(*args)
-      if args.empty?
-        group = nil
-        conditions = {}
-      else
-        group = args.first
+    #   user.preferred_color = 'red', :cars
+    #   user.preferences(:cars)
+    #   => {"language=>"English", "color"=>"red"}
+    def preferences(group = nil)
+      unless preferences_group_loaded?(group)
+        preferences = preferences_group(group)
         
-        # Split the actual group into its different parts (id/type) in case
-        # a record is passed in
         group_id, group_type = Preference.split_group(group)
-        conditions = {:group_id => group_id, :group_type => group_type}
-      end
-      
-      # Find all of the stored preferences
-      stored_preferences = self.stored_preferences.find(:all, :conditions => conditions)
-      
-      # Hashify name -> value or group -> name -> value
-      stored_preferences.inject(self.class.default_preferences.dup) do |all_preferences, preference|
-        if !group && (preference_group = preference.group)
-          preferences = all_preferences[preference_group] ||= self.class.default_preferences.dup
-        else
-          preferences = all_preferences
+        find_preferences(:group_id => group_id, :group_type => group_type).each do |preference|
+          preferences[preference.name] ||= preference.value
         end
         
-        preferences[preference.name] = preference.value
-        all_preferences
+        # Add defaults
+        preferences.reverse_merge!(self.class.default_preferences.dup)
       end
+      
+      preferences_group(group).dup
     end
     
     # Queries whether or not a value is present for the given preference.
@@ -239,11 +333,12 @@ module Preferences
     #   user.preferred?(:color, 'cars')     # => true
     #   user.preferred?(:color, Car.first)  # => true
     #   
-    #   user.set_preference(:color, nil)
+    #   user.write_preference(:color, nil)
     #   user.preferred(:color)              # => nil
     #   user.preferred?(:color)             # => false
     def preferred?(name, group = nil)
       name = name.to_s
+      assert_valid_preference(name)
       
       value = preferred(name, group)
       preference_definitions[name].query(value)
@@ -264,24 +359,27 @@ module Preferences
     #   user.preferred(:color, 'cars')    # => "red"
     #   user.preferred(:color, Car.first) # => "red"
     #   
-    #   user.set_preference(:color, 'blue')
+    #   user.write_preference(:color, 'blue')
     #   user.preferred(:color)            # => "blue"
     def preferred(name, group = nil)
       name = name.to_s
+      assert_valid_preference(name)
       
-      if @preference_values && @preference_values[group] && @preference_values[group].include?(name)
+      if preferences_group(group).include?(name)
         # Value for this group/name has been written, but not saved yet:
         # grab from the pending values
-        value = @preference_values[group][name]
+        value = preferences_group(group)[name]
       else
-        # Split the group being filtered
+        # Grab the first preference; if it doesn't exist, use the default value
         group_id, group_type = Preference.split_group(group)
+        preference = find_preferences(:name => name, :group_id => group_id, :group_type => group_type).first unless preferences_group_loaded?(group)
         
-        # Grab the first preference; if it doesn't exist, use the default value
-        preference = stored_preferences.find(:first, :conditions => {:name => name, :group_id => group_id, :group_type => group_type})
         value = preference ? preference.value : preference_definitions[name].default_value
+        preferences_group(group)[name] = value
       end
       
+      definition = preference_definitions[name]
+      value = definition.type_cast(value) unless value.nil?
       value
     end
     alias_method :prefers, :preferred
@@ -295,40 +393,213 @@ module Preferences
     # == Examples
     # 
     #   user = User.find(:first)
-    #   user.set_preference(:color, 'red')              # => "red"
+    #   user.write_preference(:color, 'red')              # => "red"
     #   user.save!
     #   
-    #   user.set_preference(:color, 'blue', Car.first)  # => "blue"
+    #   user.write_preference(:color, 'blue', Car.first)  # => "blue"
     #   user.save!
-    def set_preference(name, value, group = nil)
+    def write_preference(name, value, group = nil)
       name = name.to_s
+      assert_valid_preference(name)
+      
+      preferences_changed = preferences_changed_group(group)
+      if preferences_changed.include?(name)
+        old = preferences_changed[name]
+        preferences_changed.delete(name) unless preference_value_changed?(name, old, value)
+      else
+        old = clone_preference_value(name, group)
+        preferences_changed[name] = old if preference_value_changed?(name, old, value)
+      end
       
-      @preference_values ||= {}
-      @preference_values[group] ||= {}
-      @preference_values[group][name] = value
+      value = convert_number_column_value(value) if preference_definitions[name].number?
+      preferences_group(group)[name] = value
       
       value
     end
     
+    # Whether any attributes have unsaved changes.
+    # 
+    # == Examples
+    # 
+    #   user = User.find(:first)
+    #   user.preferences_changed?                   # => false
+    #   user.write_preference(:color, 'red')
+    #   user.preferences_changed?                   # => true
+    #   user.save
+    #   user.preferences_changed?                   # => false
+    #   
+    #   # Groups
+    #   user.preferences_changed?(:car)             # => false
+    #   user.write_preference(:color, 'red', :car)
+    #   user.preferences_changed(:car)              # => true
+    def preferences_changed?(group = nil)
+      !preferences_changed_group(group).empty?
+    end
+    
+    # A list of the preferences that have unsaved changes.
+    # 
+    # == Examples
+    # 
+    #   user = User.find(:first)
+    #   user.preferences_changed                    # => []
+    #   user.write_preference(:color, 'red')
+    #   user.preferences_changed                    # => ["color"]
+    #   user.save
+    #   user.preferences_changed                    # => []
+    #   
+    #   # Groups
+    #   user.preferences_changed(:car)              # => []
+    #   user.write_preference(:color, 'red', :car)
+    #   user.preferences_changed(:car)              # => ["color"]
+    def preferences_changed(group = nil)
+      preferences_changed_group(group).keys
+    end
+    
+    # A map of the preferences that have changed in the current object.
+    # 
+    # == Examples
+    # 
+    #   user = User.find(:first)
+    #   user.preferred(:color)                      # => nil
+    #   user.preference_changes                     # => {}
+    #   
+    #   user.write_preference(:color, 'red')
+    #   user.preference_changes                     # => {"color" => [nil, "red"]}
+    #   user.save
+    #   user.preference_changes                     # => {}
+    #   
+    #   # Groups
+    #   user.preferred(:color, :car)                # => nil
+    #   user.preference_changes(:car)               # => {}
+    #   user.write_preference(:color, 'red', :car)
+    #   user.preference_changes(:car)               # => {"color" => [nil, "red"]}
+    def preference_changes(group = nil)
+      preferences_changed(group).inject({}) do |changes, preference|
+        changes[preference] = preference_change(preference, group)
+        changes
+      end
+    end
+    
+    # Reloads the pereferences of this object as well as its attributes
+    def reload(*args) #:nodoc:
+      result = super
+      
+      @preferences.clear if @preferences
+      @preferences_changed.clear if @preferences_changed
+      
+      result
+    end
+    
     private
+      # Asserts that the given name is a valid preference in this model.  If it
+      # is not, then an ArgumentError exception is raised.
+      def assert_valid_preference(name)
+        raise(ArgumentError, "Unknown preference: #{name}") unless preference_definitions.include?(name)
+      end
+      
+      # Gets the set of preferences identified by the given group
+      def preferences_group(group)
+        @preferences ||= {}
+        @preferences[group.is_a?(Symbol) ? group.to_s : group] ||= {}
+      end
+      
+      # Determines whether the given group of preferences has already been
+      # loaded from the database
+      def preferences_group_loaded?(group)
+        preference_definitions.length == preferences_group(group).length
+      end
+      
+      # Generates a clone of the current value stored for the preference with
+      # the given name / group
+      def clone_preference_value(name, group)
+        value = preferred(name, group)
+        value.duplicable? ? value.clone : value
+      rescue TypeError, NoMethodError
+        value
+      end
+      
+      # Keeps track of all preferences that have been changed so that they can
+      # be properly updated in the database.  Maps group -> preference -> value.
+      def preferences_changed_group(group)
+        @preferences_changed ||= {}
+        @preferences_changed[group.is_a?(Symbol) ? group.to_s : group] ||= {}
+      end
+      
+      # Determines whether a preference changed in the given group
+      def preference_changed?(name, group)
+        preferences_changed_group(group).include?(name)
+      end
+      
+      # Builds an array of [original_value, new_value] for the given preference.
+      # If the perference did not change, this will return nil.
+      def preference_change(name, group)
+        [preferences_changed_group(group)[name], preferred(name, group)] if preference_changed?(name, group)
+      end
+      
+      # Gets the last saved value for the given preference
+      def preference_was(name, group)
+        preference_changed?(name, group) ? preferences_changed_group(group)[name] : preferred(name, group)
+      end
+      
+      # Forces the given preference to be saved regardless of whether the value
+      # is actually diferent
+      def preference_will_change!(name, group)
+        preferences_changed_group(group)[name] = clone_preference_value(name, group)
+      end
+      
+      # Reverts any unsaved changes to the given preference
+      def reset_preference!(name, group)
+        write_preference(name, preferences_changed_group(group)[name], group) if preference_changed?(name, group)
+      end
+      
+      # Determines whether the old value is different from the new value for the
+      # given preference.  This will use the typecasted value to determine
+      # equality.
+      def preference_value_changed?(name, old, value)
+        definition = preference_definitions[name]
+        if definition.type == :integer && (old.nil? || old == 0)
+          # For nullable numeric columns, NULL gets stored in database for blank (i.e. '') values.
+          # Hence we don't record it as a change if the value changes from nil to ''.
+          # If an old value of 0 is set to '' we want this to get changed to nil as otherwise it'll
+          # be typecast back to 0 (''.to_i => 0)
+          value = nil if value.blank?
+        else
+          value = definition.type_cast(value)
+        end
+        
+        old != value
+      end
+      
       # Updates any preferences that have been changed/added since the record
       # was last saved
       def update_preferences
-        if @preference_values
-          @preference_values.each do |group, new_preferences|
+        if @preferences_changed
+          @preferences_changed.each do |group, preferences|
             group_id, group_type = Preference.split_group(group)
             
-            new_preferences.each do |name, value|
-              attributes = {:name => name, :group_id => group_id, :group_type => group_type}
-              
+            preferences.keys.each do |name|
               # Find an existing preference or build a new one
-              preference = stored_preferences.find(:first, :conditions => attributes) ||  stored_preferences.build(attributes)
-              preference.value = value
+              attributes = {:name => name, :group_id => group_id, :group_type => group_type}
+              preference = find_preferences(attributes).first || stored_preferences.build(attributes)
+              preference.value = preferred(name, group)
               preference.save!
             end
           end
           
-          @preference_values = nil
+          @preferences_changed.clear
+        end
+      end
+      
+      # Finds all stored preferences with the given attributes.  This will do a
+      # smart lookup by looking at the in-memory collection if it was eager-
+      # loaded.
+      def find_preferences(attributes)
+        if stored_preferences.loaded?
+          stored_preferences.select do |preference|
+            attributes.all? {|attribute, value| preference[attribute] == value} 
+          end
+        else
+          stored_preferences.find(:all, :conditions => attributes)
         end
       end
   end