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.

I think this is just the beginning though, here are my thoughts….

The Big Picture

Thanks to things like Rack, the MVC design pattern, and ActiveRecord / DataMapper, all of these frameworks look very similar. They all have a similar pattern, which is the inherent nature of the MVC design pattern. So I decided to take advantage of this with Authlogic. Any specific framework implementation is extracted out into an adapter. Similar to how ActiveRecord has an adapter for each database type, except the Authlogic adapters are much simpler.

Probably the main reason these adapters are so simple / similar is because of Rack. Thanks to Rack, there is a request standard across all of these frameworks. “But Ben, why not skip all of this nonsense and implement this right into Rack?”. The reason I didn’t go right into Rack is…

1. Not every “Rack compatible” framework uses the Rack libraries. After digging through the rails internals I found that the RackRequest class extends AbstractRequest, which has nothing to do with Rack. Lastly, older versions of rails aren’t rack compatible.
2. I need to hook into the controller anyways with a before_filter
3. With my implementation you get the best of both worlds. I designed the AbstractAdapter to conform to the rack standards, and any framework specific implementation can subclass this and do it’s magic.

So what’s the big picture here? The big picture is that there is no reason Authlogic can’t be an authentication solution for virtually any ruby framework out there. Why reinvent the wheel for every framework?

What about framework X?

Since writing adapters for rails and merb was so simple, why not keep going? Here are a few frameworks I plan to write an adapter for:

1. Mack
2. Ramaze
3. Sinatra

If you are feeling generous and want to write an adapter for a framework other than rails or merb, please do so. Let me know about it and I will add it into the source.

Final thoughts

Authlogic loves you regardless of your framework

Actually considering there are a million settings solutions, this is probably the last thing we need. That being said, I decided to add my own personal settings solution to the mix called Settingslogic. It’s nothing crazy or new. Just a simple solution to a simple problem. Settingslogic provides globally accessible settings via an ERB enabled YAML file. It has been great for my apps, maybe you will enjoy it too. Here’s how it works…

Create your settings

This is a typical YAML file, notice ERB is allowed.

# app/config/application.yml
defaults: &defaults
  cool:
    saweet: nested settings
  neat_setting: 24
  awesome_setting: <%= "Did you know 5 + 5 = " + (5 + 5) + "?" %>

development:
  <<: *defaults
  neat_setting: 800

test:
  <<: *defaults

production:
  <<: *defaults

Access your settings

  >> RAILS_ENV
  => "development"

  >> Settings.cool
  => "#<Settingslogic::Settings ... >"

  >> Settings.cool.saweet
  => "nested settings"

  >> Settings.neat_setting
  => 800

  >> Settings.awesome_setting
  => "Did you know 5 + 5 = 10?"

Give me more

You got it!

• Repository: http://github.com/binarylogic/settingslogic/tree/master
• Documentation: http://settingslogic.rubyforge.org/

What if you could have authentication up and running in minutes without having to run a generator? All because it’s simple, like everything else in rails.

What if creating a user session could be as simple as…

UserSession.create(params[:user])

What if your user sessions controller could look just like your other controllers…

class UserSessionsController < ApplicationController
  def new
    @user_session = UserSession.new
  end

  def create
    @user_session = UserSession.new(params[:user_session])
    if @user_session.create
      redirect_to account_url
    else
      render :action => :new
    end
  end

  def destroy
    current_user_session.destroy
  end
end

Look familiar? If you didn’t know any better, you would think UserSession was an ActiveRecord model. I think that’s pretty cool. Why is that cool? Because it fits nicely into the RESTful development pattern and its a style we all know and love. Wouldn’t this be cool too…

<%= error_messages_for "user_session" %>
<% form_for @user_session do |f| %>
  <%= f.label :login %><br />
  <%= f.text_field :login %><br />
  <br />
  <%= f.label :password %><br />
  <%= f.password_field :password %><br />
  <br />
  <%= f.submit "Login" %>
<% end %>

Or what about persisting the session…

class ApplicationController
  helper_method :current_user_session, :current_user

  protected
    def current_user_session
      return @current_user_session if defined?(@current_user_session)
      @current_user_session = UserSession.find
    end

    def current_user
      return @current_user if defined?(@current_user)
      @current_user = current_user_session && current_user_session.user
    end
end

Authlogic makes this a reality.

Reclaim your UsersController

This is one of my favorite features that I think its pretty cool. It’s things like this that make a library great and let you know you are on the right track.

Just to clear up any confusion, Authlogic does not store the plain id in the session. It stores a token. This token changes with the password, this way stale sessions can not be persisted.

That being said..What if a user changes their password? You have to re-log them in with the new password, recreate the session, etc, pain in the ass. Or what if a user creates a new user account? You have to do the same thing. Here’s an even better one: what if a user is in the admin area and changes his own password? There might even be another place passwords can change. It shouldn’t matter, your code should be written in a way where you don’t have to remember to do this.

Instead of updating sessions all over the place, doesn’t it make sense to do this at a lower level? Like the User model? You’re saying “but Ben, models can’t mess around with sessions and cookies”. True…but Authlogic can, and you can access Authlogic just like a model. I know in most situations it’s not good practice to do this but I view this in the same class as sweepers, and feel like it actually is good practice here. User sessions are directly tied to users, they should be connected on the model level.

Fear not, because the acts_as_authentic method you call in your model takes care of this for you, by adding an after_create and after_update callback to automatically keep the session up to date. You don’t have to worry about it anymore. Don’t even think about it. Let your UsersController deal with users, not users AND sessions. ANYTIME the user changes his password in ANY way, his session will be updated.

Here is basically what is done…

class User < ActiveRecord::Base
  after_save :maintain_sessions!

  private
    def create_sessions!
      # create a new UserSession if they are not logged in
    end

    def maintain_sessions!
      # If we aren't logged in at all and the password was changed, go ahead and log the user in
      # If we are logged in and the password has change, update the sessions
    end
end

Obviously there is a little more to it than this, but hopefully this clarifies any confusion.

When things come together like this I think its a sign that you are doing something right. Put that in your pipe and smoke it!

Authlogic arouses me

That’s great, here are some resources:

• Repository: http://github.com/binarylogic/authlogic
• Documentation: http://authlogic.rubyforge.org/
• Tutorial: coming soon…

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.