ee_preferences 0.4.3

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NDc1NTg2MzkyYmYxMGRmMDgxNzY0M2EyYTRmMTczYThlZTgxN2IxNg==
+  data.tar.gz: !binary |-
+    Njk2N2U0OTBmYWY2NjVkM2Y5N2NhNzIxNjZmMWRjOWUyN2I4ZjZjMg==
+SHA512:
+  metadata.gz: !binary |-
+    Mjc5MmQ5MmYwYzhhNWVmOGMyMmY5NTEwNDI1OThhNDMxNWFkYzRmNjdlNGI4
+    YjkxNjJhZDU0M2NiMTIyMzU5Mzg5ZjFlNzQwMGUyMWJiY2M2ZTBkNDIxZTZm
+    Y2NiODY3N2M1NmY2ZWM5NjA3NDAwNmRjYjk1MGJlODJlOGIyNDA=
+  data.tar.gz: !binary |-
+    MWUxY2M4MTM4MTU4ZTc0NmQ0ZGUxMTZhMWIyMWM4NTkxYmJhN2M0OTczNGIz
+    ZjcyOGQxMGE5YTdlZGU3MDUwMDYzZmI5ZGQ4Y2MwNGE5ODQ3NjZlMzAxODE1
+    ZjhkZWEyZjY1MDQzYWFjOGI2YmJiMjVjMzc1YjZlNTMxMjAwMGI=

data/.gitignore

@@ -0,0 +1,8 @@
+*.gem
+coverage
+pkg
+rdoc
+test/app_root/log
+test/app_root/script
+Gemfile.lock
+.idea/*

data/.travis.yml

@@ -0,0 +1,3 @@
+rvm:
+  - 1.9.2
+  - 1.8.7

data/CHANGELOG.rdoc

@@ -0,0 +1,85 @@
+== master
+== 0.4.3 / 2014-09-08
+
+* Fix #named_scope to #scope
+
+== 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/Gemfile

@@ -0,0 +1,3 @@
+source "http://www.rubygems.org"
+ 
+gemspec

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,224 @@
+== preferences http://travis-ci.org/pluginaweek/preferences.png
+
++preferences+ adds support for easily creating custom preferences for models.
+
+== Resources
+
+API
+
+* http://rdoc.info/github/pluginaweek/preferences/master/frames
+
+Bugs
+
+* http://github.com/pluginaweek/preferences/issues
+
+Development
+
+* http://github.com/pluginaweek/preferences
+
+Testing
+
+* http://travis-ci.org/pluginaweek/preferences
+
+Source
+
+* git://github.com/pluginaweek/preferences.git
+
+Mailing List
+
+* http://groups.google.com/group/pluginaweek-talk
+
+== 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,36 @@
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run all tests.'
+task :default => :test
+
+desc "Test preferences."
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.test_files = Dir['test/**/*_test.rb']
+  t.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  namespace :test do
+    desc "Test preferences with Rcov."
+    Rcov::RcovTask.new(:rcov) do |t|
+      t.libs << 'lib'
+      t.test_files = Dir['test/**/*_test.rb']
+      t.rcov_opts << '--exclude="^(?!lib/|app/)"'
+      t.verbose = true
+    end
+  end
+rescue LoadError
+end
+
+desc "Generate documentation for preferences."
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'preferences'
+  rdoc.options << '--line-numbers' << '--inline-source' << '--main=README.rdoc'
+  rdoc.rdoc_files.include('README.rdoc', 'CHANGELOG.rdoc', 'LICENSE', 'lib/**/*.rb', 'app/**/*.rb')
+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

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/init.rb

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

data/lib/preferences/preference_definition.rb

@@ -0,0 +1,56 @@
+module Preferences
+  # Represents the definition of a preference for a particular model
+  class PreferenceDefinition
+    # The data type for the content stored in this preference type
+    attr_reader :type
+    
+    def initialize(name, *args) #:nodoc:
+      options = args.extract_options!
+      options.assert_valid_keys(:default, :group_defaults)
+      
+      @type = args.first ? args.first.to_sym : :boolean
+      
+      # Create a column that will be responsible for typecasting
+      @column = ActiveRecord::ConnectionAdapters::Column.new(name.to_s, options[:default], @type == :any ? nil : @type.to_s)
+      
+      @group_defaults = (options[:group_defaults] || {}).inject({}) do |defaults, (group, default)|
+        defaults[group.is_a?(Symbol) ? group.to_s : group] = type_cast(default)
+        defaults
+      end
+    end
+    
+    # The name of the preference
+    def name
+      @column.name
+    end
+    
+    # The default value to use for the preference in case none have been
+    # previously defined
+    def default_value(group = nil)
+      @group_defaults.include?(group) ? @group_defaults[group] : @column.default
+    end
+    
+    # Determines whether column backing this preference stores numberic values
+    def number?
+      @column.number?
+    end
+    
+    # Typecasts the value based on the type of preference that was defined.
+    # This uses ActiveRecord's typecast functionality so the same rules for
+    # typecasting a model's columns apply here.
+    def type_cast(value)
+      @type == :any ? value : @column.type_cast(value)
+    end
+    
+    # Typecasts the value to true/false depending on the type of preference
+    def query(value)
+      if !(value = type_cast(value))
+        false
+      elsif number?
+        !value.zero?
+      else
+        !value.blank?
+      end
+    end
+  end
+end

data/lib/preferences/version.rb

@@ -0,0 +1,3 @@
+module Preferences
+  VERSION = '0.4.3'
+end