Java The Hutt

A long time ago I wrote a blog posting on a plugin I created that would allow you to create a sortable table for your rails models with minimal work. Well, 2.5 years later I'm taking the time to write yet another blog post on a revamped version of that plugin that does more with less and is about 10x easier to set up and use. If you refer back to my old posting you'll see that I set out to create a plugin that would allow you to create a non-ajax sortable and paginated table. It certainly worked but involved too much configuration and understanding by you the developer in order to use it. The goal here is the same and the motivation is largely to make it braindead easy to get a table up and running without having to know much of anything. I use this plugin in my apps in user facing pages as well as the starting point for all of my admin pages, completely replacing the ever fragile ActiveScaffold. (Sorry you guys, it totally rocks when it works but it just kept breaking too much for me and I didn't need all the bells and whistles) Over the past couple of years I've completely revamped how this plugin works so let's a have a look at "sortable reloaded" OK let's get started:

1. First You either create or use an existing a rails app (2.2.2 is the version I'm using still, not positive but this should work with 2.3.x or any rails 2.x apps without a problem).
   


2. Next we need to install the will_paginate gem. Assuming you're familiar with specifying gems for your app in your environment.rb file here's my entry for will_paginate:
   

     config.gem 'mislav-will_paginate',
               :lib => 'will_paginate',
               :source => 'http://gems.github.com',
               :version => '~> 2.3.6'
   



3. Now that we've got the pagination gem in place it's time to install the plugin itself. We can do that with:
   

   ruby script/plugin install git://github.com/kovacs/sortable.git



4. Next up I'm going to assume that you have a model for whose objects you'd like to create a paginated, sortable table. You're going to need a model as well as a controller with an entry in your routes.rb file. For example:
   in user.rb
   

   
   class User < ActiveRecord::Base
   end
   

   
   in users_controller.rb
   

   
   class UsersController < ApplicationController 
   end
   

   
   in routes.rb
   

   
   map.resources :users
   



5. Assuming you have that set up configured the simplest possible way to use sortable to create a sortable, paginated, searchable table of your objects is like this:
   

   
   class UsersController < ApplicationController
    sortable_table User
   end
   

   After you add that snippet to your controller go and hit: http://localhost:3000/users and watch the magic happen. Pretty cool for a one line declaration. The magic happening behind the scenes is that the declaration "sortable_table User" is generating an 'index' action in your UsersController and is using a default index.erb template file for the view of that action. Here's a look at that code: In sortable.rb (vendor/plugins/sortable/lib/sortable.rb)
   

   
   def index
    get_sorted_objects(params) 
    render :template => 'sortable/index'
   end
   

   in the view for index (vendor/plugins/sortable/views/sortable/index.erb)
   

   
   <%= sortable_table %>
   

   Everything is customizable but this is just demonstrating the simplest table you can create with the plugin.
   


6. By default you'll notice that the plugin uses all the attributes on your model when it builds the table. I can hear it already: "Dude, I don't want it to show XYZ attribute on my model" to which I'd say "Pfft... way ahead of you dawg". Specify what columns you want displayed in the table by default like this:
   

   
   class UsersController < ApplicationController
    sortable_table User, :display_columns => ['id', 'name', 'email', 'created_at', 'timezone', 'state'] 
   end
   

   
   Of course this example assumes that you have the attributes on your User model. Replace with your attributes as needed. What you'll end up seeing is this:
   
   


7. Of course there's a ton of flexibility in the plugin that allows you to place a sortable table on any page you'd like as opposed to having it only show up on an index page that lists all your objects. You can also show a table that sorts, searches, and paginates over more than one object type. So if you wanted to show all your users and one or more attributes from a related object or objects you can easily do that with a few attributes in your sortable_table declaration. You can also easily customize the L&F of the table and turn off searching if you don't want/need it. See more details in sortable.rb and sortable_helper.rb where it outlines all of the options. If there's something that it doesn't do feel free to fork the code and add it yourself and send me a pull request.
   


8. The basic mechanics on how to make use of the plugin in your app is that you want to call:
   

   
   get_sorted_objects(params, sortable_options)
   

   This call will populate a few variables for you to use:
   

   
   @objects  # The collection of objects that you can display in a table
   @headings  # The collection of table header objects that are used to build the header and links.
   

   Then in your view you'll just call:
   

   
   <%= sortable_table %>
   

   Wherever you'd like that sortable table to appear. It's really that simple. You can easily override the template that's being used to build the table with a parameter to the helper call. For example:
   

   
   <%= sortable_table :partial => 'loans/loan_table' %>
   

   Have a look at vendor/plugins/sortable/views/sortable/_table.html.erb for an idea of how to build a table for your objects if you want to have more flexibility than the standard template gives you.
   

If you find this plugin useful and especially if you use it on a site that's a project that you're intending to make money with please donate something as it did require time and effort to clean up, document, and package this plugin for general consumption. Your donation will go towards improving this plugin and inspire me to release other plugins that I know would be generally useful to other rails developers. You might want to note that unlike most open sores projects this plugin comes with example code, documented code, tests, and has 100% test coverage as well. It's also being used in production on a real site that charges real money for its products so it's not just someone's hobby project that's going to be abandoned. Think about that while you're busting out your credit card and making a suggested donation of $20 (or whatever you'd like) here:

If you aren't going to donate or are using it for a non-profit project I'd really appreciate a link to my company site: http://www.cablecarsoftware.com. Thanks everyone and hope you enjoy it and find it useful! Oh and finally, get the code here.

# posted by Michael Kovacs : Tuesday, June 30, 2009  43 comments