pluginaweek-preferences 0.3.1

data/CHANGELOG.rdoc

@@ -0,0 +1,56 @@
+== master
+
+== 0.3.1 / 2009-04-25
+
+* Rename Preference#attribute to #name to avoid conflicts with reserved methods in ActiveRecord
+
+== 0.3.0 / 2009-04-13
+
+* Add dependency on Rails 2.3
+* Remove dependency on plugins_plus
+
+== 0.2.0 / 2008-12-14
+
+* Remove the PluginAWeek namespace
+
+== 0.1.5 / 2008-11-16
+
+* Add all prefers/preferred accessors for preferences to be analogous to ActiveRecord column accessors
+* Fix preferences defined in STI subclasses not working [Quinn Shanahan]
+
+== 0.1.4 / 2008-10-26
+
+* Change how the base module is included to prevent namespacing conflicts
+
+== 0.1.3 / 2008-06-29
+
+* Add +prefs+ as an alias for +preferences+
+* Fix +preferences+ not properly selecting preferences when a group is specified
+* Improve test coverage
+
+== 0.1.2 / 2008-06-22
+
+* Remove log files from gems
+
+== 0.1.1 / 2008-06-20
+
+* Rename preference_values hash to preferences
+* Rename preferences association to stored_preferences
+
+== 0.1.0 / 2008-06-19
+
+* Avoid string evaluation for dynamic methods
+* Return hashes for the preference_values, e.g.
+  
+  user.preference_values            # => {'color' => 'red', 'number' => 11, 'website' => {'background' => 'white', 'foreground' => 'black'}}
+  user.preference_values('website') # => {'background' => 'white', 'foreground' => 'black'}
+
+* Add more generic grouping of preferences than with just other records, e.g.
+  
+  user.preferred_color('cars')
+
+* Remove support for an options hash when specifying :for associations for preference
+
+== 0.0.1 / 2008-05-10
+
+* Initial public release

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008-2009 Aaron Pfeifer
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,185 @@
+== preferences
+
++preferences+ adds support for easily creating custom preferences for models.
+
+== Resources
+
+API
+
+* http://api.pluginaweek.org/preferences
+
+Bugs
+
+* http://pluginaweek.lighthouseapp.com/projects/13286-preferences
+
+Development
+
+* http://github.com/pluginaweek/preferences
+
+Source
+
+* git://github.com/pluginaweek/preferences.git
+
+== Description
+
+Preferences for models within an application, such as for users, is a pretty
+common idiom.  Although the rule of thumb is to keep the number of preferences
+available to a minimum, sometimes it's necessary if you want users to be able to
+disable things like e-mail notifications.
+
+Generally, basic preferences can be accomplished through simple designs, such as
+additional columns or a bit vector described and implemented by preference_fu[http://agilewebdevelopment.com/plugins/preferencefu].
+However, as you find the need for non-binary preferences and the number of
+preferences becomes unmanageable as individual columns in the database, the next
+step is often to create a separate "preferences" table.  This is where the
++preferences+ plugin comes in.
+
++preferences+ encapsulates this design by exposing preferences using simple
+attribute accessors on the model, hiding the fact that preferences are stored in
+a separate table and making it dead-simple to define and manage preferences.
+
+== Usage
+
+=== Defining preferences
+
+To define the preferences for a model, you can do so right within the model:
+
+  class User < ActiveRecord::Base
+    preference :hot_salsa
+    preference :dark_chocolate, :default => true
+    preference :color, :string
+    preference :favorite_number
+    preference :language, :string, :default => 'English'
+  end
+
+In the above model, 5 preferences have been defined:
+* hot_salsa
+* dark_chocolate
+* color
+* favorite_number
+* language
+
+For each preference, a data type and default value can be specified.  If no
+data type is given, it's assumed to be a boolean value.  If no default value is
+given, the default is assumed to be nil.
+
+=== Accessing preferences
+
+Once preferences have been defined for a model, they can be accessed either
+using the accessor methods that are generated for each preference or the generic
+methods that are not specific to a particular preference.
+
+==== Accessors
+
+There are several shortcut methods that are generated for each preference
+defined on a model.  These reflect the same set of methods (attribute accessors)
+that are generated for a model's columns.  Examples of these are shown below:
+
+Query methods:
+  user.prefers_hot_salsa?         # => false
+  user.preferred_language?        # => true
+
+Reader methods:
+  user.prefers_hot_salsa          # => false
+  user.preferred_language         # => "English"
+
+Writer methods:
+  user.prefers_hot_salsa = false        # => false
+  user.preferred_language = 'English'   # => "English"
+
+==== Generic methods
+
+Each preference accessor is essentially a wrapper for the various generic methods
+shown below:
+
+Query method:
+  user.prefers?(:hot_salsa)     # => false
+  user.preferred?(:language)    # => true
+
+Reader method:
+  user.prefers(:hot_salsa)      # => false
+  user.preferred(:language)     # => "English"
+
+Write method:
+  user.set_preference(:hot_salsa, false)      # => false
+  user.set_preference(:language, "English")   # => "English"
+
+=== Accessing all preferences
+
+To get the collection of all custom, stored preferences for a particular record,
+you can access the +stored_preferences+ has_many association which is automatically
+generated:
+
+  user.stored_preferences
+
+In addition to this, you can get a hash of all stored preferences *and* default
+preferences, by accessing the +preferences+ helper:
+
+  user.preferences  # => {"language"=>"English", "color"=>nil}
+
+This hash will contain the value for every preference that has been defined for
+the model, whether that's the default value or one that has been previously
+stored.
+
+A short-hand alternative for preferences is also available:
+
+  user.prefs  # => {"language"=>"English", "color"=>nil}
+
+=== Grouping preferences
+
+In addition to defining generic preferences for the owning record, you can also
+group preferences by ActiveRecord objects or arbitrary names.  This is best shown
+through an example:
+
+  user = User.find(:first)
+  car = Car.find(:first)
+  
+  user.preferred_color = 'red', car
+  # user.set_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.
+
+To access the preference for a particular record, you can use the same accessor
+methods as before:
+
+  user.preferred_color(car)
+  # user.preferred(:color, car) # The generic way
+
+In addition to grouping preferences for a particular record, you can also group
+preferences by name.  For example,
+
+  user = User.find(:first)
+  
+  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"}
+
+=== Saving preferences
+
+Note that preferences are not saved until the owning record is saved.
+Preferences are treated in a similar fashion to attributes.  For example,
+
+  user = user.find(:first)
+  user.attributes = {:prefers_hot_salsa => false, :preferred_color => 'red'}
+  user.save!
+
+Preferences are stored in a separate table called "preferences".
+
+== Testing
+
+Before you can run any tests, the following gem must be installed:
+* plugin_test_helper[http://github.com/pluginaweek/plugin_test_helper]
+
+To run against a specific version of Rails:
+
+  rake test RAILS_FRAMEWORK_ROOT=/path/to/rails
+
+== Dependencies
+
+* Rails 2.3 or later

data/Rakefile

@@ -0,0 +1,96 @@
+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.platform          = Gem::Platform::RUBY
+  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.require_path      = 'lib'
+  s.has_rdoc          = true
+  s.test_files        = Dir['test/**/*_test.rb']
+  
+  s.author            = 'Aaron Pfeifer'
+  s.email             = 'aaron@pluginaweek.org'
+  s.homepage          = 'http://www.pluginaweek.org'
+  s.rubyforge_project = 'pluginaweek'
+end
+  
+desc 'Default: run all tests.'
+task :default => :test
+
+desc "Test the #{spec.name} plugin."
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.test_files = spec.test_files
+  t.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  namespace :test do
+    desc "Test the #{spec.name} plugin with Rcov."
+    Rcov::RcovTask.new(:rcov) do |t|
+      t.libs << 'lib'
+      t.test_files = spec.test_files
+      t.rcov_opts << '--exclude="^(?!lib/|app/)"'
+      t.verbose = true
+    end
+  end
+rescue LoadError
+end
+
+desc "Generate documentation for the #{spec.name} plugin."
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = spec.name
+  rdoc.template = '../rdoc_template.rb'
+  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
+  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
+  Rake::SshDirPublisher.new('aaron@pluginaweek.org', "/home/aaron/api.pluginaweek.org/public/#{spec.name}", 'rdoc').upload
+end
+
+desc 'Publish the API docs and gem'
+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
+  
+  %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
+end

data/app/models/preference.rb

@@ -0,0 +1,65 @@
+# Represents a preferred value for a particular preference on a model.
+# 
+# == Grouped preferences
+# 
+# In addition to simple named preferences, preferences can also be grouped by
+# a particular value, be it a string or ActiveRecord object.  For example, a
+# User may have a preferred color for a particular Car.  In this case, the
+# +owner+ is the User record, the +name+ is "color", and the +group+ is the
+# Car record.  This allows preferences to have a sort of context around them.
+class Preference < ActiveRecord::Base
+  belongs_to :owner, :polymorphic => true
+  belongs_to :group, :polymorphic => true
+  
+  validates_presence_of :name, :owner_id, :owner_type
+  validates_presence_of :group_type, :if => :group_id?
+  
+  class << self
+    # Splits the given group into its corresponding id and type. For simple
+    # primitives, the id will be nil.  For complex types, specifically
+    # ActiveRecord objects, the id is the unique identifier stored in the
+    # database for the record.
+    # 
+    # For example,
+    # 
+    #   Preference.split_group('google')      # => [nil, "google"]
+    #   Preference.split_group(1)             # => [nil, 1]
+    #   Preference.split_group(User.find(1))  # => [1, "User"]
+    def split_group(group = nil)
+      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
+      end
+      
+      [group_id, group_type]
+    end
+  end
+  
+  # The definition of the preference as defined in the owner's model
+  def definition
+    # Optimize number of queries to the database by only looking up the actual
+    # owner record for STI cases when the definition can't be found in the
+    # stored owner type class
+    owner_type && (find_definition(owner_type.constantize) || find_definition(owner.class))
+  end
+  
+  # Typecasts the value depending on the preference definition's declared type
+  def value
+    value = read_attribute(:value)
+    value = definition.type_cast(value) if definition
+    value
+  end
+  
+  # Only searches for the group record if the group id is specified
+  def group_with_optional_lookup
+    group_id ? group_without_optional_lookup : group_type
+  end
+  alias_method_chain :group, :optional_lookup
+  
+  private
+    # Finds the definition for this preference in the given owner class.
+    def find_definition(owner_class)
+      owner_class.respond_to?(:preference_definitions) && owner_class.preference_definitions[name]
+    end
+end

data/init.rb

@@ -0,0 +1 @@
+require 'preferences'

data/lib/preferences.rb

@@ -0,0 +1,339 @@
+require 'preferences/preference_definition'
+
+# Adds support for defining preferences on ActiveRecord models.
+# 
+# == Saving preferences
+# 
+# Preferences are not automatically saved when they are set.  You must save
+# the record that the preferences were set on.
+# 
+# For example,
+# 
+#   class User < ActiveRecord::Base
+#     preference :notifications
+#   end
+#   
+#   u = User.new(:login => 'admin', :prefers_notifications => false)
+#   u.save!
+#   
+#   u = User.find_by_login('admin')
+#   u.attributes = {:prefers_notifications => true}
+#   u.save!
+# 
+# == Validations
+# 
+# Since the generated accessors for a preference allow the preference to be
+# treated just like regular ActiveRecord attributes, they can also be
+# validated against in the same way.  For example,
+# 
+#   class User < ActiveRecord::Base
+#     preference :color, :string
+#     
+#     validates_presence_of :preferred_color
+#     validates_inclusion_of :preferred_color, :in => %w(red green blue)
+#   end
+#   
+#   u = User.new
+#   u.valid?                        # => false
+#   u.errors.on(:preferred_color)   # => "can't be blank"
+#   
+#   u.preferred_color = 'white'
+#   u.valid?                        # => false
+#   u.errors.on(:preferred_color)   # => "is not included in the list"
+#   
+#   u.preferred_color = 'red'
+#   u.valid?                        # => true
+module Preferences
+  module MacroMethods
+    # Defines a new preference for all records in the model.  By default,
+    # preferences are assumed to have a boolean data type, so all values will
+    # be typecasted to true/false based on ActiveRecord rules.
+    # 
+    # Configuration options:
+    # * <tt>:default</tt> - The default value for the preference. Default is nil.
+    # 
+    # == Examples
+    # 
+    # The example below shows the various ways to define a preference for a
+    # particular model.
+    # 
+    #   class User < ActiveRecord::Base
+    #     preference :notifications, :default => false
+    #     preference :color, :string, :default => 'red'
+    #     preference :favorite_number, :integer
+    #     preference :data, :any # Allows any data type to be stored
+    #   end
+    # 
+    # All preferences are also inherited by subclasses.
+    # 
+    # == Associations
+    # 
+    # After the first preference is defined, the following associations are
+    # created for the model:
+    # * +stored_preferences+ - A collection of all the custom preferences
+    #   specified for a record.  This will not include default preferences
+    #   unless they have been explicitly set.
+    # 
+    # == Generated accessors
+    # 
+    # In addition to calling <tt>prefers?</tt> and +preferred+ on a record,
+    # you can also use the shortcut accessor methods that are generated when a
+    # preference is defined.  For example,
+    # 
+    #   class User < ActiveRecord::Base
+    #     preference :notifications
+    #   end
+    # 
+    # ...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>
+    # 
+    # Notice that there are two tenses used depending on the context of the
+    # preference.  Conventionally, <tt>prefers_notifications?</tt> is better
+    # for accessing boolean preferences, while +preferred_color+ is better for
+    # accessing non-boolean preferences.
+    # 
+    # Example:
+    # 
+    #   user = User.find(:first)
+    #   user.prefers_notifications?         # => false
+    #   user.prefers_notifications          # => false
+    #   user.preferred_color?               # => true
+    #   user.preferred_color                # => 'red'
+    #   user.preferred_color = 'blue'       # => 'blue'
+    #   
+    #   user.prefers_notifications = true
+    #   
+    #   car = Car.find(:first)
+    #   user.preferred_color = 'red', car   # => 'red'
+    #   user.preferred_color(car)           # => 'red'
+    #   user.preferred_color?(car)          # => true
+    #   
+    #   user.save!  # => true
+    def preference(name, *args)
+      unless included_modules.include?(InstanceMethods)
+        class_inheritable_hash :preference_definitions
+        self.preference_definitions = {}
+        
+        class_inheritable_hash :default_preferences
+        self.default_preferences = {}
+        
+        has_many :stored_preferences, :as => :owner, :class_name => 'Preference'
+        
+        after_save :update_preferences
+        
+        include Preferences::InstanceMethods
+      end
+      
+      # Create the definition
+      name = name.to_s
+      definition = PreferenceDefinition.new(name, *args)
+      self.preference_definitions[name] = definition
+      self.default_preferences[name] = definition.default_value
+      
+      # Create short-hand accessor methods, making sure that the name
+      # is method-safe in terms of what characters are allowed
+      name = name.gsub(/[^A-Za-z0-9_-]/, '').underscore
+      
+      # Query lookup
+      define_method("preferred_#{name}?") do |*group|
+        preferred?(name, group.first)
+      end
+      alias_method "prefers_#{name}?", "preferred_#{name}?"
+      
+      # Reader
+      define_method("preferred_#{name}") do |*group|
+        preferred(name, group.first)
+      end
+      alias_method "prefers_#{name}", "preferred_#{name}"
+      
+      # Writer
+      define_method("preferred_#{name}=") do |*args|
+        set_preference(*([name] + [args].flatten))
+      end
+      alias_method "prefers_#{name}=", "preferred_#{name}="
+      
+      definition
+    end
+  end
+  
+  module InstanceMethods
+    def self.included(base) #:nodoc:
+      base.class_eval do
+        alias_method :prefs, :preferences
+      end
+    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.
+    # 
+    # == Examples
+    # 
+    # A user with no stored values:
+    # 
+    #   user = User.find(:first)
+    #   user.preferences
+    #   => {"language"=>"English", "color"=>nil}
+    #   
+    # 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
+        
+        # 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
+        end
+        
+        preferences[preference.name] = preference.value
+        all_preferences
+      end
+    end
+    
+    # Queries whether or not a value is present for the given preference.
+    # This is dependent on how the value is type-casted.
+    # 
+    # == Examples
+    # 
+    #   class User < ActiveRecord::Base
+    #     preference :color, :string, :default => 'red'
+    #   end
+    #   
+    #   user = User.create
+    #   user.preferred(:color)              # => "red"
+    #   user.preferred?(:color)             # => true
+    #   user.preferred?(:color, 'cars')     # => true
+    #   user.preferred?(:color, Car.first)  # => true
+    #   
+    #   user.set_preference(:color, nil)
+    #   user.preferred(:color)              # => nil
+    #   user.preferred?(:color)             # => false
+    def preferred?(name, group = nil)
+      name = name.to_s
+      
+      value = preferred(name, group)
+      preference_definitions[name].query(value)
+    end
+    alias_method :prefers?, :preferred?
+    
+    # Gets the actual value stored for the given preference, or the default
+    # value if nothing is present.
+    # 
+    # == Examples
+    # 
+    #   class User < ActiveRecord::Base
+    #     preference :color, :string, :default => 'red'
+    #   end
+    #   
+    #   user = User.create
+    #   user.preferred(:color)            # => "red"
+    #   user.preferred(:color, 'cars')    # => "red"
+    #   user.preferred(:color, Car.first) # => "red"
+    #   
+    #   user.set_preference(:color, 'blue')
+    #   user.preferred(:color)            # => "blue"
+    def preferred(name, group = nil)
+      name = name.to_s
+      
+      if @preference_values && @preference_values[group] && @preference_values[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]
+      else
+        # Split the group being filtered
+        group_id, group_type = Preference.split_group(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
+      end
+      
+      value
+    end
+    alias_method :prefers, :preferred
+    
+    # Sets a new value for the given preference.  The actual Preference record
+    # is *not* created until this record is saved.  In this way, preferences
+    # act *exactly* the same as attributes.  They can be written to and
+    # validated against, but won't actually be written to the database until
+    # the record is saved.
+    # 
+    # == Examples
+    # 
+    #   user = User.find(:first)
+    #   user.set_preference(:color, 'red')              # => "red"
+    #   user.save!
+    #   
+    #   user.set_preference(:color, 'blue', Car.first)  # => "blue"
+    #   user.save!
+    def set_preference(name, value, group = nil)
+      name = name.to_s
+      
+      @preference_values ||= {}
+      @preference_values[group] ||= {}
+      @preference_values[group][name] = value
+      
+      value
+    end
+    
+    private
+      # 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|
+            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}
+              
+              # Find an existing preference or build a new one
+              preference = stored_preferences.find(:first, :conditions => attributes) ||  stored_preferences.build(attributes)
+              preference.value = value
+              preference.save!
+            end
+          end
+          
+          @preference_values = nil
+        end
+      end
+  end
+end
+
+ActiveRecord::Base.class_eval do
+  extend Preferences::MacroMethods
+end