aguids-positionable 0.2.1

data/lib/positionable.rb

@@ -0,0 +1,362 @@
+module Positionable
+
+  # This +acts_as+ extension provides the capabilities for sorting and reordering a number of objects in a list.
+  # The class that has this specified needs to have a column defined as an integer on the mapped database table
+  # to store the list's position. The default is +position+.
+  #
+  # Todo list example:
+  #
+  #   class TodoList < ActiveRecord::Base
+  #     has_many :todo_items, :order => "position"
+  #   end
+  #
+  #   class TodoItem < ActiveRecord::Base
+  #     belongs_to :todo_list
+  #     acts_as_positionable :scope => :todo_list_id
+  #   end
+  #
+  #   todo_list.first.move_to_bottom
+  #   todo_list.last.move_higher
+  module ClassMethods
+    # Configuration options are:
+    #
+    # * +column+ - specifies the column name to use for keeping the position integer (default: +position+)
+    # * +scope+ - restricts what is to be considered a list. Expects a symbol representing a object attribute
+    # * +conditions+ - activerecord find conditions to evaluate if the record should be inserted on the list
+    # * +list_name+ - the name for this list's act_as_positionable declaration (default: +:default+)
+    def acts_as_positionable(options = {})
+      options = { :list_name => :default, :column => "position" }.merge(options)
+      
+      cattr_accessor :positionable unless respond_to?(:positionable)
+      self.positionable ||= Positionable::Wrapper.new
+      self.positionable << options
+      
+      named_scope :ascending, lambda { |list_name|
+        { :order => self.positionable.lists[list_name][:column] }
+      }
+      named_scope :descending, lambda { |list_name|
+        { :order => "#{self.positionable.lists[list_name][:column]} DESC" }
+      }
+      named_scope :conditions, lambda { |list_name|
+        { :conditions => self.positionable.lists[list_name][:conditions] }
+      }
+
+      class_eval <<-EOV
+        include Positionable::InstanceMethods
+        
+        def acts_as_positionable_class
+          ::#{self.name}
+        end
+        
+        before_create  :add_to_lists
+        before_update  :update_lists
+        before_destroy :remove_from_lists
+      EOV
+    end
+  end
+
+  module EvalSupport
+    def conditions_to_eval(conditions)
+      case conditions
+        when Array  then array_conditions_to_eval(conditions)
+        when Hash   then hash_conditions_to_eval(conditions)
+        when String then string_conditions_to_eval(conditions)
+      end
+    end
+    
+    def array_conditions_to_eval(conditions)
+      string_conditions_to_eval ActiveRecord::Base.send(:sanitize_sql_array, conditions)
+    end
+
+    def hash_conditions_to_eval(conditions)
+      conditions.inject("") do |str, (attribute, value)|
+        str << ' && ' unless str.blank?
+        str << "#{attribute} == "
+        str << case value
+          when String then "\'#{value}\'"
+          when nil then 'nil'
+          else value.to_s
+        end
+      end
+    end
+    
+    def string_conditions_to_eval(conditions)
+      conditions.gsub(' = ', ' == ').gsub(/ and /i, ' && ').gsub(/ or /i, ' || ')
+    end
+    
+    module_function :conditions_to_eval, :array_conditions_to_eval, :hash_conditions_to_eval, :string_conditions_to_eval
+  end
+
+  # Wrapper class for all the lists' options
+  class Wrapper
+    attr_accessor :lists
+    def initialize
+      self.lists = {}
+    end
+    
+    def <<(options={})
+      options[:conditions_to_eval] = Positionable::EvalSupport.conditions_to_eval(options[:conditions])
+      self.lists[options.delete(:list_name)] = options
+    end
+    
+    def has_scope?(list_name)
+      !!lists[list_name][:scope]
+    end
+    
+    def scope(list_name)
+      lists[list_name][:scope].is_a?(Array) ? lists[list_name][:scope] : [lists[list_name][:scope]]
+    end
+    
+    def has_conditions?(list_name)
+      !!lists[list_name][:conditions]
+    end
+    
+    def conditions(list_name)
+      lists[list_name][:conditions]
+    end
+  end
+  
+  # All the methods available to a record that has had <tt>acts_as_positionable</tt> specified. Each method works
+  # by assuming the object to be the item in the list, so <tt>chapter.move_lower</tt> would move that chapter
+  # lower in the list of all chapters. Likewise, <tt>chapter.first?</tt> would return +true+ if that chapter is
+  # the first in the list of all chapters.
+  module InstanceMethods
+    # Insert the item at the given position (defaults to the top position).
+    def insert_at(position = :top, list_name = :default)
+      if !position.is_a?(Symbol) && position <= 0
+        position = :top
+      elsif !position.is_a?(Symbol) && position > bottom_position_in_list(list_name) && position != 1
+        position = :bottom
+      end
+      insert_at_position(list_name, position)
+    end
+    
+    def insert_at_top(list_name = :default)
+      insert_at_position(list_name, :top)
+    end
+    
+    def insert_at_bottom(list_name = :default)
+      insert_at_position(list_name, :bottom)
+    end
+
+    # Swap positions with the next lower item, if one exists.
+    def move_lower(list_name = :default)
+      lower = lower_item
+      insert_at_position(list_name, lower.list_position) if lower
+    end
+    alias_method :move_down, :move_lower
+
+    # Swap positions with the next higher item, if one exists.
+    def move_higher(list_name = :default)
+      higher = higher_item
+      insert_at_position(list_name, higher.list_position) if higher
+    end
+    alias_method :move_up, :move_higher
+
+    # Move to the bottom of the list.
+    def move_to_bottom(list_name = :default)
+      insert_at_position(list_name, :bottom) if in_list?
+    end
+
+    # Move to the top of the list.
+    def move_to_top(list_name = :default)
+      insert_at_position(list_name, :top) if in_list?
+    end
+
+    # True if the record is the first in the list.
+    def first?(list_name = :default)
+      in_list? && list_position == top_position_in_list(list_name)
+    end
+
+    # True if the record is the last in the list.
+    def last?(list_name = :default)
+      in_list? && list_position == bottom_position_in_list(list_name)
+    end
+
+    # Returns the next higher item in the list.
+    def higher_item(list_name = :default)
+      return nil unless in_list?
+      scoped(list_name).descending(list_name).first(:conditions => options_for_position(list_name, '<'))
+    end
+    alias_method :previous_item, :higher_item
+
+    # Returns the next lower item in the list.
+    def lower_item(list_name = :default)
+      return nil unless in_list?
+      scoped(list_name).ascending(list_name).first(:conditions => options_for_position(list_name, '>'))
+    end
+    alias_method :next_item, :lower_item
+
+    # True if the record is in the list.
+    def in_list?(list_name = :default)
+      !list_position(list_name).nil?
+    end
+    
+    # Returns the record list position for the list.
+    def list_position(list_name = :default)
+      send position_column(list_name)
+    end
+
+    # Removes the record from the list and shift other items accordingly.
+    def remove_from_list(list_name = :default)
+      if in_list?
+        acts_as_positionable_class.transaction do
+          decrement_positions_on_lower_items(list_name)
+          update_attribute position_column(list_name), nil
+        end
+      end
+    end
+
+    protected
+      # Flag the record's position on all lists as long as it meets the lists' conditions.
+      # No save or update is performed.
+      def add_to_lists
+        positionable.lists.each_key do |list_name|
+          if !positionable.has_conditions?(list_name) || meet_conditions?(list_name)
+            add_to_list_bottom(list_name)
+          end
+        end
+      end
+
+      # Flag the record's position on a list as after the current last item.
+      # No save or update is performed
+      def add_to_list_bottom(list_name)
+        self[position_column(list_name)] = bottom_position_in_list(list_name) + 1
+      end
+
+      # Remove the record from all lists.
+      def remove_from_lists
+        positionable.lists.each_key do |list_name|
+          remove_from_list(list_name)
+        end
+      end
+
+      # Remove and insert the record according to the lists' scopes and conditions.
+      def update_lists
+        @old_record = acts_as_positionable_class.find self.id
+        positionable.lists.each_key do |list_name|
+          if positionable.has_scope?(list_name) && scope_changed?(list_name)
+            @old_record.remove_from_list(list_name)
+            add_to_list_bottom(list_name)
+          end
+          
+          if positionable.has_conditions?(list_name) && conditions_changed?(list_name)
+            if in_list?(list_name)
+              @old_record.remove_from_list(list_name)
+              self[position_column(list_name)] = nil
+            else
+              add_to_list_bottom(list_name)
+            end
+          end
+        end
+      end
+      
+      # True if this save action changed the record according to the list's scope.
+      def scope_changed?(list_name)
+        positionable.scope(list_name).each do |scope|
+          return true if @old_record.send(scope) != self.send(scope)
+        end
+        false
+      end
+      
+      # True if this save action changed the record according to the list's conditions.
+      def conditions_changed?(list_name)
+        @old_record.meet_conditions?(list_name) != self.meet_conditions?(list_name)
+      end
+
+      # True if the record meets the list conditions.
+      def meet_conditions?(list_name)
+        eval positionable.lists[list_name][:conditions_to_eval]
+      end
+
+      # Returns an activerecord class scope, based on the list's scope and conditions.
+      def scoped(list_name)
+        chain = acts_as_positionable_class
+        if positionable.has_scope?(list_name)
+          positionable.scope(list_name).each { |scope| chain = chain.send("scoped_by_#{scope}", send(scope)) }
+        end
+        chain = chain.send(:conditions, list_name) if positionable.has_conditions?(list_name)
+        chain
+      end
+
+      # Returns the position for the first item in list.
+      # Lists with gaps might have a number other than 1
+      def top_position_in_list(list_name)
+        top_item(list_name).try(:list_position, list_name) || 1
+      end
+      alias_method :first_position_in_list, :top_position_in_list
+
+      # Returns the first item of the list.
+      def top_item(list_name)
+        scoped(list_name).ascending(list_name).first(:conditions => options_for_position(list_name, :not_null))
+      end
+
+      # Returns the position for the bottom item in the list.
+      def bottom_position_in_list(list_name)
+        bottom_item(list_name).try(:list_position, list_name) || 0
+      end
+      alias_method :last_position_in_list, :bottom_position_in_list
+
+      # Returns the bottom item.
+      def bottom_item(list_name)
+        scoped(list_name).descending(list_name).first(:conditions => options_for_position(list_name, :not_null))
+      end
+
+      # Returns the attribute name for the column storing the list position.
+      def position_column(list_name = :default)
+        positionable.lists[list_name][:column]
+      end
+
+      # Builds position options for updates.
+      def options_for_position(list_name, option, value = nil)
+        return "#{position_column(list_name)} IS NOT NULL" if option == :not_null
+        "#{position_column(list_name)} #{option} #{value || list_position(list_name)}"
+      end
+
+      # Builds position assignment statement for updates.
+      def update_options(list_name, sign)
+        "#{position_column(list_name)} = (#{position_column(list_name)} #{sign} 1)"
+      end
+
+      # Move all the lower items up one position.
+      def decrement_positions_on_lower_items(list_name, limit = nil)
+        conditions = options_for_position(list_name, '>')
+        conditions << " AND " << options_for_position(list_name, '<=', limit) if limit
+        scoped(list_name).update_all(update_options(list_name, '-'), conditions)
+      end
+
+      # Move all items lower than the given position down one position.
+      def increment_positions_on_lower_items(list_name, position)
+        scoped(list_name).update_all(update_options(list_name, '+'), options_for_position(list_name, '>=', position))
+      end
+      
+      # Move all the higher items up one position.
+      def increment_positions_on_higher_items(list_name, limit = nil)
+        conditions = options_for_position(list_name, '<')
+        conditions << " AND " << options_for_position(list_name, '>=', limit) if limit
+        scoped(list_name).update_all(update_options(list_name, '+'), conditions)
+      end
+
+      # Insert at the given position and shifts all necessary items accordingly.
+      def insert_at_position(list_name, position)
+        if position.is_a?(Symbol)
+          position = send("#{position}_position_in_list", list_name)
+          position = 1 if position == 0
+        end
+        acts_as_positionable_class.transaction do
+          if in_list?
+            if position < self.list_position
+              increment_positions_on_higher_items(list_name, position)
+            elsif position > self.list_position
+              decrement_positions_on_lower_items(list_name, position)
+            end
+          else
+            increment_positions_on_lower_items(list_name, position)
+          end
+          self.update_attribute(position_column(list_name), position)
+        end
+      end
+  end
+end
+
+ActiveRecord::Base.extend Positionable::ClassMethods

data/positionable.gemspec

@@ -0,0 +1,154 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{positionable}
+  s.version = "0.2.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Felipe Doria"]
+  s.date = %q{2009-07-10}
+  s.email = %q{felipe.doria@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.markdown"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.markdown",
+     "Rakefile",
+     "VERSION",
+     "app/controllers/positionable_controller.rb",
+     "app/helpers/positionable_helper.rb",
+     "config/routes.rb",
+     "init.rb",
+     "lib/positionable.rb",
+     "positionable.gemspec",
+     "test/rails_root/Rakefile",
+     "test/rails_root/app/controllers/application_controller.rb",
+     "test/rails_root/app/helpers/application_helper.rb",
+     "test/rails_root/app/models/conditional_item.rb",
+     "test/rails_root/app/models/different_position_column_item.rb",
+     "test/rails_root/app/models/hell_on_earth_item.rb",
+     "test/rails_root/app/models/multiple_list_item.rb",
+     "test/rails_root/app/models/multiple_scoped_item.rb",
+     "test/rails_root/app/models/scoped_item.rb",
+     "test/rails_root/app/models/simple_item.rb",
+     "test/rails_root/config/boot.rb",
+     "test/rails_root/config/database.yml",
+     "test/rails_root/config/environment.rb",
+     "test/rails_root/config/environments/development.rb",
+     "test/rails_root/config/environments/production.rb",
+     "test/rails_root/config/environments/test.rb",
+     "test/rails_root/config/initializers/backtrace_silencers.rb",
+     "test/rails_root/config/initializers/inflections.rb",
+     "test/rails_root/config/initializers/mime_types.rb",
+     "test/rails_root/config/initializers/new_rails_defaults.rb",
+     "test/rails_root/config/initializers/session_store.rb",
+     "test/rails_root/config/locales/en.yml",
+     "test/rails_root/config/routes.rb",
+     "test/rails_root/db/development.sqlite3",
+     "test/rails_root/db/migrate/20090702170207_create_simple_items.rb",
+     "test/rails_root/db/migrate/20090703071830_create_scoped_items.rb",
+     "test/rails_root/db/migrate/20090706180046_create_different_position_column_items.rb",
+     "test/rails_root/db/migrate/20090706200318_create_conditional_items.rb",
+     "test/rails_root/db/migrate/20090708045618_create_multiple_scoped_items.rb",
+     "test/rails_root/db/migrate/20090708174947_create_multiple_list_items.rb",
+     "test/rails_root/db/migrate/20090708183550_create_hell_on_earth_items.rb",
+     "test/rails_root/db/schema.rb",
+     "test/rails_root/script/about",
+     "test/rails_root/script/console",
+     "test/rails_root/script/dbconsole",
+     "test/rails_root/script/destroy",
+     "test/rails_root/script/generate",
+     "test/rails_root/script/performance/benchmarker",
+     "test/rails_root/script/performance/profiler",
+     "test/rails_root/script/plugin",
+     "test/rails_root/script/runner",
+     "test/rails_root/script/server",
+     "test/rails_root/test/conditional_tests.rb",
+     "test/rails_root/test/functional/positionable_controller_test.rb",
+     "test/rails_root/test/performance/browsing_test.rb",
+     "test/rails_root/test/scoped_tests.rb",
+     "test/rails_root/test/simple_gap_tests.rb",
+     "test/rails_root/test/simple_gapless_tests.rb",
+     "test/rails_root/test/simple_tests.rb",
+     "test/rails_root/test/test_helper.rb",
+     "test/rails_root/test/unit/conditional_item_test.rb",
+     "test/rails_root/test/unit/different_position_column_item_test.rb",
+     "test/rails_root/test/unit/eval_support_test.rb",
+     "test/rails_root/test/unit/hell_on_earth_item_test.rb",
+     "test/rails_root/test/unit/helpers/positionable_helper_test.rb",
+     "test/rails_root/test/unit/multiple_list_item_test.rb",
+     "test/rails_root/test/unit/multiple_scoped_item_test.rb",
+     "test/rails_root/test/unit/scoped_item_test.rb",
+     "test/rails_root/test/unit/scoped_item_with_gaps_test.rb",
+     "test/rails_root/test/unit/simple_item_test.rb",
+     "test/rails_root/test/unit/simple_item_with_gaps_test.rb"
+  ]
+  s.homepage = %q{http://github.com/aguids/positionable}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.4}
+  s.summary = %q{acts-as-list extension stretched to controllers and helpers}
+  s.test_files = [
+    "test/rails_root/app/controllers/application_controller.rb",
+     "test/rails_root/app/helpers/application_helper.rb",
+     "test/rails_root/app/models/conditional_item.rb",
+     "test/rails_root/app/models/different_position_column_item.rb",
+     "test/rails_root/app/models/hell_on_earth_item.rb",
+     "test/rails_root/app/models/multiple_list_item.rb",
+     "test/rails_root/app/models/multiple_scoped_item.rb",
+     "test/rails_root/app/models/scoped_item.rb",
+     "test/rails_root/app/models/simple_item.rb",
+     "test/rails_root/config/boot.rb",
+     "test/rails_root/config/environment.rb",
+     "test/rails_root/config/environments/development.rb",
+     "test/rails_root/config/environments/production.rb",
+     "test/rails_root/config/environments/test.rb",
+     "test/rails_root/config/initializers/backtrace_silencers.rb",
+     "test/rails_root/config/initializers/inflections.rb",
+     "test/rails_root/config/initializers/mime_types.rb",
+     "test/rails_root/config/initializers/new_rails_defaults.rb",
+     "test/rails_root/config/initializers/session_store.rb",
+     "test/rails_root/config/routes.rb",
+     "test/rails_root/db/migrate/20090702170207_create_simple_items.rb",
+     "test/rails_root/db/migrate/20090703071830_create_scoped_items.rb",
+     "test/rails_root/db/migrate/20090706180046_create_different_position_column_items.rb",
+     "test/rails_root/db/migrate/20090706200318_create_conditional_items.rb",
+     "test/rails_root/db/migrate/20090708045618_create_multiple_scoped_items.rb",
+     "test/rails_root/db/migrate/20090708174947_create_multiple_list_items.rb",
+     "test/rails_root/db/migrate/20090708183550_create_hell_on_earth_items.rb",
+     "test/rails_root/db/schema.rb",
+     "test/rails_root/test/conditional_tests.rb",
+     "test/rails_root/test/functional/positionable_controller_test.rb",
+     "test/rails_root/test/performance/browsing_test.rb",
+     "test/rails_root/test/scoped_tests.rb",
+     "test/rails_root/test/simple_gap_tests.rb",
+     "test/rails_root/test/simple_gapless_tests.rb",
+     "test/rails_root/test/simple_tests.rb",
+     "test/rails_root/test/test_helper.rb",
+     "test/rails_root/test/unit/conditional_item_test.rb",
+     "test/rails_root/test/unit/different_position_column_item_test.rb",
+     "test/rails_root/test/unit/eval_support_test.rb",
+     "test/rails_root/test/unit/hell_on_earth_item_test.rb",
+     "test/rails_root/test/unit/helpers/positionable_helper_test.rb",
+     "test/rails_root/test/unit/multiple_list_item_test.rb",
+     "test/rails_root/test/unit/multiple_scoped_item_test.rb",
+     "test/rails_root/test/unit/scoped_item_test.rb",
+     "test/rails_root/test/unit/scoped_item_with_gaps_test.rb",
+     "test/rails_root/test/unit/simple_item_test.rb",
+     "test/rails_root/test/unit/simple_item_with_gaps_test.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

data/test/rails_root/Rakefile

@@ -0,0 +1,10 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require(File.join(File.dirname(__FILE__), 'config', 'boot'))
+
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+require 'tasks/rails'

data/test/rails_root/app/controllers/application_controller.rb

@@ -0,0 +1,10 @@
+# Filters added to this controller apply to all controllers in the application.
+# Likewise, all the methods added will be available for all controllers.
+
+class ApplicationController < ActionController::Base
+  helper :all # include all helpers, all the time
+  protect_from_forgery # See ActionController::RequestForgeryProtection for details
+
+  # Scrub sensitive parameters from your log
+  # filter_parameter_logging :password
+end

data/test/rails_root/app/helpers/application_helper.rb

@@ -0,0 +1,3 @@
+# Methods added to this helper will be available to all templates in the application.
+module ApplicationHelper
+end

data/test/rails_root/app/models/conditional_item.rb

@@ -0,0 +1,3 @@
+class ConditionalItem < ActiveRecord::Base
+  acts_as_positionable :conditions => {:tag => 'todo'}
+end

data/test/rails_root/app/models/different_position_column_item.rb

@@ -0,0 +1,3 @@
+class DifferentPositionColumnItem < ActiveRecord::Base
+  acts_as_positionable :column => :different_position
+end

data/test/rails_root/app/models/hell_on_earth_item.rb

@@ -0,0 +1,5 @@
+class HellOnEarthItem < ActiveRecord::Base
+  acts_as_positionable :scope => [:parent_id, :session_id], :conditions => {:published => true}
+  acts_as_positionable :list_name => :client, :column => "client_position", :scope => :parent_id, :conditions => {:published => false}
+  acts_as_positionable :list_name => :developer, :column => "developer_position", :scope => :parent_id, :conditions => {:published => false, :tag => 'todo'}
+end

data/test/rails_root/app/models/multiple_list_item.rb

@@ -0,0 +1,5 @@
+class MultipleListItem < ActiveRecord::Base
+  acts_as_positionable
+  acts_as_positionable :list_name => :client, :column => "client_position"
+  acts_as_positionable :list_name => :developer, :column => "developer_position"
+end

data/test/rails_root/app/models/multiple_scoped_item.rb

@@ -0,0 +1,3 @@
+class MultipleScopedItem < ActiveRecord::Base
+  acts_as_positionable :scope => [:parent_id, :tag]
+end

data/test/rails_root/app/models/scoped_item.rb

@@ -0,0 +1,3 @@
+class ScopedItem < ActiveRecord::Base
+  acts_as_positionable :scope => :parent_id
+end

data/test/rails_root/app/models/simple_item.rb

@@ -0,0 +1,4 @@
+# Simple list. No scoping, no conditions, default position column.
+class SimpleItem < ActiveRecord::Base
+  acts_as_positionable
+end