Skip to content
Sortable Table Columns
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
dev
lib
.gitignore Updates. Better docs & support for Rails 3. Jul 29, 2011
MIT-LICENSE
README.html
README.md
Rakefile Update. Feb 24, 2013
VERSION.yml Update. Feb 24, 2013
handles_sortable_columns.gemspec Update. Feb 24, 2013
init.rb

README.md

Sortable Table Columns

Introduction

A simple yet flexible Rails gem/plugin to quickly add sortable table columns to your controller and views.

Setup (Rails 3)

In your app's Gemfile, add:

gem "handles_sortable_columns"

To install the gem with RDoc/ri documentation, do a:

$ gem install handles_sortable_columns

Otherwise, do a bundle install.

Setup (Rails 2)

In your app's config/environment.rb add:

config.gem "handles_sortable_columns"

To install the gem, do a:

$ gem sources --add http://rubygems.org
$ gem install handles_sortable_columns

, or use rake gems:install.

Basic Usage

Activate the feature in your controller class:

class MyController < ApplicationController
  handles_sortable_columns
  ...

In a view, mark up sortable columns by using the sortable_column helper:

<%= sortable_column "Product" %>
<%= sortable_column "Price" %>

In controller action, fetch and use the order clause according to current state of sortable columns:

def index
  order = sortable_column_order
  @records = Article.order(order)           # Rails 3.
  @records = Article.all(:order => order)   # Rails 2.
end

That's it for basic usage. Production usage may require passing additional parameters to listed methods.

Production Usage

Please take time to read the gem's full RDoc documentation. This README has a limited coverage.

Configuration

Change names of GET parameters used for sorting and pagination:

class MyController < ApplicationController
  handles_sortable_columns do |conf|
    conf.sort_param = "s"
    conf.page_param = "p"
  end
  ...

Change CSS class of all sortable column <a> tags:

handles_sortable_columns do |conf|
  conf.class = "SortableLink"
  conf.indicator_class = {:asc => "AscSortableLink", :desc => "DescSortableLink"}
end

Change how text-based sort indicator looks like:

handles_sortable_columns do |conf|
  conf.indicator_text = {:asc => "[asc]", :desc => "[desc]"}
end

Disable text-based sort indicator completely:

handles_sortable_columns do |conf|
  conf.indicator_text = {}
end

Helper Options

Explicitly specify column name:

<%= sortable_column "Highest Price", :column => "max_price" %>

Specify CSS class for this particular link:

<%= sortable_column "Name", :class => "SortableLink" %>

Specify sort direction on first click:

<%= sortable_column "Created At", :direction => :asc %>

Fetching Sort Order

To fetch sort order securely, with column name validation, default values and multiple sort criteria, use the block form of sortable_column_order:

order = sortable_column_order do |column, direction|
  case column
  when "name"
    "#{column} #{direction}"
  when "created_at", "updated_at"
    "#{column} #{direction}, name ASC"
  else
    "name ASC"
  end
end

Feedback

Send bug reports, suggestions and criticisms through project's page on GitHub.

You can’t perform that action at this time.