sortable

Allows you to sort ActiveRecord items similar to github.com/rails/acts_as_list but with support for multiple scopes and lists

Installation

  gem install shuber-sortable --source http://gems.github.com
  OR
  script/plugin install git://github.com/shuber/sortable.git

Examples

Simple

Works just like github.com/rails/acts_as_list

  class Todo < ActiveRecord::Base
    # schema
    #   id           :integer
    #   project_id   :integer
    #   description  :string
    #   position     :integer
    sortable :scope => :project_id
  end

  @todo = Todo.create(:description => 'do something', :project_id => 1)
  @todo_2 = Todo.create(:description => 'do something else', :project_id => 1)
  @todo_3 = Todo.create(:description => 'some other task', :project_id => 2)

  @todo.position # 1
  @todo_2.position # 2
  @todo_3.position # 1

  @todo.move_down!
  @todo_2.reload

  @todo.position # 2
  @todo_2.position # 1
  @todo_3.position # 1

Multiple scopes

Stories may or may not be in a sprint, but if we scoped just by :sprint_id, all stories with a nil :sprint_id would be sorted in one giant list instead of being sorted in each of their respective projects. Specifying an array of scopes fixes this problem.

  class Story < ActiveRecord::Base
    # schema
    #   id           :integer
    #   project_id   :integer
    #   sprint_id    :integer
    #   description  :string
    #   position     :integer
    sortable :scope => [:project_id, :sprint_id]
  end

Multiple lists

Your project management software needs to allow both clients and developers to prioritize todo items separately so that they can be discussed and reviewed during their next meeting. Multiple lists solves this problem.

  class Todo < ActiveRecord::Base
    # schema
    #   id                  :integer
    #   project_id          :integer
    #   description         :string
    #   client_priority     :integer
    #   developer_priority  :integer
    sortable :scope => :project_id, :column => :client_priority, :list_name => :client
    sortable :scope => :project_id, :column => :developer_priority, :list_name => :developer
  end

  @todo = Todo.create(:description => 'do something', :project_id => 1)
  @todo_2 = Todo.create(:description => 'do something else', :project_id => 1)

  @todo.client_priority # 1
  @todo.developer_priority # 1
  @todo_2.client_priority # 2
  @todo_2.developer_priority # 2

  @todo.move_down!(:client)
  @todo_2.reload

  @todo.client_priority # 2
  @todo.developer_priority # 1
  @todo_2.client_priority # 1
  @todo_2.developer_priority # 2

Switching scope

Any attributes specified as a :scope that are changed on an item cause the item to automatically switch lists when it is saved

  class Todo < ActiveRecord::Base
    # schema
    #   id           :integer
    #   project_id   :integer
    #   description  :string
    #   position     :integer
    sortable :scope => :project_id
  end

  @todo = Todo.create(:description => 'do something', :project_id => 1)
  @todo_2 = Todo.create(:description => 'do something else', :project_id => 1)

  @todo.position # 1
  @todo_2.position # 2

  @todo.project_id = 2
  @todo.save
  @todo_2.reload

  @todo.position # 1
  @todo_2.position # 1

Instance methods

  # Adds the current item to the end of the specified list and saves
  #
  # If the current item is already in the list, it will remove it before adding it
  add_to_list!(list_name = nil)

  # Returns the first item in a list associated with the current item
  first_item(list_name = nil)

  # Returns a boolean after determining if the current item is the first item in the specified list
  first_item?(list_name = nil)

  # Returns a boolean after determining if the current item is in the specified list
  in_list?(list_name = nil)

  # Inserts the current item at a certain position in the specified list and saves
  #
  # If the current item is already in the list, it will remove it before adding it
  #
  # Aliased as insert_at_position!
  insert_at!(position = 1, list_name = nil)

  # Returns the item with a position at a certain offset to the current item's position in the specified list
  #
  # Example
  #
  #   @todo = Todo.create
  #   @todo_2 = Todo.create
  #   @todo.item_at_offset(1) # returns @todo_2
  #
  # Returns nil if an item at the specified offset could not be found
  item_at_offset(offset, list_name = nil)

  # Returns the last item in a list associated with the current item
  last_item(list_name = nil)

  # Returns a boolean after determining if the current item is the last item in the specified list
  last_item?(list_name = nil)

  # Returns the position of the last item in a specified list
  #
  # Returns 0 if there are no items in the specified list
  last_position(list_name = nil)

  # Moves the current item down one position in the specified list and saves
  move_down!(list_name = nil)

  # Moves the current item up one position in the specified list and saves
  move_up!(list_name = nil)

  # Moves the current item down to the bottom of the specified list and saves
  move_to_bottom!(list_name = nil)

  # Moves the current item up to the top of the specified list and saves
  move_to_top!(list_name = nil)

  # Returns the next lower item in the specified list
  next_item(list_name = nil)

  # Returns the previous higher item in the specified list
  previous_item(list_name = nil)

  # Removes the current item from the specified list and saves
  #
  # This will set the :position to nil
  remove_from_list!(list_name = nil)

  # Returns a boolean after determining if this item has changed any attributes specified in the :scope options
  sortable_scope_changed?

  # Stores an array of attributes specified as a :scope that have been changed
  sortable_scope_changes

Contact

Problems, comments, and suggestions all welcome: shuber@huberry.com