Maybe it’s not a pain in the ass for you, maybe it is, or maybe it is and you don’t know it. We’ll never know. Either way, this tutorial is pain-in-the-ass free. Guaranteed. That’s what this is all about, making your life easier when it comes to paginating, ordering, and searching. Things you do multiple times in almost every application.

My solution: Searchlogic. It has saved me a lot time, shortened my code, and ultimately given me the proper tools to paginate, order, and search my data. Hopefully it will do the same for you.

Enough talk, let’s dive in.

“Does this really work? Am I about to waste my time?”. I hope not. But just for you, I made this live example:

Live example based on this tutorial

Paginating, ordering, and searching doesn’t get any easier than this. Before we start I want to make the following assumptions about you:

1. You have a working rails application on rails edge (rake rails:freeze:edge)
2. You have the following model structure: UserGroup => User => Order (=> = has_many). Make sure you have the has_many and belongs_to relationships set up. The fields are irrelevant, just change the field names in the view to whatever you have.

1. Install Searchlogic

$ sudo gem install searchlogic

Now add the gem dependency to your rails config:

# config/environment.rb
config.gem "searchlogic"

As always you can install searchlogic as a plugin, but plugins are becoming a thing of the past. I recommend the above approach, but here is the plugin installation if you prefer to do it this way:

$ script/plugin install git://github.com/binarylogic/searchlogic.git

2. Create your controller

Let’s create a controller that searches, orders, and paginates users. Like an admin area. Create app/controllers/users_controller.rb with the following content:

# app/controllers/users_controller.rb
class UsersController < ApplicationController
    def index
        @search = User.new_search(params[:search])
        @users, @users_count = @search.all, @search.count
    end
end

What did we do here?

It’s simple actually, if you haven’t looked at Searchlogic I suggest you take a quick glance. I’m not going to get into crazy detail about what it does, because the README in the library covers that, but to make this short it “enhances” searching with ActiveRecord.

Notice that we started a new search with the @search object. This lets you search via an object, which is really handy for your view, which you will see below. It also added in some nifty methods such as page, per_page, order_by, order_as, and a plethora of conditions for each of your columns. The second line does a simple search and counts the results. The thing to remember here is that the .count method ignores pagination. It ignores the limit and offset values. So if you want to know how many users matched the search, use count, not @users.size. If the first page is limited to 10 reconds @user.size will return 10.

3. Create the view and your’re done

# app/views/users/index.html.erb
<% if @users_count > 0 %>
    <%= @users_count %> users found

    <table border="1" cellpadding="5">
        <tr>
            <th><%= order_by_link :id %></th>
            <th><%= order_by_link :user_group => :name %></th>
            <th><%= order_by_link :first_name %></th>
            <th><%= order_by_link :last_name %></th>
            <th><%= order_by_link [:email, :first_name] %></th>
        </tr>
        <% @users.each do |user| %>
            <tr>
                <td><%= user.id %></td>
                <td><%= user.user_group ? user.user_group.name : "-" %></td>
                <td><%= user.first_name %></td>
                <td><%= user.last_name %></td>
                <td><%= user.email %></td>
            </tr>
        <% end %>
    </table>

    <br />
    <br />

    Per page: <%= per_page_select %>

    <% if @search.page_count > 1 %>
        <br />Page: <%= page_select %>
    <% end %>
<% else %>
    No users were returned
<% end %>

What did we do here?

All that we did was iterate through our users, list them in a table format, and then add page and per_page controls. Notice any unusual helpers? (order_by_link, per_page_select, and page_select). I won’t go into detail about these helpers because its all in the documentation under Searchlogic::Helpers::ControlTypes.

These are only a few ways to use these helpers, this is really just the tip of the iceberg. The sky is the limit: create a select that lets users navigate through the pages, create a list of links (like flickr) that lets you navigate through pages, create a link that lets you order by any number of columns you want, etc. I know ruby has a bad rep when it comes to documentation, but I actually put some decent time into the Searchlogic documentation and I think you will find it helpful. That’s your best resource for finding out everything Searchlogic has to offer.

Adding a search form

“This is all great, but you said I could search my data”. Searching your data is just as easy. Just add this to the top of your index.html.erb

# app/views/users/index.html.erb
<% form_for @search do |f| %>
    <fieldset>
        <legend>Search Users</legend>

        <% f.fields_for @search.conditions do |users| %>
            <%= users.label :first_name_keywords %><br />
            <%= users.text_field :first_name_keywords %><br />
            <br />

            <% users.fields_for users.object.orders do |orders| %>
                <%= orders.label :total_gt, "Has orders with a total greater than" %><br />
                $<%= orders.text_field :total_gt %><br />
                <br />
            <% end %>

            <% users.fields_for users.object.user_group do |user_group| %>
                <%= user_group.label :name_starts_with, "Belongs to user group with name that starts with" %><br />
                <%= user_group.text_field :name_starts_with %><br />
                <br />
            <% end %>
        <% end %>
    </fieldset>
    <%= f.submit "Search" %>
<% end %>

As I mentioned above Searchlogic creates default conditions on your columns based on the type. Letting you use a form builder to call those conditions. When it receives these conditions on the back-end it will do its “magic” and creates the proper SQL. Don’t worry about SQL injections, Searchlogic has you covered on that (see the documentation for more info).

What’s great about this method of searching?

1. Your search logic is in one place: the view.
2. You can add conditions by doing f.text_field “[column name]_[condition]“. So when your picky client calls up and says “Hey, we need a search field for finding emails that end with…” No prob: f.text_field :email_ends_with. Done!
3. You can traverse your relationships with fields_for and set conditions on related objects. Saweet!

Ajaxified

So you’re saying “this is great, but super old school, where’s the AJAX?!?!?” So you’re all about AJAX? No problem. In the example I have 3 examples: a non AJAX example, an AJAX example using the built in rails helpers, and a jQuery AJAX example. Check them out. You can view the source of the examples on github (each example if named spaced into its own controller). On a side note, I highly recommend jQuery. I recently started using it and love it. I actually get excited to write javascript because I always find something new when digging through the documentation or plugins and unobtrusive javascript never felt so good.

Some helpful links

This tutorial is really just the tip of the ice berg with Searchlogic. Checkout these links to see all it has to offer:

• Live example based on this tutorial
• Source code for the live tutorial
• Searchlogic, the library that makes all of this magic happen
• Searchlogic documentation

I am always interested in hearing feedback. Let me know what you think, what you like, what you don’t, that you hate the name, etc. I love criticism. Searchlogic is under active development and I am always trying to improve it. I hope this tutorial was helpful to you and ultimately makes your life easier.