= guilded

http://github.com/midas/sort_it_out


== DESCRIPTION

Easily add sorting functionality to your Rails controller actions in a clean manner.


== FEATURES

* Specify that your controller should resolve the order clause from the params.
* Configure a default field to sort by if no sorting params are passed in.
* Map order requests to one or more other field names.  Useful for aggregated fields, etc.


== REQUIREMENTS

* Rails >= 2.3


== INSTALL

  gem sources -a http://gemcutter.org
  sudo gem install sort_it_out


== USAGE

Add to the Rails environment file:

  config.gem "sort_it_out", :source => 'http://gemcutter.org'

Simplest case:

  class UsersController< ApplicationController
    sortable

    def index
      User.find( :all, :order => @order ) # @order is set up by sort_it_out
      ...
    end
  end

In the previous example a before filter is run that will set up an @order variable containing a SQL fragment
for the order clause.  The order clause will be set up from the parameters :order and :direction.

Include a default sort direction:

class UsersController< ApplicationController
  sortable :default => { :attribute => :name, :direction => 'DESC' }

  def index
    User.find( :all, :order => @order ) # @order is set up by sort_it_out
    ...
  end
end

More complex case:


  class UsersController< ApplicationController
    sortable :default => :name, :map => { :name => [:name_last, :name_first, :name_middle] }

    def index
      User.find( :all, :order => @order ) # @order is set up by sort_it_out
      ...
    end
  end

In the previous example a default field to sort by is configured.  Thus, if there is no :order param, the
default field is used.  There is also a map set up.  If the :order param is :name, then the order clause will
be built using the name_last, name_first and name_middle fields.


== LICENSE

Copyright (c) 2009 C. Jason Harrelson (midas)

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.