sortable¶ ↑

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

Requires ActiveRecord >= 2.0.0

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 an array of items higher than the current item in the specified list
higher_items(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)

# Returns an array of items lower than the current item in the specified list
lower_items(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: [email protected]