acts_as_preferenced 0.9.0

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in ..gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 TODO: Write your name
+
+MIT License
+
+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,75 @@
+ActsAsPreferenced
+===========
+
+ActsAsPreferenced helps with handling of some settings you might want to store
+per-object (usually per-user) in Rails applications. It provides unified API to
+access those, ways to handle default values and some useful view helpers.
+Preferences may be divided into sections for easier categorization if many are
+present.
+
+Preferences can be stored in one of pluggable stores. Currently two stores are
+implemented: Field (stores in serialized db column) and Association (stores in
+associated table). One of the aims of this gem was to provide smooth transition
+between different stores - API stays the same for all of them, so you may start
+with preferences being stored in a serialized field and then transition to
+associated table.
+
+Example
+=======
+
+# Association store - use whatever association you like, there are just 2
+# requirements:
+# * associated table needs to have field for every preference (type matching)
+# * the name of the association cannot be "preferences", as it is used
+#   internally by ActsAsPreferenced
+
+	class User
+		attr_accessor :user_preferences
+
+		acts_as_preferenced( :association => :user_preferences ) do |config|
+			
+			# Just an integer preference with allowed range
+			config.preference :items_per_page, :section => :general, :choices => (1..100), :default => 20
+			# Define the whole section of preferences. :prefix => true means
+			# preference names will start with section name, so :flowers will become
+			# "likes_flowers?" method ("?" added because it's boolean)
+			config.section :likes, :prefix => true do |section|
+				section.preference :flowers, :default => true
+				# No default - if not set will be nil
+				section.preference :animals
+			end
+			# Enumerated preference with no section (it belongs to nil section)
+			config.preference :likes_people, :choices => [:no, :little, :yes]
+		end
+
+	end
+
+OR
+
+# Field store
+
+	class User
+		acts_as_preferenced( :field => :prefs, ...
+	end
+
+
+# Usage
+
+user = User.new
+user.likes_flowers? # True - default; as preference is boolean question mark is appended to getter
+user.likes_flowers = false
+user.likes_flowers? # False
+user.likes_animals? # Nil - no default present
+user.items_per_page = 120 # ArgumentError - value out of range
+user.likes_people = :yes
+user.likes_people # :yes - name might be misleading, but it's not boolean, so no question mark here 
+
+TODO
+====
+
+Helpers
+API documentation
+Migration generator for Association store.
+I18n tests.
+
+Copyright (c) 2009-2013 Marek Janukowicz, released under the MIT license

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/acts_as_preferenced.rb

@@ -0,0 +1,72 @@
+require 'acts_as_preferenced/version'
+require 'acts_as_preferenced/store/base'
+require 'acts_as_preferenced/store/association'
+require 'acts_as_preferenced/store/field'
+require 'acts_as_preferenced/preference'
+require 'acts_as_preferenced/section'
+
+module ActsAsPreferenced
+
+  def self.included( klass )
+    klass.extend( ActMethods )
+  end
+
+  module ActMethods
+
+    def acts_as_preferenced( options = {} )
+      options.assert_valid_keys( :field, :association, :translation_scope )
+      class_attribute :preference_config
+      include InstanceMethods
+      extend ClassMethods
+      if options[:field]
+        field = options[:field]
+        self.module_eval { serialize field, Hash } # TODO: move this line into config initialization
+        config = ActsAsPreferenced::Store::Field.new( self, field, options[:translation_scope] )
+        self.preference_config = config
+        yield config
+      elsif options[:association]
+        config = ActsAsPreferenced::Store::Association.new( self, options[:association], options[:translation_scope] )
+        self.preference_config = config
+        yield config
+      else
+        raise ArgumentError, "Invalid options for acts_as_preferenced: #{options.inspect}"
+      end
+    end
+
+  end
+
+  module ClassMethods
+
+    # TODO: Those methods should only be available when preferences are actually defined
+    def preference_sections
+      preference_config.sections.keys
+    end
+
+    def preferences_for_section( section )
+      preference_config.sections[section]
+    end
+
+    def all_preferences
+      preference_config.all_preferences
+    end
+
+  end
+
+  module InstanceMethods
+
+    def preference_value( name )
+      # TODO: implement
+    end
+
+    #def preferences
+    #  Preferences.configs[self.class].all
+    #end
+
+    #def preferences= (prefs)
+    #  Preferences.configs[self.class].all = prefs
+    #end
+  end
+
+end
+
+ActiveRecord::Base.send( :include, ActsAsPreferenced )

data/lib/acts_as_preferenced/preference.rb

@@ -0,0 +1,48 @@
+module ActsAsPreferenced
+  class Preference
+
+    attr_reader :name, :default, :section
+
+    def initialize( store, name, options = {} )
+      options.assert_valid_keys( :section, :label, :choices, :default )
+      @store, @name = store, name
+      @section = options[:section]
+      @label = options[:label]
+      @choices = options[:choices]
+      @default = options[:default]
+      store.sections[@section] << self
+      store.all_preferences << self
+    end
+
+    def label
+      if @store.translation_scope && @label.nil?
+        I18n.t( @name, :scope => [@store.translation_scope, @section] )
+      else
+        @label
+      end
+    end
+
+    # Options translations are stored under hardcoded :choices key in Preferences
+    # translation_scope. TODO: make it not hardcoded and make it work for other
+    # options than Array (eg. Range?)
+    # TODO: it should be cached
+    def choices
+      if @choices.is_a?( Array )
+        # TODO: I don't quite understand checking for an array here
+        @choices.collect { |choice| choice.is_a?( Array ) ? choice : [I18n.t( choice, :scope => [@store.translation_scope, :choices] ), opt] }
+      else
+        @choices
+      end
+    end
+
+    def value_valid?( value )
+      value = value.to_sym if value.is_a?( String )
+      if @choices
+        return @choices.include?( value )
+      else
+        return [true, false].include?( value )
+      end
+    end
+
+  end
+end

data/lib/acts_as_preferenced/section.rb

@@ -0,0 +1,23 @@
+module ActsAsPreferenced
+  
+  # This class only helps with defining of preference sections, not with storage
+  # (as I see no reason to make storage more complicated while bringing no real
+  # benefit)
+  class Section
+
+    # Options:
+    # * prefix - if true, section name will be prepended to all preferences
+    # defined within. False by default
+    def initialize( store, name, options = {} )
+      options.assert_valid_keys( :prefix )
+      @store, @name = store, name
+      @prefix = options[:prefix]
+    end
+
+    def preference( name, options = {} )
+      pref_name = (@prefix ? "#{@name}_#{name}".to_sym : name)
+      @store.preference( pref_name, options.merge( :section => @name ))
+    end
+
+  end
+end

data/lib/acts_as_preferenced/store/association.rb

@@ -0,0 +1,66 @@
+module ActsAsPreferenced
+  module Store
+
+    class Association < Base
+
+      attr_reader :association
+
+      def initialize(klass, assoc, translation_scope = nil)
+        super( klass, translation_scope )
+        @association = assoc
+        @klass.send( :define_method, "preferences" ) do
+          prefs = send( preference_config.association ) || send( "build_#{preference_config.association}" )
+          return prefs
+        end
+        @klass.send( :define_method, "preferences=" ) do |new_prefs|
+          pref_object = send( preference_config.association ) || send( "build_#{preference_config.association}" )
+          self.class.all_preferences.each do |pref|
+            old_value = pref_object.send( pref.name )
+            new_value = new_prefs[pref.name]
+            if new_value
+              stringified_value = new_value.is_a?( Symbol ) ? new_value.to_s : new_value
+              new_prefs[pref.name] = stringified_value
+            else
+              # Hack to allow boolean preferences to be set to false. This looks
+              # wrong from model point of view (if you mass assign preferences,
+              # absent boolean ones will be set to false even though default is
+              # true), but it works well for forms.
+              # TODO: find a way to make it work properly both for defaults and
+              # forms (if at all possible)
+              if pref.default == true || old_value == true
+                new_prefs[pref.name] = false
+              end
+            end
+          end
+          pref_object.attributes = new_prefs
+        end
+
+        @klass.send( :define_method, "save_preferences" ) do
+          pref_object = send( preference_config.association )
+          pref_object.save! if pref_object
+        end
+        @klass.before_save :save_preferences
+      end
+
+      def preference( name, options = {} )
+        options.assert_valid_keys( :section, :label, :choices, :default )
+        pref = Preference.new( self, name, options )
+        method_name = options[:choices] ? name.to_s : "#{name}?"
+        @klass.send( :define_method, method_name ) do
+          value = preferences[name]
+          value = pref.default if value.nil?
+          value &&= value.to_sym if value.is_a?( String )
+          value
+        end
+        @klass.send( :define_method, "#{name}=" ) do |value|
+          if pref.value_valid?( value )
+            preferences[name] = (value.is_a?( Symbol ) ? value.to_s : value)
+          else
+            raise ArgumentError, "Value #{value} invalid for preference #{pref.name}"
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/acts_as_preferenced/store/base.rb

@@ -0,0 +1,23 @@
+module ActsAsPreferenced
+  module Store
+
+    # Base class for all stores for preferences
+    class Base
+
+      attr_reader :sections, :all_preferences, :translation_scope
+
+      def initialize( klass, translation_scope = nil )
+        @klass = klass
+        @translation_scope = translation_scope
+        @sections = Hash.new { |h,k| h[k] = [] }
+        @all_preferences = []
+      end
+
+      def section( name, options = {} )
+        section = Section.new( self, name, options )
+        yield section
+      end
+    end
+
+  end
+end

data/lib/acts_as_preferenced/store/field.rb

@@ -0,0 +1,61 @@
+module ActsAsPreferenced
+  module Store
+
+    # This store holds preferences in a serialized field
+    class Field < Base
+
+      def initialize( klass, field, translation_scope = nil )
+        super( klass, translation_scope )
+        @field = field
+        @klass.send( :define_method, "preferences" ) do
+          prefs = read_attribute(field)
+          unless prefs
+            prefs = HashWithIndifferentAccess.new
+            write_attribute(field, prefs)
+          end
+          return prefs
+        end
+
+        @klass.send( :define_method, "preferences=" ) do |new_prefs|
+          self.class.all_preferences.each do |pref|
+            # Hack to allow boolean preferences to be set to false. This looks
+            # wrong from model point of view (if you mass assign preferences,
+            # absent boolean ones will be set to false even though default is
+            # true), but it works well for forms.
+            # TODO: find a way to make it work properly both for defaults and
+            # forms (if at all possible)
+            new_prefs[pref.name] ||= false if pref.default == true 
+          end
+          write_attribute(field, new_prefs)
+        end
+      end
+
+      def preference( name, options = {} )
+        options.assert_valid_keys( :section, :label, :choices, :default )
+        pref = Preference.new( self, name, options )
+        if options[:choices] # Choice
+          @klass.send( :define_method, "#{name}" ) do
+            # This symbolizes strings and leave other values (eg. numbers)
+            # intact
+            value = preferences[name].is_a?( String ) ? preferences[name].to_sym : preferences[name]
+            value || pref.default
+          end
+        else # Boolean
+          @klass.send( :define_method, "#{name}?" ) do
+            # We check for nil to allow "false" here
+            preferences[name].nil? ?  pref.default : preferences[name]
+          end
+        end
+        @klass.send( :define_method, "#{name}=" ) do |value|
+          if pref.value_valid?( value )
+            preferences[name] = value
+          else
+            raise ArgumentError, "Value #{value} invalid for preference #{pref.name}"
+          end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/acts_as_preferenced/version.rb

@@ -0,0 +1,3 @@
+module ActsAsPreferenced
+  VERSION = "0.9.0"
+end

data/test/acts_as_preferences_test.rb

@@ -0,0 +1,253 @@
+require 'test_helper'
+
+class ActsAsPreferencedFieldTest < ActiveSupport::TestCase
+
+  class User < FakeModel
+
+    attr_accessor :hold_preferences_here
+
+    acts_as_preferenced( :field => :hold_preferences_here ) do |config|
+      config.preference :items_per_page, :section => :general, :choices => (1..100), :default => 20
+      config.section :likes, :prefix => true do |section|
+        section.preference :flowers, :default => true
+        section.preference :animals 
+      end
+      config.preference :likes_people, :choices => [:no, :little, :yes]
+    end
+  end
+
+  def setup
+    @user = User.new
+  end
+
+  test "all preferences" do
+    all = User.all_preferences
+    assert_equal [:items_per_page, :likes_flowers, :likes_animals, :likes_people], all.collect(&:name)
+  end
+
+  test "preference sections" do
+    assert_equal [:general, nil, :likes], User.preference_sections
+    prefs = User.preferences_for_section( :sdjkfajsdf )
+    assert prefs.empty?
+    prefs = User.preferences_for_section( :likes )
+    assert_equal [:likes_flowers, :likes_animals], prefs.collect(&:name)
+    prefs = User.preferences_for_section( nil )
+    assert_equal [:likes_people], prefs.collect(&:name)
+  end
+
+  test "defaults" do
+    assert_equal true, @user.likes_flowers?
+    assert_equal 20, @user.items_per_page
+    assert_nil @user.likes_animals?
+    assert_nil @user.likes_people
+  end
+
+  test "set boolean" do
+    @user.likes_flowers = false
+    assert_equal false, @user.likes_flowers?
+  end
+
+  test "set integer" do
+    @user.items_per_page = 11
+    assert_equal 11, @user.items_per_page
+  end
+
+  test "set enumerable" do
+    @user.likes_people = :little
+    assert_equal :little, @user.likes_people
+  end
+  
+  test "set integer as boolean" do
+    assert_raises( ArgumentError ) do
+      @user.items_per_page = true
+    end
+  end
+
+  test "set integer out of range" do
+    assert_raises( ArgumentError ) do
+      @user.items_per_page = 0
+    end
+    assert_raises( ArgumentError ) do
+      @user.items_per_page = 101
+    end
+  end
+
+  test "set boolean as integer" do
+    assert_raises( ArgumentError ) do
+      @user.likes_flowers = 10
+    end
+  end
+
+  test "set enumerable out of range" do
+    assert_raises( ArgumentError ) do
+      @user.likes_people = :lot
+    end
+  end
+
+  test "set enumerable as string" do
+    @user.likes_people = "yes"
+    assert_equal :yes, @user.likes_people
+  end
+
+  test "set batch preferences" do
+    @user.likes_flowers = true
+    @user.likes_animals = true
+    @user.preferences = { :items_per_page => 23 }
+    assert_equal 23, @user.items_per_page
+    # No value for boolean defaulting to true - we assume it was unset
+    # TODO: in fact Rails handle this by sending hidden field with the same
+    # name, use the same approach
+    assert_equal false, @user.likes_flowers?
+    # No value for this boolean without default - reset it
+    # TODO: this also doesn't seem correct
+    assert_nil @user.likes_animals?
+  end
+end
+
+class ActsAsPreferencedAssociationTest < ActiveSupport::TestCase
+
+  class UserPreference < FakeModel
+    
+    # Tons of fakes here
+    attr_accessor :attributes
+
+    def items_per_page
+      attributes[:items_per_page]
+    end
+
+    def items_per_page= (value)
+      attributes[:items_per_page] = value
+    end
+
+    def likes_flowers?
+      attributes[:likes_flowers]
+    end
+
+    def likes_flowers= (value)
+      attributes[:likes_flowers] = value
+    end
+
+    def likes_animals?
+      attributes[:likes_animals]
+    end
+
+    def likes_animals= (value)
+      attributes[:likes_animals] = value
+    end
+
+    def likes_people?
+      attributes[:likes_people]
+    end
+
+    def likes_people= (value)
+      attributes[:likes_people] = value
+    end
+
+    alias_method :likes_flowers, :likes_flowers?
+    alias_method :likes_animals, :likes_animals?
+    alias_method :likes_people, :likes_people?
+    delegate :[], :[]=, :to => :attributes
+  end
+
+  class User < FakeModel
+
+    attr_accessor :user_preferences
+
+    acts_as_preferenced( :association => :user_preferences ) do |config|
+      config.preference :items_per_page, :section => :general, :choices => (1..100), :default => 20
+      config.section :likes, :prefix => true do |section|
+        section.preference :flowers, :default => true
+        section.preference :animals 
+      end
+      config.preference :likes_people, :choices => [:no, :little, :yes]
+    end
+  end
+
+  def setup
+    @user = User.new
+    @user.user_preferences = UserPreference.new
+  end
+
+  test "all preferences" do
+    all = User.all_preferences
+    assert_equal [:items_per_page, :likes_flowers, :likes_animals, :likes_people], all.collect(&:name)
+  end
+
+  test "preference sections" do
+    assert_equal [:general, nil, :likes], User.preference_sections
+    prefs = User.preferences_for_section( :sdjkfajsdf )
+    assert prefs.empty?
+    prefs = User.preferences_for_section( :likes )
+    assert_equal [:likes_flowers, :likes_animals], prefs.collect(&:name)
+    prefs = User.preferences_for_section( nil )
+    assert_equal [:likes_people], prefs.collect(&:name)
+  end
+
+  test "defaults" do
+    assert_equal true, @user.likes_flowers?
+    assert_equal 20, @user.items_per_page
+    assert_nil @user.likes_animals?
+    assert_nil @user.likes_people
+  end
+
+  test "set boolean" do
+    @user.likes_flowers = false
+    assert_equal false, @user.likes_flowers?
+  end
+
+  test "set integer" do
+    @user.items_per_page = 11
+    assert_equal 11, @user.items_per_page
+  end
+
+  test "set enumerable" do
+    @user.likes_people = :little
+    assert_equal :little, @user.likes_people
+  end
+  
+  test "set integer as boolean" do
+    assert_raises( ArgumentError ) do
+      @user.items_per_page = true
+    end
+  end
+
+  test "set integer out of range" do
+    assert_raises( ArgumentError ) do
+      @user.items_per_page = 0
+    end
+    assert_raises( ArgumentError ) do
+      @user.items_per_page = 101
+    end
+  end
+
+  test "set boolean as integer" do
+    assert_raises( ArgumentError ) do
+      @user.likes_flowers = 10
+    end
+  end
+
+  test "set enumerable out of range" do
+    assert_raises( ArgumentError ) do
+      @user.likes_people = :lot
+    end
+  end
+
+  test "set enumerable as string" do
+    @user.likes_people = "yes"
+    assert_equal :yes, @user.likes_people
+  end
+
+  test "set batch preferences" do
+    @user.likes_flowers = true
+    @user.likes_animals = false
+    @user.preferences = { :items_per_page => 23 }
+    assert_equal 23, @user.items_per_page
+    # No value for boolean defaulting to true - we assume it was unset
+    # TODO: in fact Rails handle this by sending hidden field with the same
+    # name, use the same approach
+    assert_equal false, @user.likes_flowers?
+    # No value for this boolean without default - reset it
+    # TODO: this also doesn't seem correct
+    assert_nil @user.likes_animals?
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,29 @@
+require 'rubygems'
+require 'test/unit'
+require 'set'
+gem 'activesupport', "> 3.0.0"
+require 'active_support/test_case'
+require 'active_record'
+require 'active_record/base'
+require 'acts_as_preferenced'
+require 'acts_as_preferenced/preference'
+require 'acts_as_preferenced/section'
+require 'acts_as_preferenced/store/base'
+require 'acts_as_preferenced/store/association'
+require 'acts_as_preferenced/store/field'
+
+# Class faking AR model behavior - needed to test the validations without the database
+class FakeModel < ActiveRecord::Base
+
+  self.abstract_class = true
+
+  def self.columns
+    @columns ||= [];
+  end
+
+  def self.column(name, sql_type = nil, default = nil, null = true)
+    columns << ActiveRecord::ConnectionAdapters::Column.new(name.to_s, default, sql_type.to_s, null)
+  end
+
+end
+

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: acts_as_preferenced
+version: !ruby/object:Gem::Version
+  version: 0.9.0
+  prerelease: 
+platform: ruby
+authors:
+- Marek Janukowicz
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-01-07 00:00:00.000000000 Z
+dependencies: []
+description: Preferences for Rails
+email:
+- marek@janukowicz.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/acts_as_preferenced.rb
+- lib/acts_as_preferenced/version.rb
+- lib/acts_as_preferenced/section.rb
+- lib/acts_as_preferenced/store/field.rb
+- lib/acts_as_preferenced/store/association.rb
+- lib/acts_as_preferenced/store/base.rb
+- lib/acts_as_preferenced/preference.rb
+- Gemfile
+- LICENSE.txt
+- Rakefile
+- README
+- test/acts_as_preferences_test.rb
+- test/test_helper.rb
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: ''
+test_files:
+- test/acts_as_preferences_test.rb
+- test/test_helper.rb