preferences 0.0.1 → 0.1.0

data/CHANGELOG

@@ -1,5 +1,20 @@
 *SVN*
 
+*0.1.0* (June 19th, 2008)
+
+* 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.preferences_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* (May 10th, 2008)
 
 * Initial public release

data/README

@@ -8,14 +8,18 @@ Wiki
 
 * http://wiki.pluginaweek.org/Preferences
 
-Source
+API
 
-* http://svn.pluginaweek.org/trunk/plugins/preferences
+* http://api.pluginaweek.org/preferences
 
 Development
 
 * http://dev.pluginaweek.org/browser/trunk/preferences
 
+Source
+
+* http://svn.pluginaweek.org/trunk/preferences
+
 == Description
 
 Preferences for models within an application, such as for users, is a pretty
@@ -23,11 +27,11 @@ 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
+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 seprate "preferences" table.  This is where the +preferences+
+step is often to create a separate "preferences" table.  This is where the +preferences+
 plugin comes in.
 
 +preferences+ encapsulates this design by hiding the fact that preferences are
@@ -56,7 +60,7 @@ In the above model, 5 preferences have been defined:
 * 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
+data type is given, it's considered a boolean value.  If no default value is
 given, the default is assumed to be nil.
 
 === Accessing preferences
@@ -84,7 +88,7 @@ Writer methods:
 ==== Generic methods
 
 Each shortcut method is essentially a wrapper for the various generic methods
-show below:
+shown below:
 
 Query method:
   user.prefers?(:hot_salsa)       # => false
@@ -100,21 +104,32 @@ Write method:
 
 === 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:
+To get the collection of all custom, stored preferences for a particular record,
+you can access the +preferences+ has_many association which is automatically
+generated:
 
   user.preferences
 
-=== Preferences for other records
+In addition to this, you can get a hash of all stored preferences *and* default
+preferences, by accessing the +preference_values+ helper:
+
+  user.preference_values  # => {"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.
+
+=== Grouping preferences
 
 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:
+group preferences by ActiveRecord objects or basic names.  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
+  user.preferred_color = 'red', car
+  # user.set_preference(:color, 'red', 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.
@@ -122,8 +137,22 @@ 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
+  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.preference_values                # => {"color"=>nil, "automobiles"=>{"color"=>"red"}, "clothing=>{"color=>"tan"}}
+  user.preference_values('automobiles') # => {"color"=>"red"}
 
 === Saving preferences
 
@@ -134,13 +163,18 @@ are treated in a similar fashion to attributes.  For example,
   user.attributes = {:preferred_color => 'red'}
   user.save!
 
-Preferences are stored in a separate table assumed to be called "preferences".
+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://wiki.pluginaweek.org/Plugin_test_helper]
 
+To run against a specific version of Rails:
+
+  rake test RAILS_FRAMEWORK_ROOT=/path/to/rails
+
 == Dependencies
 
+* Rails 2.1 or later
 * plugins_plus[http://wiki.pluginaweek.org/Plugins_plus]

data/Rakefile

@@ -4,7 +4,7 @@ require 'rake/gempackagetask'
 require 'rake/contrib/sshpublisher'
 
 PKG_NAME           = 'preferences'
-PKG_VERSION        = '0.0.1'
+PKG_VERSION        = '0.1.0'
 PKG_FILE_NAME      = "#{PKG_NAME}-#{PKG_VERSION}"
 RUBY_FORGE_PROJECT = 'pluginaweek'
 
@@ -68,7 +68,7 @@ desc 'Publish the release files to RubyForge.'
 task :release => [:gem, :package] do
   require 'rubyforge'
   
-  ruby_forge = RubyForge.new
+  ruby_forge = RubyForge.new.configure
   ruby_forge.login
   
   %w( gem tgz zip ).each do |ext|

data/app/models/preference.rb

@@ -10,15 +10,27 @@
 class Preference < ActiveRecord::Base
   belongs_to  :owner,
                 :polymorphic => true
-  belongs_to  :preferenced,
+  belongs_to  :group,
                 :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?}
+  validates_presence_of :group_type,
+                          :if => :group_id?
+  
+  class << self
+    # Splits the given group into its corresponding id and type
+    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
+      
+      return group_id, group_type
+    end
+  end
   
   # The definition for the attribute
   def definition
@@ -31,4 +43,10 @@ class Preference < ActiveRecord::Base
     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
 end

data/lib/preferences.rb

@@ -79,22 +79,26 @@ module PluginAWeek #:nodoc:
       # 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?         # => 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.preferred_color = 'red', car   # => 'red'
+      #   user.preferred_color(car)           # => 'red'
+      #   user.prefers_color?(car)            # => true
       #   
       #   user.save!  # => true
       def preference(attribute, *args)
         unless included_modules.include?(InstanceMethods)
           class_inheritable_hash :preference_definitions
+          self.preference_definitions = {}
+          
+          class_inheritable_hash :default_preference_values
+          self.default_preference_values = {}
           
           has_many  :preferences,
                       :as => :owner
@@ -107,73 +111,120 @@ module PluginAWeek #:nodoc:
         # Create the definition
         attribute = attribute.to_s
         definition = PreferenceDefinition.new(attribute, *args)
-        self.preference_definitions = {attribute => definition}
+        self.preference_definitions[attribute] = definition
+        self.default_preference_values[attribute] = definition.default_value
         
         # 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
+        
+        # Query lookup
+        define_method("prefers_#{attribute}?") do |*group|
+          prefers?(attribute, group.first)
+        end
+        
+        # Writer
+        define_method("prefers_#{attribute}=") do |*args|
+          set_preference(*([attribute] + [args].flatten))
+        end
+        alias_method "preferred_#{attribute}=", "prefers_#{attribute}="
+        
+        # Reader
+        define_method("preferred_#{attribute}") do |*group|
+          preferred(attribute, group.first)
+        end
         
         definition
       end
     end
     
     module InstanceMethods
+      # 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.preference_values
+      #   => {"language"=>"English", "color"=>nil}
+      #   
+      # A user with stored values for a particular group:
+      #   user.preferred_color = 'red', 'cars'
+      #   user.preference_values
+      #   => {"language"=>"English", "color"=>nil, "cars"=>{"language=>"English", "color"=>"red"}}
+      #   
+      # Getting preference values for the owning record:
+      #   user.preference_values(nil)
+      #   => {"language"=>"English", "color"=>nil}
+      #   
+      # Getting preference values for a particular group:
+      #   user.preference_values('cars')
+      #   => {"language"=>"English", "color"=>"red"}
+      def preference_values(*args)
+        if args.any?
+          group = args.first
+          group_id, group_type = Preference.split_group(group)
+          conditions = {:group_id => group_id, :group_type => group_type}
+        else
+          conditions = {}
+        end
+        
+        # Find all of the stored preferences
+        stored_preferences = preferences.find(:all, :conditions => conditions)
+        
+        # Hashify attribute -> value or group -> attribute -> value
+        stored_preferences.inject(self.class.default_preference_values.dup) do |preferences, preference|
+          if group = preference.group
+            preference_group = preferences[group] ||= self.class.default_preference_values.dup
+          else
+            preference_group = preferences
+          end
+          
+          preference_group[preference.attribute] = preference.value
+          preferences
+        end
+      end
+      
       # 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
+      #   user.prefers?(:notifications)             # => true
+      #   
+      #   user.prefers(:notifications, 'error')     # => true
       #   
       #   newsgroup = Newsgroup.find(:first)
-      #   user.prefers?(:notifications, :for => newsgroup)  # => false
-      def prefers?(attribute, options = {})
+      #   user.prefers?(:notifications, newsgroup)  # => false
+      def prefers?(attribute, group = nil)
         attribute = attribute.to_s
         
-        value = preferred(attribute, options)
+        value = preferred(attribute, group)
         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'
+      #   user.preferred(:color)          # => 'red'
+      #   
+      #   user.preferred(:color, 'cars')  # => 'blue'
       #   
       #   car = Car.find(:first)
-      #   user.preferred(:color, :for => car) # => 'black'
-      def preferred(attribute, options = {})
-        options.assert_valid_keys(:for)
+      #   user.preferred(:color, car)     # => 'black'
+      def preferred(attribute, group = nil)
         attribute = attribute.to_s
         
-        if @preference_values && @preference_values[attribute] && @preference_values[attribute].include?(options[:for])
-          value = @preference_values[attribute][options[:for]]
+        if @preference_values && @preference_values[attribute] && @preference_values[attribute].include?(group)
+          value = @preference_values[attribute][group]
         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})
+          group_id, group_type = Preference.split_group(group)
+          preference = preferences.find(:first, :conditions => {:attribute => attribute, :group_id => group_id, :group_type => group_type})
           value = preference ? preference.value : preference_definitions[attribute].default_value
         end
         
@@ -183,9 +234,6 @@ module PluginAWeek #:nodoc:
       # 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)
@@ -193,15 +241,14 @@ module PluginAWeek #:nodoc:
       #   user.save!
       #   
       #   newsgroup = Newsgroup.find(:first)
-      #   user.set_preference(:notifications, true, :for => newsgroup)  # => true
+      #   user.set_preference(:notifications, true, newsgroup)  # => true
       #   user.save!
-      def set_preference(attribute, value, options = {})
-        options.assert_valid_keys(:for)
+      def set_preference(attribute, value, group = nil)
         attribute = attribute.to_s
         
         @preference_values ||= {}
         @preference_values[attribute] ||= {}
-        @preference_values[attribute][options[:for]] = value
+        @preference_values[attribute][group] = value
         
         value
       end
@@ -211,10 +258,10 @@ module PluginAWeek #:nodoc:
         # 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}
+            @preference_values.each do |attribute, grouped_records|
+              grouped_records.each do |group, value|
+                group_id, group_type = Preference.split_group(group)
+                attributes = {:attribute => attribute, :group_id => group_id, :group_type => group_type}
                 
                 # Find an existing preference or build a new one
                 preference = preferences.find(:first, :conditions => attributes) ||  preferences.build(attributes)