My favorite feature in Searchlogic is named scope delegation. I’ve noticed in a number of projects I’ve seen where programmers copy over named scope logic into related models. Which makes sense, because AR gives you no way of easily accessing related scopes. For example:

Order.named_scope :pending, :conditions => {:state => "pending"}
User.named_scope :pending_orders, :joins => :orders, :conditions => "orders.state = 'pending'"

Most people would look at that and never see anything wrong with it. What is the conditions for a pending order changes?

Order.named_scope :pending, :conditions => "orders.state = 'pending' AND approved = true

Now you have to remember to change this logic in associated models. This is a programming no-no. With searchlogic you don’t even need to touch the User model. You can access the order’s named scope, and it delegates that call:

User.orders_pending

Now when you change what defines an order as pending it will change everywhere in your application. This is great, but where this feature comes to a screeching halt is when you encounter a polymorphic association. This is because AR has no internal support for this either. For example, you can’t do:

Audit.belongs_to :auditable, :polymorphic => true
User.has_many :audits, :as => :auditable

Audit.all(:joins => :user)

Obviously the above won’t work. AR has no idea that there is a relationship with users through the polymorphic auditable relationship. To overcome this you have to write your own join. Again, there is nothing wrong with writing SQL, I don’t want to send the wrong message. The problem is that you are back to square one with my named scope delegation problem above. To solve this I added a way to overcome this. With searchlogic you could do this:

Audit.auditable_user_type_name_like("ben")

Searchlogic will take care of creating the join on the polymorphic relationship and then delegate the call to the User.name_like named_scope. I think it’s pretty nifty.

I hope I explained this well. I figured I would mention the new feature because I’m sure I’m not the only person that has encountered this problem.

# will return all venues within 10 miles of the 10018 zip code
Venue.find(:all, :origin => "10018", :within => 10)

The problem is that you can’t use geokit options in a named scope. Since searchlogic is named scope driven this presented a problem. So I wrote a little module that transfers geokit options from named scopes to the actual arguments of the method:

module GeokitForNamedScopes
  OPTIONS = [:origin, :within, :beyond, :range, :formula, :bounds]

  def find(*args)
    super(*transfer_from_scope_to_args(args))
  end

  def count(*args)
    super(*transfer_from_scope_to_args(args))
  end

  private
    def transfer_from_scope_to_args(args)
      find_options = scope(:find)
      if find_options.is_a?(Hash)
        options = args.extract_options!
        OPTIONS.each do |key|
          options[key] = find_options.delete(key) if find_options.key?(key)
        end
        args << options
      else
        args
      end
    end
end

class ActiveRecord::Base
  class << self
    def acts_as_mappable(*args)
      result = super(*args)
      extend GeokitForNamedScopes

      GeokitForNamedScopes::OPTIONS.each do |key|
        named_scope key, lambda { |value| {key => value} }
      end

      result
    end

    VALID_FIND_OPTIONS += GeokitForNamedScopes::OPTIONS
  end
end

It’s far from perfect. The glaring problem is obviously redefining the VALID_FIND_OPTIONS constant, which throws a warning. But it works and it’s good enough for now. If anyone has any suggestions on how to improve this I’d to hear them. But you should be able to use geokit options in a named_scope with the above code. Ex:

Venue.origin("10017").within(10).all # => will return all venues within 10 miles of 10017

Using this through associations

Geokit doesn’t really support making these calls through associations. But if you read the documentation. You will notice they do support this:

acts_as_mappable :through => :whatever

You can use that feature to bridge the gap

Hopefully this helps some of you.

User.first_name_or_last_name_like("ben")
User.id_lt_or_age_gt(10)

I think this is nice feature on a variety of levels, but what I particularly like is the implementation. It uses method_missing to accomplish this. You can call any scope you want, call scopes provided by searchlogic, call your own scopes, call scopes on associations, etc. As long as it maps to a named scope it will join the conditions with ‘OR’. So you have a little more flexibility when building a query with named scopes:

User.id_gt(10).first_name_or_last_name_like("ben")
# => (id > 10) AND (first_name LIKE '%ben% OR last_name LIKE '%ben%')

More than just named scopes

A lot of people think searchlogic is just a bunch of named scopes, what people don’t realize is that it provides tools around how you use named scopes in general.

The other day I was reviewing an application for a friend who was using searchlogic. I noticed this:

User.named_scope :with_recent_orders, :conditions => ["orders.created_at >= ?", 1.week.ago], :joins => :orders
Order.named_scope :recent, :conditions => ["orders.created_at >= ?", 1.week.ago]

See the duplication there? With more complex named scopes this becomes more obvious, but the scope was so simple I think he missed it. I even catch myself doing this sometimes, then I realize I don’t need to. The named_scope in the User class is pointless. With searchlogic, you can accomplish the same thing by doing:

User.orders_recent

searchlogic dynamically creates the scope for you, pulls over the scope details, and create the necessary join.

The goal of named scopes

In my opinion the simpler the named scope, the better. If you find yourself writing a complicated named scope, take a step back and look at it. I’d be willing to bet you could split that named scope into multiple smaller scopes. For example, instead of calling a named scope ‘Product.popular_expensive’, create 2 named scopes called ‘popular’ and ‘expensive’. Break your scope into small parts and then piece them together when you need them.

Another good idea is to create scope procedures. This allows you to create small named scopes and still get the advantage of calling a single scope. Creating a procedure is as easy as creating a class level method:

class User
  def self.awesome
    name_begins_with("Ben").name_ends_with("Johnson")
  end
end

Even better, used searchlogic’s scope procedure:

User.scope_procedure :awesome, lambda { name_begins_with("Ben").name_ends_with("Johnson") }

I’ll leave it at that. If you are bored one day checkout the searchlogic docs. I think you’ll find some small things like this that could help save you time and DRY up your code.

I’m not going to ramble about the changes, because you can read my previous post or you can check out the read me on github.

Using github not rubyforge

I have decided to start using github to host my gems, if you want to start using v2 as a gem you need to install the binarylogic-searchlogic gem from the github source. (checkout the read me for easy installation instructions).

Thank you

Sorry for such a quick post. I figured this was an important announcement.

Thank you for being patient with v1, I know there were some people having issues. This should address all of them.

As always, I did my best with the readme and the rdocumentation. If you really want to see what v2 is all about I suggest you take a glance at those, they should be comprehensive.

I hope you enjoy v2, I’m really excited to release it. I have already integrated it into the app that I am working on, and I love it. It works great and all of my tests pass.

So, the project I’m working on now required something from Searchlogic v1 that it couldn’t provide. That is, searching with existing named scopes. I could do this, but it wasn’t as elegant as it was with the built in conditions (Ex: username_like, etc.).

The idea behind Searchlogic v2

So this got me thinking, how can I get Searchlogic v1 to use existing named scopes? That’s when it hit me, why not use named scopes for everything?I think we can all agree named scopes are the heart of searching and breaking up common search logic in your models. Instead of having all of this crazy logic write SQL and chain it together, as in v1, why not have Searchlogic dynamically create these common named scopes for you and then just leverage those? That’s exactly what v2 does. Instead of going into detail about v2, check out the current README. It explains everything v2 has to offer up to this point.

The best part about this approach is that it fits nicely into your application. All that it is doing is creating named scopes. More importantly, if you need some condition that Searchlogic doesn’t offer, no problem, just create your own named scope. This is what you should be doing anyways.

To bring it all home, let me show a simple search form that uses v2. Assume we have

User(name:string, age:integer)
Order(user_id:integer, total:float)

User.has_many :orders
User.named_scope :four_year_olds, :conditions => {:age => 4}
User.named_scope :name_sounds_like, lamda { |value| {:conditions => ["name SOUNDS LIKE ?", value]} }

Your search form could look like this:

- form_for @search do |f|
  = f.text_field :name_like
  = f.select :age_greater_than, (1..100)
  = f.text_field :orders_total_less_than
  = f.text_field :name_sounds_like
  = f.check_box :four_year_olds
  = f.submit

Notice the use of custom named scopes. Also the other conditions are also named scopes that searchlogic dynamically defines as you need them.

The best part of v2

• V1: ~2300 lines of code
• V2: ~350 lines of code

As you might have saw in this post Searchlogic v1 was too big for me to handle. The issues people were having would take way too long to solve and I just didn’t like the code. The library really wasn’t advancing and it was just an annoyance. It was regretably the first library I ever wrote, and as such there are a lot of things I would do differently, which should be evident in v2.

That being said, v2 is lean, makes sense, and just feels right. I’m really looking forward to maintaing the library and seeing where it goes. I hope everyone enjoys it. Let me know what you think. There are just a couple of things left to do before I officially release it.

Applications using v1

Lastly, because this is such a big change, backwards compatibility will be broken. Before I officially release the library I will write a document explaining the differences and how to transition. In the mean time, your gem declarations in your application should look like this, so that your app doesn’t break when the new version is released:

 config.gem "searchlogic", :version => "~> 1.6.6"
# the ~ will let you advance minor and tiny versions, but not major versions.

Fillin’ a brotha in

A lot of people think Searchlogic is a “console” searching utility. Meaning you can pop into your console and execute some simple searches quickly and easily, and it is, but by accident. My goal with Searchlogic has always been freeing your application of searching clutter. If you’ve ever done an app with searching you know there is a lot of “cruft” that goes along with it: nasty controller actions, excessive named_scopes, etc. Searchlogic rids you of this by representing an entire search’s criteria with a hash: conditions, ordering, pagination, the whole package. Why is this nice? Because GET and POST parameters are a hash. What’s nice about that? Because an HTML form’s sole purpose is to send GET and POST parameters to a URI. This means you can build a form that represents your entire search. Adding a condition to your search is as easy as adding a field to your form. This ultimately makes your controller dead simple, frees it of any search clutter, and rids your models of excessive named_scopes. Here is what your controller action should look like with Searchlogic:

@search = User.new_search(params[:search])
@users = @search.all

Complex searching in tha house

This is great for simple searching, but how do you represent complex searches this way? Let’s take this query:

select * from users where id > 5 AND
  (email LIKE 'ben%' or email LIKE '%binarylogic.com') AND
  first_name LIKE '%ben%'

Before, Searchlogic couldn’t handle this. It did not support grouping (parenthesis) and it did not allow you to mix and match “AND” and “OR”, you had to pick one or the other. Why? Because I never intended for Searchlogic to replace complex searching. If you need to perform a complex search there is nothing wrong with using Searchlogic in conjunction with some named_scopes. SQL is not bad, but what is bad is that all of that searching cruft starts seeping back into your project. All of a sudden your controller is not clean, your form has to stray away from using the form builder, and your model gets cluttered with named scopes that you are only using for one section in your application. Searchlogic fails to meet its goal of keeping your application free of “search clutter” and a tear runs down your cheek.

Slap a prefix on it!

Solving the problem of mixing “AND” and “OR” was easier than I thought. The only major change I had to make was making the conditions order relevant. The order you set your conditions is the same order they will appear in your SQL statement. Before, the conditions were stored in a hash, where order was not preserved. Now you can slap an “and_” or “or_” prefix in front of your conditions:

search = User.new_search
search.conditions.name_like = "Ben"
search.conditions.or_email_like = "a@a.com"
search.conditions.and_id_gt = 5
# => name LIKE '%Ben%' OR email like '%a@a.com%' AND id > 5

The last condition “and_id_gt” could also be written as “id_gt”, because, by default, we are joining with “AND”. Not specifying a prefix uses whatever you are joining your conditions with by default, specifying a prefix will always use that join. If you want your conditions to be joined by “OR” by default just do:

search.any = true

You best wrap it with some parenthesis

What about grouping conditions with parenthesis? No problem. Take the above query:

search = User.new_search
search.conditions.id_gt = 5
search.conditions.group do |group|
  group.email_begins_with = "ben"
  group.or_email_ends_with = "binarylogic.com"
end
search.conditions.first_name_contains = "ben"
search.all

What about a hash?

search = User.new_search(:conditions => [
  {:id_gt => 5},
  {:group => [
    {:email_begins_with => "ben"},
    {:or_email_ends_with => "binarylogic.com"}
  ]},
  {:first_name_contains => "ben"}
])

What about a form?

- form_for @search do |search|
  - search.fields_for "conditions" do |conditions_array|
    - conditions_array.fields_for "[]", search.object.conditions do |conditions|
      = conditions.text_field :id_gt
      - conditions.fields_for "group" do |group_array|
        - group_array.fields_for "[]" do |group|
          = group.text_field :email_begins_with
          = group.text_field :or_email_ends_with
      = conditions.text_field :first_name_contains

You will notice the hash and the form are implementing arrays, thats because hashes do not preserve the order. In our case above, order is important to us. What does preserve the order? An array. So if order is relevant to you, then you need to structure your conditions into an array. There is no other choice with this, because forms can either submit a hash or an array of parameters.

I know what you are thinking: “the above looks a little confusing and messy”. I agree with you, to a point. The word “messy” is a relative term. In our case, we have no other choice, this is the 100% correct way to do this. That being said, this is clean, because there is no other cleaner option. Sorry to be a debbie downer here, but this is how forms work, there is nothing I can do about that. Regardless, the above is still cleaner than having a nasty controller action or adding a bunch of named_scopes into you model. Your search logic is nice and DRY, in one spot: the view.

99 problems, but complex searching aint one

I think this is pretty nifty, now you have the tools to construct any type of search in your form. I’ve been getting a lot of emails asking me about this, and I had to be a debbie downer and tell them to use named scopes. Now you can ditch the named scopes and keep your search logic nice and DRY in your form, where it probably belongs.

The last thing I want to say is that there is a time and a place for a named scope, by no means am I discouraging them, because they are by far one of the nicest features in ActiveRecord. But something about creating a complex named scope or a bunch of small named scopes for a single action in one of my controllers felt dirty. It felt like clutter. I knew I would never use those named scopes anywhere else, and they were solely for that search form. After a while all of these named scopes start overlapping and start sharing search logic. If you’re extremely picky like me, your don’t feel like your code is DRY. So how far do you go to break down a named scope? Breaking them down too much defeats their purpose, but not breaking them down enough seems to create redundant search logic. Searchlogic solved my problem with this, now all of my view specific search logic is where it should be, in my view.

I’ve been having a lot of conversations via email with people using Searchlogic, that go like the following:

Some person: Hi Ben, How do I order by an order’s total with Searchlogic?

Me: Cache the total in your database. Your idol, Ben

Some person: Before Searchlogic, I was just doing: Order.all(:order => “(quantity * price) ASC”). Is there a way to do this in Searchlogic?

Me: No, you shouldn’t order data like that. …long explanation of what to do…. Your idol, Ben

Some person: Thank you so much Ben, I can’t thank you enough for everything you have done for me. You truly are my idol. There should be a statue in your honor.

Maybe it didn’t go exactly like that, but you get the point. So instead of having to retype the “long explanation of what to do”, I can just link them to this post:

This can be simple or complicated depending on how you calculate your total. Let’s start with the simple:

Simple solution

Your total method looks something like to following. Dealing with only local attributes.

def total
    quantity * price
end

Your first thought might be to sort via the ruby sort method. This is wrong on so many levels, not to mention you already have a tool that is extremely good at sorting data: your database.

Awesome! We’ll just do something like this:

Order.all(:order => "(quantity * price) ASC")

Wrong again! This is bad for a number of reasons:

1. Your code is no longer DRY. What if you want to add in tax later on down the road? You’ll have to do it in multiple places.
2. (quantity * price) can not be indexed. The whole point of indexing is to sort.

Now you’re saying “WTF Ben?!?!?1!?11″. Relax, why not just cache the total in the database?

class Order < ActiveRecord::Base
    before_validation :cache_virtual_columns

    def total
        quantity * price
    end

    private
        def cache_virtual_columns
            self.total = total
        end
end

Now you can index the total column and order just like you would with any other column. Yay!

Don’t celebrate yet. Chances are your total probably isn’t that simple.

Advanced solution

Maybe your total method looks like:

def total
    line_items.sum(:total) + tax + shipping_cost
end

Oh no! What happens when the total of a line item changes? The total in the orders table is no longer accurate. Your total now depends on other models. This is where observers shine:

class OrderObserver < ActiveRecord::Observer
  observe :order, :line_item

  def before_validation(obj)
    case obj
    when Order
      obj.total = obj.total
    end
  end

  def after_save(obj)
    case obj
    when LineItem
      obj.order.update_attribute(:total, obj.order.total)
    end
  end
end

You could really set this up a number of ways. You could create a CacheObserver that handles all caching for all models. This could get messy and confusing really fast, which is why I recommend the above example. My philosophy on OO programming is that classes should be responsible for their self. If the Order class is calculating the total it should be responsible for keeping it up to date in the database too.

“But Ben, this looks messy and complicated”. I agree with you, to an extent, but there is no simple solution here, because there is no pattern. Your total method could be anything you want. For all I know, your total method could be outsourced to a team in India that calculates the total by hand.

Sometimes in programming you have to give up something to gain something. I feel like writing some simple code in an observer is worth having a cached value of the total in the database. It makes everything so much cleaner, easier, and simpler in your controllers and views. Models should do all of the heavy lifting anyways.

Obviously, this is not just limited to total. You could do this for pretty much any virtual attribute in your models.

What do you think? I am always interested in feedback.

Why modifiers are necessary?

ActiveRecord does a great job when it comes to keeping your code database agnostic. But I feel like it neglected searching when it came to that goal. What if you want to find all records that were created after 7am? Depending on your database you would have to do something like the following:

MySQL:        HOUR(created_at)
PostgreSQL:   date_part('hour', created_at)
SQLite:       strftime('%H', created_at)

All of a sudden your app is not database agnostic. Oh no!

All of that bragging to your girlfriend about how you can switch databases in a matter of minutes was all a lie. How’s she going to feel when she finds out HOUR(created_at) is a MySQL specific function? Searchlogic to the rescue!

Searchlogic modifiers

Remember how you can do this in searchlogic?

User.all(:condition => {:created_at_gt => Time.parse("Jan 1, 2008")})
# => "created_at > 2008-01-01 00:00:00

Now you can do this too:

User.all(:conditions => {:hour_of_created_at_gt => 10})
# => HOUR(created_at) > 10

or this:

User.all(:conditions => {:tan_of_sin_of_cos_of_minute_of_created_at_gt => 20})
# => TAN(SIN(COS(MINUTE(created_at)))) > 20

What the hell was that? That was me making the point that you can chain modifiers. Obviously a very unrealistic example, but cool none-the-less.

Check out the readme for a list of modifiers and check out the changelog for a complete list of changes

What do you think?

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.

Enough said, let me show you some of my favorite features. If you are still interested you can just jump over to the searchlogic github page for a more detailed explanation.

For the following examples lets assume these relationships: User => Orders => LineItems

Simple Searching Example

User.all(
  :conditions => {
    :first_name_contains => "Ben",          # first_name like '%Ben%'
    :email_ends_with => "binarylogic.com"   # email like '%binarylogic.com'
  },
  :per_page => 20,                      # limit 20
  :page => 3,                           # offset 40, which starts us on page 3
  :order_as => "ASC",
  :order_by => {:user_group => :name}   # order user_groups.name ASC
)

same as above, but object based

search = User.new_search
search.conditions.first_name_contains = "Ben"
search.conditions.email_ends_with = "binarylogic.com"
search.per_page = 20
search.page = 3
search.order_as = "ASC"
search.order_by = {:user_group => :name}
search.all

In both examples, instead of using the “all” method you could use any search method: first, find(:all), find(:first), count, sum, average, etc, just like ActiveRecord.

The beauty of searchlogic, integration with rails

Using Searchlogic in rails is the best part, because rails has all kinds of nifty methods to make dealing with ActiveRecord objects quick and easy, especially with forms. So let’s take advantage of them! That’s the idea behind this plugin. Searchlogic is searching, ordering, and pagination all rolled into one simple plugin. Take all of that pagination and searching cruft out of your models and let Searchlogic handle it. Check it out:

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

Now your view.

# app/views/users/index.html.haml
- form_for @search do |f|
 - f.fields_for @search.conditions do |users|
  = users.text_field :first_name_contains
  = users.calendar_date_select :created_after # nice rails plugin for replacing date_select
  - users.fields_for users.object.orders do |orders|
    = orders.select :total_gt, (1..100)
  = f.submit "Search"

- if @users_count > 0
  %table
    %tr
      %th= order_by_link :account => :name
      %th= order_by_link :first_name
      %th= order_by_link :last_name
      %th= order_by_link :email
    - @users.each do |user|
      %tr
        %td= user.first_name
        %td= user.last_name
        %td= user.email

  Per page:
  = per_page_select
  Page:
  = page_select
- else
  No users returned

Things to notice

1. Passing a search object right into form_for and fields_for
2. The built in conditions for each column and how you can traverse the relationships and set conditions on them
3. The order_by_link helper
4. The page_select and per_page_select helpers
5. All of your search logic is in 1 spot: your view. Nice and DRY.

See my tutorial on this example

Nifty methods for searching trees

Just like the conditions you automatically get with each column. You automatically get conditions for searching tree data structures, if you’re model is a tree data structure.

# User is a tree data structure.
conditions = User.new_conditions
conditions.child_of = User.roots.first                  # Finds all children
conditions.sibling_of = User.first                      # Finds siblings
conditions.descendant_of = User.roots.first             # Finds all children, grandchildren, etc
conditions.inclusive_descendant_of = User.roots.first   # Includes root + children, grandchildren, etc.

Any of these conditions can accept a User object or a User id.

Get Started

Check out the GitHub repository to get started:

http://github.com/binarylogic/searchlogic/

Or a tutorial I posted on using Searchlogic in rails:

http://www.binarylogic.com/2008/9/7/tutorial-pagination-ordering-and-searching-with-searchlogic