README

CanSearch
=========

Allows you create common named_scopes and chain them together with #search and 
#search_for.

  class Topic
    belongs_to :forum
    has_many :commented
    has_many :comments, :through => :commented
    can_search do
      scoped_by :forums
      scoped_by :created, :scope => :date_range
      scoped_by :comments, :scope => :many
      scoped_by :name, :scope => :many_like, :on => comments
    end

    # creates these three named scopes
    #   named_scope :by_forums, lambda { |f| {:conditions => {:forum_id => f}} }
    #   named_scope :created,   lambda { |range| {:conditions => ...} }
    #   named_scope :many_comments, lambda { |q| 
    #     {:joins => :commented,:conditions => {"commented.comments_key" => q},
    #      :select => "DISTINCT topics.*"}
    #   named_scope :many_comments_name_like, lambda { |q| 
    #     {:joins => :comments,:conditions => ["comments.name LIKE ?", format % q],
    #      :select => "DISTINCT topics.*"}
  end
  
  Topic.search(:forum => 1)                  # Topic.by_forums(1)
  Topic.search(:forums => [1,2])             # Topic.by_forums([1,2])
  Topic.search(:created => (time1..time2))   # Topic.created(time1..time2)
  Topic.search(:created => \
    {:period => :daily, :start => Time.now}) # Topic.created(Time.now, Time.now + 1.day)
  Topic.search(:name => "something")         # Topic.many_comments_name_like("something")

You can automatically paginate:

  Topic.search :forum => 1, :page => params[:page]

You can also access the named_scope directly for custom #find or #calculate calls.

  Topic.search_for(:forum => 1).sum(:hits)

Oh, and you can combine scopes:

  Topic.search :forum => 1, :forums => [2, 3], :created => (time1..time2)

The options for every scope are: 

:named_scope => "name"
   "name" will be the name of the created scope
:attribute => "attr"
   "attr" will be the attribute the scope is applied on

many_... scopes take
:on => "association"
   "association" is the ActiveRecord class that is joined

many_scope takes
:foreign_key => "foreign_key"
  foreign_key will only be used if you are searching for the id on a has_many :through
  assocation. You only need it if you have a non standard foreign_key in the :through
  association.

like... scopes take 
:format => "%s"
   "%s" will be the format like is aplied on

Be careful when using multiple ":scope => :many" in one search. Right now the
:joins overwrite each other. The one with the alpabeticly lower name will be
used. You will have to wait for Rails 2.2 or run rails edge to get a fix for this.
See ticket: 
http://rails.lighthouseapp.com/projects/8994/tickets/501-merge-joins-instead-of-clobbering-them 


Copyright (c) 2008-* Rick Olson, released under the MIT license