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
gem install shuber-sortable --source http://gems.github.com OR script/plugin install git://github.com/shuber/sortable.git
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
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
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
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
# 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
Problems, comments, and suggestions all welcome: shuber@huberry.com