optimeez_preferences 0.4.2

data/CHANGELOG.rdoc

@@ -0,0 +1,82 @@
+== master
+
+== 0.4.2 / 2010-04-17
+
+* Fix #preferences lookup not typecasting values
+
+== 0.4.1 / 2010-03-07
+
+* Add support for per-group default preferences
+* Fix unsaved boolean preferences getting overridden by defaults if value is false
+
+== 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
+
+== 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,216 @@
+== preferences
+
++preferences+ adds support for easily creating custom preferences for models.
+
+== Resources
+
+API
+
+* http://rdoc.info/projects/pluginaweek/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
+
+=== 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:
+
+  class User < ActiveRecord::Base
+    preference :hot_salsa
+    preference :dark_chocolate, :default => true
+    preference :color, :string
+    preference :favorite_number
+    preference :language, :string, :default => 'English', :group_defaults => {:chat => 'Spanish'}
+  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.write_preference(:hot_salsa, false)      # => false
+  user.write_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.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.
+
+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(: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".
+
+=== 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:
+* 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,75 @@
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+
+spec = Gem::Specification.new do |s|
+  s.name              = 'preferences'
+  s.version           = '0.4.2'
+  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,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']
+  
+  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
+end
+
+desc 'Publish the release files to RubyForge.'
+task :release => :package do
+  require 'rake/gemcutter'
+  
+  Rake::Gemcutter::Tasks.new(spec)
+  Rake::Task['gem:push'].invoke
+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.is_a?(Symbol) ? group.to_s : 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