Resort provides sorting capabilities to your Rails 3 models.
##Install
$ gem install resort
Or in your Gemfile:
gem 'resort'
##Rationale
Most other sorting plugins work with an absolute position
attribute that sets
the weight of a given element within a tree. This field has no semantic sense,
since "84" by itself gives you absolutely no information about an element's
position or its relations with other elements of the tree.
Resort is implemented like a linked list,
rather than relying on absolute position values. This way, every model
references a next
element, which seems a bit more sensible :)
##Usage
First, run the migration for the model you want to Resort:
$ rails generate resort:migration product
$ rake db:migrate
Then in your Product model:
class Product < ActiveRecord::Base
resort!
end
NOTE: By default, Resort will treat all products as a single big tree.
If you wanted to limit the tree scope, i.e. treating every ProductLine as a
separate tree of sortable products, you must override the siblings
method:
class Product < ActiveRecord::Base
resort!
def siblings
# Tree contains only products from my own product line
self.product_line.products
end
end
Multiple users modifying the same list at the same time could be a problem, so it's always a good practice to wrap the changes in a transaction:
Product.transaction do
my_product.append_to(another_product)
end
###API
Every time a product is created, it will be appended after the last element.
Moreover, now a product
responds to the following methods:
first?
— Returns true if the element is the first of the tree.append_to(other_element)
— Appends the element after another element.next
— Returns the next element in the listprevious
— Returns the previous element in the list
And the class Product has a new scope named ordered
that returns the
products in order.
Given our Product
example defined before, we can do things like:
Getting products in order:
Product.first_in_order # returns the first ordered product.
Product.last_in_order # returns the last ordered product.
Product.ordered # returns all products ordered as an Array, not a Relation!
Find ordered products with scopes or conditions:
Product.where('price > 10').ordered # => Ordered array of products with price > 10
Product.with_custom_scope.ordered # => Ordered array of products with your custom conditions
Modify the list of products:
product = Product.create(:name => 'Bread')
product.first? # => true
another_product = Product.create(:name => 'Milk')
yet_another_product = Product.create(:name => 'Salami')
yet_another_product.append_to(product) # puts the products right after the first one
Product.ordered.map(&:name) # => ['Bread', 'Salami', 'Milk']
Check neighbours:
product = Product.create(:name => 'Bread')
second_product = Product.create(:name => 'Milk')
third_product = Product.create(:name => 'Salami')
second_product.previous.name # => 'Bread'
second_product.next.name # => 'Salami'
third_product.next # => nil
Maybe you need different orders depending on the product vendor:
class Product < ActiveRecord::Base
resort!
belongs_to :vendor
def siblings
self.vendor.products
end
end
bread = Product.create(:name => 'Bread', :vendor => Vendor.where(:name => 'Bread factory'))
bread.first? # => true
milk = Product.create(:name => 'Milk', :vendor => Vendor.where(:name => 'Cow world'))
milk.first? # => true
# bread and milk aren't neighbours
##Under the hood
Run the test suite by typing:
rake spec
You can also build the documentation with the following command:
rake docs
- Fork the project.
- Make your feature addition or bug fix.
- Add tests for it. This is important so I don't break it in a future version unintentionally.
- Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
- Send us a pull request. Bonus points for topic branches.
Copyright (c) 2011 Codegram. See LICENSE for details.