Chris@909: module ActiveRecord Chris@909: module Acts #:nodoc: Chris@909: module List #:nodoc: Chris@909: def self.included(base) Chris@909: base.extend(ClassMethods) Chris@909: end Chris@909: Chris@909: # This +acts_as+ extension provides the capabilities for sorting and reordering a number of objects in a list. Chris@909: # The class that has this specified needs to have a +position+ column defined as an integer on Chris@909: # the mapped database table. Chris@909: # Chris@909: # Todo list example: Chris@909: # Chris@909: # class TodoList < ActiveRecord::Base Chris@909: # has_many :todo_items, :order => "position" Chris@909: # end Chris@909: # Chris@909: # class TodoItem < ActiveRecord::Base Chris@909: # belongs_to :todo_list Chris@909: # acts_as_list :scope => :todo_list Chris@909: # end Chris@909: # Chris@909: # todo_list.first.move_to_bottom Chris@909: # todo_list.last.move_higher Chris@909: module ClassMethods Chris@909: # Configuration options are: Chris@909: # Chris@909: # * +column+ - specifies the column name to use for keeping the position integer (default: +position+) Chris@909: # * +scope+ - restricts what is to be considered a list. Given a symbol, it'll attach _id Chris@909: # (if it hasn't already been added) and use that as the foreign key restriction. It's also possible Chris@909: # to give it an entire string that is interpolated if you need a tighter scope than just a foreign key. Chris@909: # Example: acts_as_list :scope => 'todo_list_id = #{todo_list_id} AND completed = 0' Chris@909: def acts_as_list(options = {}) Chris@909: configuration = { :column => "position", :scope => "1 = 1" } Chris@909: configuration.update(options) if options.is_a?(Hash) Chris@909: Chris@909: configuration[:scope] = "#{configuration[:scope]}_id".intern if configuration[:scope].is_a?(Symbol) && configuration[:scope].to_s !~ /_id$/ Chris@909: Chris@909: if configuration[:scope].is_a?(Symbol) Chris@909: scope_condition_method = %( Chris@909: def scope_condition Chris@909: if #{configuration[:scope].to_s}.nil? Chris@909: "#{configuration[:scope].to_s} IS NULL" Chris@909: else Chris@909: "#{configuration[:scope].to_s} = \#{#{configuration[:scope].to_s}}" Chris@909: end Chris@909: end Chris@909: ) Chris@909: else Chris@909: scope_condition_method = "def scope_condition() \"#{configuration[:scope]}\" end" Chris@909: end Chris@909: Chris@909: class_eval <<-EOV Chris@909: include ActiveRecord::Acts::List::InstanceMethods Chris@909: Chris@909: def acts_as_list_class Chris@909: ::#{self.name} Chris@909: end Chris@909: Chris@909: def position_column Chris@909: '#{configuration[:column]}' Chris@909: end Chris@909: Chris@909: #{scope_condition_method} Chris@909: Chris@909: before_destroy :remove_from_list Chris@909: before_create :add_to_list_bottom Chris@909: EOV Chris@909: end Chris@909: end Chris@909: Chris@909: # All the methods available to a record that has had acts_as_list specified. Each method works Chris@909: # by assuming the object to be the item in the list, so chapter.move_lower would move that chapter Chris@909: # lower in the list of all chapters. Likewise, chapter.first? would return +true+ if that chapter is Chris@909: # the first in the list of all chapters. Chris@909: module InstanceMethods Chris@909: # Insert the item at the given position (defaults to the top position of 1). Chris@909: def insert_at(position = 1) Chris@909: insert_at_position(position) Chris@909: end Chris@909: Chris@909: # Swap positions with the next lower item, if one exists. Chris@909: def move_lower Chris@909: return unless lower_item Chris@909: Chris@909: acts_as_list_class.transaction do Chris@909: lower_item.decrement_position Chris@909: increment_position Chris@909: end Chris@909: end Chris@909: Chris@909: # Swap positions with the next higher item, if one exists. Chris@909: def move_higher Chris@909: return unless higher_item Chris@909: Chris@909: acts_as_list_class.transaction do Chris@909: higher_item.increment_position Chris@909: decrement_position Chris@909: end Chris@909: end Chris@909: Chris@909: # Move to the bottom of the list. If the item is already in the list, the items below it have their Chris@909: # position adjusted accordingly. Chris@909: def move_to_bottom Chris@909: return unless in_list? Chris@909: acts_as_list_class.transaction do Chris@909: decrement_positions_on_lower_items Chris@909: assume_bottom_position Chris@909: end Chris@909: end Chris@909: Chris@909: # Move to the top of the list. If the item is already in the list, the items above it have their Chris@909: # position adjusted accordingly. Chris@909: def move_to_top Chris@909: return unless in_list? Chris@909: acts_as_list_class.transaction do Chris@909: increment_positions_on_higher_items Chris@909: assume_top_position Chris@909: end Chris@909: end Chris@909: Chris@909: # Move to the given position Chris@909: def move_to=(pos) Chris@909: case pos.to_s Chris@909: when 'highest' Chris@909: move_to_top Chris@909: when 'higher' Chris@909: move_higher Chris@909: when 'lower' Chris@909: move_lower Chris@909: when 'lowest' Chris@909: move_to_bottom Chris@909: end Chris@909: end Chris@909: Chris@909: # Removes the item from the list. Chris@909: def remove_from_list Chris@909: if in_list? Chris@909: decrement_positions_on_lower_items Chris@909: update_attribute position_column, nil Chris@909: end Chris@909: end Chris@909: Chris@909: # Increase the position of this item without adjusting the rest of the list. Chris@909: def increment_position Chris@909: return unless in_list? Chris@909: update_attribute position_column, self.send(position_column).to_i + 1 Chris@909: end Chris@909: Chris@909: # Decrease the position of this item without adjusting the rest of the list. Chris@909: def decrement_position Chris@909: return unless in_list? Chris@909: update_attribute position_column, self.send(position_column).to_i - 1 Chris@909: end Chris@909: Chris@909: # Return +true+ if this object is the first in the list. Chris@909: def first? Chris@909: return false unless in_list? Chris@909: self.send(position_column) == 1 Chris@909: end Chris@909: Chris@909: # Return +true+ if this object is the last in the list. Chris@909: def last? Chris@909: return false unless in_list? Chris@909: self.send(position_column) == bottom_position_in_list Chris@909: end Chris@909: Chris@909: # Return the next higher item in the list. Chris@909: def higher_item Chris@909: return nil unless in_list? Chris@909: acts_as_list_class.find(:first, :conditions => Chris@909: "#{scope_condition} AND #{position_column} = #{(send(position_column).to_i - 1).to_s}" Chris@909: ) Chris@909: end Chris@909: Chris@909: # Return the next lower item in the list. Chris@909: def lower_item Chris@909: return nil unless in_list? Chris@909: acts_as_list_class.find(:first, :conditions => Chris@909: "#{scope_condition} AND #{position_column} = #{(send(position_column).to_i + 1).to_s}" Chris@909: ) Chris@909: end Chris@909: Chris@909: # Test if this record is in a list Chris@909: def in_list? Chris@909: !send(position_column).nil? Chris@909: end Chris@909: Chris@909: private Chris@909: def add_to_list_top Chris@909: increment_positions_on_all_items Chris@909: end Chris@909: Chris@909: def add_to_list_bottom Chris@909: self[position_column] = bottom_position_in_list.to_i + 1 Chris@909: end Chris@909: Chris@909: # Overwrite this method to define the scope of the list changes Chris@909: def scope_condition() "1" end Chris@909: Chris@909: # Returns the bottom position number in the list. Chris@909: # bottom_position_in_list # => 2 Chris@909: def bottom_position_in_list(except = nil) Chris@909: item = bottom_item(except) Chris@909: item ? item.send(position_column) : 0 Chris@909: end Chris@909: Chris@909: # Returns the bottom item Chris@909: def bottom_item(except = nil) Chris@909: conditions = scope_condition Chris@909: conditions = "#{conditions} AND #{self.class.primary_key} != #{except.id}" if except Chris@909: acts_as_list_class.find(:first, :conditions => conditions, :order => "#{position_column} DESC") Chris@909: end Chris@909: Chris@909: # Forces item to assume the bottom position in the list. Chris@909: def assume_bottom_position Chris@909: update_attribute(position_column, bottom_position_in_list(self).to_i + 1) Chris@909: end Chris@909: Chris@909: # Forces item to assume the top position in the list. Chris@909: def assume_top_position Chris@909: update_attribute(position_column, 1) Chris@909: end Chris@909: Chris@909: # This has the effect of moving all the higher items up one. Chris@909: def decrement_positions_on_higher_items(position) Chris@909: acts_as_list_class.update_all( Chris@909: "#{position_column} = (#{position_column} - 1)", "#{scope_condition} AND #{position_column} <= #{position}" Chris@909: ) Chris@909: end Chris@909: Chris@909: # This has the effect of moving all the lower items up one. Chris@909: def decrement_positions_on_lower_items Chris@909: return unless in_list? Chris@909: acts_as_list_class.update_all( Chris@909: "#{position_column} = (#{position_column} - 1)", "#{scope_condition} AND #{position_column} > #{send(position_column).to_i}" Chris@909: ) Chris@909: end Chris@909: Chris@909: # This has the effect of moving all the higher items down one. Chris@909: def increment_positions_on_higher_items Chris@909: return unless in_list? Chris@909: acts_as_list_class.update_all( Chris@909: "#{position_column} = (#{position_column} + 1)", "#{scope_condition} AND #{position_column} < #{send(position_column).to_i}" Chris@909: ) Chris@909: end Chris@909: Chris@909: # This has the effect of moving all the lower items down one. Chris@909: def increment_positions_on_lower_items(position) Chris@909: acts_as_list_class.update_all( Chris@909: "#{position_column} = (#{position_column} + 1)", "#{scope_condition} AND #{position_column} >= #{position}" Chris@909: ) Chris@909: end Chris@909: Chris@909: # Increments position (position_column) of all items in the list. Chris@909: def increment_positions_on_all_items Chris@909: acts_as_list_class.update_all( Chris@909: "#{position_column} = (#{position_column} + 1)", "#{scope_condition}" Chris@909: ) Chris@909: end Chris@909: Chris@909: def insert_at_position(position) Chris@909: remove_from_list Chris@909: increment_positions_on_lower_items(position) Chris@909: self.update_attribute(position_column, position) Chris@909: end Chris@909: end Chris@909: end Chris@909: end Chris@909: end