preferences 0.0.1

data/CHANGELOG

@@ -0,0 +1,5 @@
+*SVN*
+
+*0.0.1* (May 10th, 2008)
+
+* Initial public release

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 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

@@ -0,0 +1,146 @@
+== preferences
+
++preferences+ adds support for easily creating custom preferences for models.
+
+== Resources
+
+Wiki
+
+* http://wiki.pluginaweek.org/Preferences
+
+Source
+
+* http://svn.pluginaweek.org/trunk/plugins/preferences
+
+Development
+
+* http://dev.pluginaweek.org/browser/trunk/preferences
+
+== 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 accomplish 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 seprate "preferences" table.  This is where the +preferences+
+plugin comes in.
+
++preferences+ encapsulates this design by 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 considered a boolean value.  If not 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 shortcut methods that are generated for each preference or the generic methods
+that are not specific to a particular preference.
+
+==== Shortcut methods
+
+There are several shortcut methods that are generated.  They are shown below.
+
+Query methods:
+  user.prefers_hot_salsa?         # => false
+  user.prefers_dark_chocolate?    # => false
+
+Reader methods:
+  user.preferred_color      # => nil
+  user.preferred_language   # => "English"
+
+Writer methods:
+  user.prefers_hot_salsa = false        # => false
+  user.preferred_language = 'English'   # => "English"
+
+==== Generic methods
+
+Each shortcut method is essentially a wrapper for the various generic methods
+show below:
+
+Query method:
+  user.prefers?(:hot_salsa)       # => false
+  user.prefers?(:dark_chocolate)  # => false
+
+Reader method:
+  user.preferred(:color)      # => nil
+  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 preferences for a particular user, you can access
+the +preferences+ has_many association which is automatically generated:
+
+  user.preferences
+
+=== Preferences for other records
+
+In addition to defining generic preferences for the owning record, you can also
+define preferences for other records.  This is best shown through an example:
+
+  user = User.find(:first)
+  car = Car.find(:first)
+  
+  user.preferred_color = 'red', {:for => car}
+  # user.set_preference(:color, 'red', :for => car) # The generic way
+
+This will create a preference for the color "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(:for => car)
+  # user.preferred(:color, :for => car) # The generic way
+
+=== 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 = {:preferred_color => 'red'}
+  user.save!
+
+Preferences are stored in a separate table assumed to be called "preferences".
+
+== Testing
+
+Before you can run any tests, the following gem must be installed:
+* plugin_test_helper[http://wiki.pluginaweek.org/Plugin_test_helper]
+
+== Dependencies
+
+* plugins_plus[http://wiki.pluginaweek.org/Plugins_plus]

data/Rakefile

@@ -0,0 +1,80 @@
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'rake/contrib/sshpublisher'
+
+PKG_NAME           = 'preferences'
+PKG_VERSION        = '0.0.1'
+PKG_FILE_NAME      = "#{PKG_NAME}-#{PKG_VERSION}"
+RUBY_FORGE_PROJECT = 'pluginaweek'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the preferences plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the preferences plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Preferences'
+  rdoc.template = '../rdoc_template.rb'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+spec = Gem::Specification.new do |s|
+  s.name            = PKG_NAME
+  s.version         = PKG_VERSION
+  s.platform        = Gem::Platform::RUBY
+  s.summary         = 'Adds support for easily creating custom preferences for models'
+  
+  s.files           = FileList['{app,lib,test}/**/*'].to_a + %w(CHANGELOG init.rb MIT-LICENSE Rakefile README)
+  s.require_path    = 'lib'
+  s.autorequire     = 'preferences'
+  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'
+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', "#{PKG_FILE_NAME}.gem").upload
+end
+
+desc 'Publish the API documentation'
+task :pdoc => [:rdoc] do
+  Rake::SshDirPublisher.new('aaron@pluginaweek.org', "/home/aaron/api.pluginaweek.org/public/#{PKG_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
+  ruby_forge.login
+  
+  %w( gem tgz zip ).each do |ext|
+    file = "pkg/#{PKG_FILE_NAME}.#{ext}"
+    puts "Releasing #{File.basename(file)}..."
+    
+    ruby_forge.add_release(RUBY_FORGE_PROJECT, PKG_NAME, PKG_VERSION, file)
+  end
+end

data/app/models/preference.rb

@@ -0,0 +1,34 @@
+# Represents a preferred value for a particular preference on a model.
+# 
+# == Targeted preferences
+# 
+# In addition to simple named preferences, preferences can also be targeted for
+# a particular record.  For example, a User may have a preferred color for a
+# particular Car.  In this case, the +owner+ is the User, the +preference+ is
+# the color, and the +target+ is the Car.  This allows preferences to have a sort
+# of context around them.
+class Preference < ActiveRecord::Base
+  belongs_to  :owner,
+                :polymorphic => true
+  belongs_to  :preferenced,
+                :polymorphic => true
+  
+  validates_presence_of :attribute,
+                        :owner_id,
+                        :owner_type
+  validates_presence_of :preferenced_id,
+                        :preferenced_type,
+                          :if => Proc.new {|p| p.preferenced_id? || p.preferenced_type?}
+  
+  # The definition for the attribute
+  def definition
+    owner_type.constantize.preference_definitions[attribute] if owner_type
+  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
+end

data/init.rb

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

data/lib/preferences/preference_definition.rb

@@ -0,0 +1,50 @@
+module PluginAWeek #:nodoc:
+  # Adds support for defining preferences on ActiveRecord models.
+  module Preferences
+    # Represents the definition of a preference for a particular model
+    class PreferenceDefinition
+      def initialize(attribute, *args) #:nodoc:
+        options = args.extract_options!
+        options.assert_valid_keys(:default)
+        
+        @type = args.first ? args.first.to_s : 'boolean'
+        
+        # Create a column that will be responsible for typecasting
+        @column = ActiveRecord::ConnectionAdapters::Column.new(attribute.to_s, options[:default], @type == 'any' ? nil : @type)
+      end
+      
+      # The attribute which is being preferenced
+      def attribute
+        @column.name
+      end
+      
+      # The default value to use for the preference in case none have been
+      # previously defined      
+      def default_value
+        @column.default
+      end
+      
+      # Typecasts the value based on the type of preference that was defined
+      def type_cast(value)
+        if @type == 'any'
+          value
+        else
+          @column.type_cast(value)
+        end
+      end
+      
+      # Typecasts the value to true/false depending on the type of preference
+      def query(value)
+        unless value = type_cast(value)
+          false
+        else
+          if @column.number?
+            !value.zero?
+          else
+            !value.blank?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/preferences.rb

@@ -0,0 +1,235 @@
+require 'preferences/preference_definition'
+
+module PluginAWeek #:nodoc:
+  # 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!
+  module Preferences
+    def self.included(base) #:nodoc:
+      base.class_eval do
+        extend PluginAWeek::Preferences::MacroMethods
+      end
+    end
+    
+    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:
+      # * +default+ - 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:
+      # * +preferences+ - A collection of all the preferences specified for a record
+      # 
+      # == Generated shortcut methods
+      # 
+      # In addition to calling <tt>prefers?</tt> and +preferred+ on a record, you
+      # can also use the shortcut 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> - The same as calling <tt>record.prefers?(:notifications)</tt>
+      # * <tt>prefers_notifications=(value)</tt> - The same as calling <tt>record.set_preference(:notifications, value)</tt>
+      # * <tt>preferred_notifications</tt> - The same as called <tt>record.preferred(:notifications)</tt>
+      # * <tt>preferred_notifications=(value)</tt> - The same as calling <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 boolean preferences, while +preferred_color+ is better for non-boolean
+      # preferences.
+      # 
+      # Example:
+      # 
+      #   user = User.find(:first)
+      #   user.prefers_notifications?     # => false
+      #   user.prefers_color?             # => true
+      #   user.preferred_color            # => 'red'
+      #   user.preferred_color = 'blue'   # => 'blue'
+      #   
+      #   user.prefers_notifications = true
+      #   
+      #   car = Car.find(:first)
+      #   user.preferred_color = 'red', {:for => car}   # => 'red'
+      #   user.preferred_color(:for => car)             # => 'red'
+      #   user.prefers_color?(:for => car)              # => true
+      #   
+      #   user.save!  # => true
+      def preference(attribute, *args)
+        unless included_modules.include?(InstanceMethods)
+          class_inheritable_hash :preference_definitions
+          
+          has_many  :preferences,
+                      :as => :owner
+          
+          after_save :update_preferences
+          
+          include PluginAWeek::Preferences::InstanceMethods
+        end
+        
+        # Create the definition
+        attribute = attribute.to_s
+        definition = PreferenceDefinition.new(attribute, *args)
+        self.preference_definitions = {attribute => definition}
+        
+        # Create short-hand helper methods, making sure that the attribute
+        # is method-safe in terms of what characters are allowed
+        attribute = attribute.gsub(/[^A-Za-z0-9_-]/, '').underscore
+        class_eval <<-end_eval
+          def prefers_#{attribute}?(options = {})
+            prefers?(#{attribute.dump}, options)
+          end
+          
+          def prefers_#{attribute}=(args)
+            set_preference(*([#{attribute.dump}] + [args].flatten))
+          end
+          
+          def preferred_#{attribute}(options = {})
+            preferred(#{attribute.dump}, options)
+          end
+          
+          alias_method :preferred_#{attribute}=, :prefers_#{attribute}=
+        end_eval
+        
+        definition
+      end
+    end
+    
+    module InstanceMethods
+      # Queries whether or not a value has been specified for the given attribute.
+      # This is dependent on how the value is type-casted.
+      # 
+      # Configuration options:
+      # * +for+ - The record being preferenced
+      # 
+      # == Examples
+      # 
+      #   user = User.find(:first)
+      #   user.prefers?(:notifications)   # => true
+      #   
+      #   newsgroup = Newsgroup.find(:first)
+      #   user.prefers?(:notifications, :for => newsgroup)  # => false
+      def prefers?(attribute, options = {})
+        attribute = attribute.to_s
+        
+        value = preferred(attribute, options)
+        preference_definitions[attribute].query(value)
+      end
+      
+      # Gets the preferred value for the given attribute.
+      # 
+      # Configuration options:
+      # * +for+ - The record being preferenced
+      # 
+      # == Examples
+      # 
+      #   user = User.find(:first)
+      #   user.preferred(:color)    # => 'red'
+      #   
+      #   car = Car.find(:first)
+      #   user.preferred(:color, :for => car) # => 'black'
+      def preferred(attribute, options = {})
+        options.assert_valid_keys(:for)
+        attribute = attribute.to_s
+        
+        if @preference_values && @preference_values[attribute] && @preference_values[attribute].include?(options[:for])
+          value = @preference_values[attribute][options[:for]]
+        else
+          preferenced_id, preferenced_type = options[:for].id, options[:for].class.base_class.name.to_s if options[:for]
+          preference = preferences.find(:first, :conditions => {:attribute => attribute, :preferenced_id => preferenced_id, :preferenced_type => preferenced_type})
+          value = preference ? preference.value : preference_definitions[attribute].default_value
+        end
+        
+        value
+      end
+      
+      # Sets a new value for the given attribute.  The actual Preference record
+      # is *not* created until the actual record is saved.
+      # 
+      # Configuration options:
+      # * +for+ - The record being preferenced
+      # 
+      # == Examples
+      # 
+      #   user = User.find(:first)
+      #   user.set_preference(:notifications, false) # => false
+      #   user.save!
+      #   
+      #   newsgroup = Newsgroup.find(:first)
+      #   user.set_preference(:notifications, true, :for => newsgroup)  # => true
+      #   user.save!
+      def set_preference(attribute, value, options = {})
+        options.assert_valid_keys(:for)
+        attribute = attribute.to_s
+        
+        @preference_values ||= {}
+        @preference_values[attribute] ||= {}
+        @preference_values[attribute][options[:for]] = 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 |attribute, preferenced_records|
+              preferenced_records.each do |preferenced, value|
+                preferenced_id, preferenced_type = preferenced.id, preferenced.class.base_class.name.to_s if preferenced
+                attributes = {:attribute => attribute, :preferenced_id => preferenced_id, :preferenced_type => preferenced_type}
+                
+                # Find an existing preference or build a new one
+                preference = preferences.find(:first, :conditions => attributes) ||  preferences.build(attributes)
+                preference.value = value
+                preference.save!
+              end
+            end
+            
+            @preference_values = nil
+          end
+        end
+    end
+  end
+end
+
+ActiveRecord::Base.class_eval do
+  include PluginAWeek::Preferences
+end

data/test/app_root/app/models/car.rb

@@ -0,0 +1,2 @@
+class Car < ActiveRecord::Base
+end

data/test/app_root/app/models/user.rb

@@ -0,0 +1,7 @@
+class User < ActiveRecord::Base
+  preference :hot_salsa
+  preference :dark_chocolate, :default => true
+  preference :color, :string
+  preference :car, :integer
+  preference :language, :string, :default => 'English'
+end

data/test/app_root/config/environment.rb

@@ -0,0 +1,9 @@
+require 'config/boot'
+require "#{File.dirname(__FILE__)}/../../../../plugins_plus/boot"
+
+Rails::Initializer.run do |config|
+  config.plugin_paths << '..'
+  config.plugins = %w(plugins_plus preferences)
+  config.cache_classes = false
+  config.whiny_nils = true
+end

data/test/app_root/db/migrate/001_create_users.rb

@@ -0,0 +1,11 @@
+class CreateUsers < ActiveRecord::Migration
+  def self.up
+    create_table :users do |t|
+      t.string :login, :null => false
+    end
+  end
+  
+  def self.down
+    drop_table :users
+  end
+end

data/test/app_root/db/migrate/002_create_cars.rb

@@ -0,0 +1,11 @@
+class CreateCars < ActiveRecord::Migration
+  def self.up
+    create_table :cars do |t|
+      t.string :name, :null => false
+    end
+  end
+  
+  def self.down
+    drop_table :cars
+  end
+end

data/test/app_root/db/migrate/003_migrate_preferences_to_version_1.rb

@@ -0,0 +1,9 @@
+class MigratePreferencesToVersion1 < ActiveRecord::Migration
+  def self.up
+    Rails::Plugin.find(:preferences).migrate(1)
+  end
+  
+  def self.down
+    Rails::Plugin.find(:preferences).migrate(0)
+  end
+end