searchgasm 0.9.0

data/CHANGELOG

@@ -0,0 +1 @@
+v0.9.0. First release

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2007 Ben Johnson of Binary Logic (binarylogic.com)
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Manifest

@@ -0,0 +1,28 @@
+CHANGELOG
+init.rb
+lib/searchgasm/active_record/associations.rb
+lib/searchgasm/active_record/base.rb
+lib/searchgasm/active_record/protection.rb
+lib/searchgasm/helpers.rb
+lib/searchgasm/search/base.rb
+lib/searchgasm/search/condition.rb
+lib/searchgasm/search/conditions.rb
+lib/searchgasm/search/utilities.rb
+lib/searchgasm/version.rb
+lib/searchgasm.rb
+Manifest
+MIT-LICENSE
+Rakefile
+README.mdown
+test/fixtures/accounts.yml
+test/fixtures/orders.yml
+test/fixtures/users.yml
+test/libs/acts_as_tree.rb
+test/libs/rexml_fix.rb
+test/test_active_record_associations.rb
+test/test_active_record_base.rb
+test/test_active_record_protection.rb
+test/test_helper.rb
+test/test_searchgasm_base.rb
+test/test_searchgasm_condition.rb
+test/test_searchgasm_conditions.rb

data/README.mdown

@@ -0,0 +1,240 @@
+# Searchgasm
+
+Searchgasm is orgasmic. Maybe not orgasmic, but you will get aroused. So go grab a towel and let's dive in.
+
+Searchgasm originated to satisfy a VERY simple need: so that I could use my form builder when making search forms. Sounds simple right? The goal was to use an object, that represents a search, just like an ActiveRecord object in form\_for and fields\_for.
+
+I'm a big fan of understanding what I'm using, so here's a quick explanation: The design behind this plugin is pretty simple. The search object "santiizes" down into the options passed into ActiveRecord::Base.find(). It basically serves as a transparent filter between you and ActiveRecord::Base.find(). This filter provides "enhancements" that get translated into options that ActiveRecord::Base.find() can understand. This doesn't step on the toes or dig into he internals of ActiveRecord. It uses what ActiveRecord provides publicly. Letting ActiveRecord do all of the hard work and keeping this plugin solid and less brittle.
+
+Here's where you get aroused...
+
+## Install and use
+
+    sudo gem install searchgasm
+
+For rails > 2.1
+
+    # environment.rb
+    config.gem "searchgasm"
+
+For rails < 2.1
+
+    # environment.rb
+    require "searchgasm"
+
+Or as a plugin
+
+    script/plugin install git://github.com/binarylogic/searchgasm.git
+
+Now go into your console and try out any of these example with your own models.
+
+**For all examples, let's assume the following relationships: User => Orders => Line Items**
+
+## Super Simple Example
+
+    User.all(
+        :conditions => {
+            :first_name_contains => "Ben",
+            :email_ends_with => "binarylogic.com"
+        },
+        :page => 3,
+        :per_page => 20
+    )
+
+## Detailed Example w/ object based searching
+
+    # new_search returns an object, you can call "find", "all", "first" also, see "different ways to search" below
+    
+    search = User.new_search(
+        :conditions => {
+            :first_name_contains => "Ben", 
+            :age_gt => 18,
+            :orders => {:total_lt => 100}
+        },
+        :per_page => 20,
+        :page => 2,
+        :order_by => {:orders => :total},
+        :order_as => "DESC"
+    )
+    search.conditions.email_ends_with = "binarylogic.com"
+    search.conditions.oders.line_items.created_at_after = Time.now
+    search.per_page = 50 # overrides the 20 set above
+    
+    # Call ANY of the ActiveRecord options
+    search.group = "last_name"
+    search.readonly = true
+    # ... see ActiveRecord documentation
+    
+    # Return results just like ActiveRecord
+    search.all
+    search.search # alias for all
+    search.first
+
+## Calculations
+
+Using the object from above:
+
+    search.average('id')
+    search.count
+    search.maximum('id')
+    search.minimum('id')
+    search.sum('id')
+    search.calculate(:sum, 'id') # any of the above calculations
+
+Or do it from your model:
+
+    User.count(:conditions => {:first_name_contains => "Ben"})
+    # ... all other calcualtions, etc.
+
+## Different ways to search, take your pick
+
+Any of the options used in the above example can be used in these, but for the sake of brevity I am only using a few:
+
+    User.all(:conditions => {:age_gt => 18}, :per_page => 20)
+
+    User.first(:conditions => {:age_gt => 18}, :per_page => 20)
+
+    User.find(:all, :conditions => {::age_gt => 18}, :per_page => 20)
+
+    User.find(:first, :conditions => {::age_gt => 18}, :per_page => 20)
+
+    search = User.new_search(:conditions => {:age_gt => 18})
+    search.conditions.first_name_contains = "Ben"
+    search.per_page = 20
+    search.all
+
+If you want to be hardcore:
+
+    search = Searchgasm::Search.new(User, :conditions => {:age_gt => 18})
+    search.conditions.first_name_contains = "Ben"
+    search.per_page = 20
+    search.all
+
+## Search with conditions only (great for form\_for or fields\_for)
+
+    conditions = User.new_conditions(:age_gt => 18)
+    conditions.first_name_contains = "Ben"
+    conditions.search
+    conditions.all
+    # ... all operations above are available
+
+Pass a conditions object right into ActiveRecord:
+
+    User.all(:conditions => conditions) # same as conditions.search
+
+Again, if you want to be hardcore:
+
+    conditions = Searchgasm::Conditions.new(User, :age_gt => 18)
+    conditions.first_name_contains = "Ben"
+    conditions.search
+
+## Scoped searching
+
+    @current_user.orders.find(:all, :conditions => {:total_lte => 500})
+    @current_user.orders.count(:conditions => {:total_lte => 500})
+    @current_user.orders.sum('total', :conditions => {:total_lte => 500})
+    
+    search = @current_user.orders.build_search('total', :conditions => {:total_lte => 500})
+
+## Searching trees
+
+For tree data structures you get a few nifty methods. Let's assume Users is a tree data structure.
+
+    # Child of
+    User.all(:conditions => {:child_of => User.roots.first})
+    User.all(:conditions => {:child_of => User.roots.first.id})
+    
+    # Sibling of
+    User.all(:conditions => {:sibling_of => User.roots.first})
+    User.all(:conditions => {:sibling_of => User.roots.first.id})
+    
+    # Descendent of (includes all recursive children: children, grand children, great grand children, etc)
+    User.all(:conditions => {:descendent_of => User.roots.first})
+    User.all(:conditions => {:descendent_of => User.roots.first.id})
+    
+    # Inclusive descendent_of. Same as above but includes the root
+    User.all(:conditions => {:inclusive_descendent_of => User.roots.first})
+    User.all(:conditions => {:inclusive_descendent_of => User.roots.first.id})
+    
+
+
+## Available anywhere (relationships & named scopes)
+
+Not only can you use searchgasm when searching, but you can use it when setting up relationships or named scopes:
+
+    class User < ActiveRecord::Base
+        has_many :expensive_pending_orders, :conditions => {:total_greater_than => 1_000_000, :state => :pending}, :per_page => 20
+        named_scope :sexy, :conditions => {:first_name => "Ben", email_ends_with => "binarylogic.com"}, :per_page => 20
+    end
+
+## Always use protection (searching with params)
+
+If there is one thing we in sex ed. it's to always use protection. As I mentioned above the purpose of this plugin was to create a search object and use it in form\_for or fields\_for. What about receiving the params in the controller and protecting against SQL injection?
+
+    accounts = Account.find_with_protection(params[:search])
+    accounts = Account.all_with_protection(params[:search])
+    account = Account.first_with_protection(params[:search])
+
+For the lazy programmer:
+
+    accounts = Account.findwp(params[:search])
+    accounts = Account.allwp(params[:search])
+    account = Account.firstwp(params[:search])
+
+This performs various checks to ensure SQL injection is impossible. I'm sure you know this, but I have to say it: *DO NOT* pass params into the "find", "all", or "first" methods, otherwise you are opening yourself up to SQL injections.
+
+    # DO NOT DO THIS!
+    accounts = Account.all(params[:search])
+    
+    # OR THIS!
+    accounts = Account.all(:conditions => params[:conditions])
+
+## Available Conditions
+
+Depending on the type, each column comes preloaded with a bunch of nifty conditions:
+
+    all columns
+    => :equals, :does_not_equal
+
+    :string, :text
+    => :begins_with, :contains, :keywords, :ends_with
+
+    :integer, :float, :decimal,:datetime, :timestamp, :time, :date
+    => :greater_than, :greater_than_or_equal_to, :less_than, :less_than_or_equal_to
+
+    tree data structures (see above "searching trees")
+    => :child_of, :sibling_of, :descendent_of, :inclusive_descendent_of
+
+Some of these conditions come with aliases, so you have your choice how to call the conditions. For example you can use "greater\_than" or "gt":
+
+    :equals;                    => :is
+    :does_not_equal             => :is_not, :not
+    :begins_with                => :starts_with
+    :contains                   => :like
+    :greater_than               => :gt, :after
+    :greater_than_or_equal_to   => :at_least, :gte
+    :less_than                  => :lt, :before
+    :less_than_or_equal_to      => :at_most, :lte
+
+### Enhanced searching and blacklisted words
+
+You will notice above there is "contains" and "keywords". The difference is that "keywords" is an enhanced search. It acts like a real keyword search. It finds those keywords, in any order, and blacklists meaningless words such as "and", "the", etc. "contains" finds the EXACT string in the column you are searching, spaces and all.
+
+## Creating your search form
+
+After all of that, here's why I love this plugin:
+
+    <% form_for :search, User.new_conditions, :url => users_path do |f| %>
+        <%= f.text_field :first_name_contains %>
+        <%= f.calendar_date_select :created_at_after %>
+        <%= f.select :age_gt, (1..100) %>
+    <% end %>
+
+## Credits
+
+Author: [Ben Johnson](http://github.com/binarylogic) of [Binary Logic](http://www.binarylogic.com)
+
+Credit to [Zack Ham](http://github.com/zackham) and [Robert Malko](http://github.com/malkomalko/) for helping with feature suggestions, cleaning up the readme / wiki, and cleaning up my code.
+
+
+Copyright (c) 2008 [Ben Johnson](http://github.com/binarylogic) of [Binary Logic](http://www.binarylogic.com), released under the MIT license 

data/Rakefile

@@ -0,0 +1,17 @@
+require 'rubygems'
+require 'echoe'
+
+require File.dirname(__FILE__) << "/lib/searchgasm/version"
+
+Echoe.new 'searchgasm' do |p|
+  p.version = BinaryLogic::Searchgasm::Version::STRING
+  p.author = "Ben Johnson of Binary Logic"
+  p.email  = 'bjohnson@binarylogic.com'
+  p.project = 'searchgasm'
+  p.summary = "Orgasmic ActiveRecord searching"
+  p.description = "Makes ActiveRecord searching easier, robust, and powerful. Automatic conditions, pagination support, object based searching, and more."
+  p.url = "http://github.com/binarylogic/searchgasm"
+  p.dependencies = %w(activerecord)
+  p.include_rakefile = true
+end
+

data/init.rb

@@ -0,0 +1 @@
+require File.dirname(__FILE__) << "/lib/searchgasm"

data/lib/searchgasm/active_record/associations.rb

@@ -0,0 +1,56 @@
+module BinaryLogic
+  module Searchgasm
+    module ActiveRecord
+      module Associations
+        module AssociationCollection
+          def self.included(klass)
+            klass.class_eval do
+              include Protection
+            end
+          end
+          
+          def find_with_searchgasm(*args)
+            options = args.extract_options!
+            args << sanitize_options_with_searchgasm(options)
+            find_without_searchgasm(*args)
+          end
+          
+          def build_conditions(options = {}, &block)
+            @reflection.klass.build_conditions(options.merge(:scope => scope(:find)[:conditions]), &block)
+          end
+        
+          def build_search(options = {}, &block)
+            @reflection.klass.build_search(options.merge(:scope => scope(:find)[:conditions]), &block)
+          end
+        end
+      
+        module HasManyAssociation
+          def count_with_searchgasm(*args)
+            column_name, options = @reflection.klass.send(:construct_count_options_from_args, *args)
+            count_without_searchgasm(column_name, sanitize_options_with_searchgasm(options))
+          end
+        end
+      end
+    end
+  end
+end
+
+ActiveRecord::Associations::AssociationCollection.send(:include, BinaryLogic::Searchgasm::ActiveRecord::Associations::AssociationCollection)
+
+module ::ActiveRecord
+  module Associations
+    class AssociationCollection
+      alias_method_chain :find, :searchgasm
+    end
+  end
+end
+
+ActiveRecord::Associations::HasManyAssociation.send(:include, BinaryLogic::Searchgasm::ActiveRecord::Associations::HasManyAssociation)
+
+module ::ActiveRecord
+  module Associations
+    class HasManyAssociation
+      alias_method_chain :count, :searchgasm
+    end
+  end
+end

data/lib/searchgasm/active_record/base.rb

@@ -0,0 +1,70 @@
+module BinaryLogic
+  module Searchgasm
+    module ActiveRecord
+      module Base
+        def self.included(klass)
+          klass.class_eval do
+            alias_method :new_conditions, :build_conditions
+            alias_method :new_search, :build_search
+            include Protection
+          end
+        end
+        
+        def calculate_with_searchgasm(*args)
+          options = args.extract_options!
+          options = sanitize_options_with_searchgasm(options)
+          args << options
+          calculate_without_searchgasm(*args)
+        end
+        
+        def find_with_searchgasm(*args)
+          options = args.extract_options!
+          options = sanitize_options_with_searchgasm(options)
+          args << options
+          find_without_searchgasm(*args)
+        end
+        
+        def scope_with_searchgasm(method, key = nil)
+          scope = scope_without_searchgasm(method, key)
+          return sanitize_options_with_searchgasm(scope) if key.nil? && method == :find
+          scope
+        end
+        
+        def build_conditions(options = {})
+          BinaryLogic::Searchgasm::Search::Conditions(self, options)
+        end
+        
+        def build_search(options = {})
+          searcher = searchgasm_searcher(options)
+          yield searcher if block_given?
+          searcher
+        end
+        
+        private
+          def sanitize_options_with_searchgasm(options)
+            searchgasm_searcher(options).sanitize
+          end
+          
+          def searchgasm_searcher(options)
+            BinaryLogic::Searchgasm::Search::Base.new(self, options)
+          end
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.send(:extend, BinaryLogic::Searchgasm::ActiveRecord::Base)
+
+module ::ActiveRecord
+  class Base
+    class << self
+      alias_method_chain :calculate, :searchgasm
+      alias_method_chain :find, :searchgasm
+      alias_method_chain :scope, :searchgasm
+      
+      def valid_find_options
+         VALID_FIND_OPTIONS
+       end
+    end
+  end
+end

data/lib/searchgasm/active_record/protection.rb

@@ -0,0 +1,37 @@
+module BinaryLogic
+  module Searchgasm
+    module ActiveRecord
+      module Protection
+        def self.included(klass)
+          klass.class_eval do
+            alias_method :new_search, :build_search
+            alias_method :findwp, :find_with_protection
+            alias_method :allwp, :all_with_protection
+            alias_method :firstwp, :first_with_protection
+          end
+        end
+        
+        def find_with_protection(*args)
+          options = args.extract_options!
+          options.merge!(:protect => true)
+          args << options
+          find(*args)
+        end
+
+        def all_with_protection(*args)
+          options = args.extract_options!
+          options.merge!(:protect => true)
+          args << options
+          all(*args)
+        end
+  
+        def first_with_protection(*args)
+          options = args.extract_options!
+          options.merge!(:protect => true)
+          args << options
+          first(*args)
+        end
+      end
+    end
+  end
+end

data/lib/searchgasm/helpers.rb

@@ -0,0 +1,100 @@
+require "base64"
+
+module BinaryLogic
+  module SearchGasm
+    module Helpers
+      def order_by_link(text, searcher, options = {})
+        options[:order_by] ||= text.underscore.gsub(/ /, "_")
+        options[:order_as] ||= "ASC"
+        options[:form_prefix] ||= determine_form_prefix(searcher)
+    
+        if searcher.order_by == options[:order_by]
+          options[:order_as] = searcher.order_as == "ASC" ? "DESC" : "ASC"
+      
+          text = content_tag("span", text + (searcher.order_as == "ASC" ? " ▲" : " ▼"), :class => searcher.order_as == "ASC" ? "ordering asc" : "ordering desc")
+        end
+    
+        options[:order_by] = Base64.encode64(Marshal.dump(options[:order_by])) if !options[:order_by].nil? && !options[:order_by].is_a?(String) && !options[:order_by].is_a?(Symbol)
+    
+        link_to_function(text, "submit_form({form_prefix: '#{options[:form_prefix]}', dont_reset: true, fields: {order_by: '#{escape_javascript(options[:order_by])}', order_as: '#{options[:order_as]}'}});")
+      end
+  
+      # tag methods
+      #------------------------------------------------------------------------------
+      def page_select_tag(name, items_count, searcher, options = {})
+        options = options.dup
+        form_prefix = options.delete(:form_prefix) || determine_form_prefix(searcher)
+        options[:id] ||= "select_tag_#{unique_id}"
+        options[:onchange] ||= "submit_form({form_prefix: '#{form_prefix}', dont_reset: true, fields: {page: this.value}});"
+        items_count = items_count.to_i
+        per_page = searcher.per_page.to_i
+        page = searcher.page.to_i
+        page = 1 if page < 1
+        page_options = page_options_for_select(items_count, per_page)
+    
+        html = ""
+        if page_options.size > 0
+          html << (button_to_function("Prev", "sel = $('#{options[:id]}'); sel.value = '#{page-1}'; sel.onchange();", :class => "prev_page") + "&nbsp;") if page > 1
+          html << select_tag(name, options_for_select(page_options, page), options)
+          html << ("&nbsp;" + button_to_function("Next", "sel = $('#{options[:id]}'); sel.value = '#{page+1}'; sel.onchange();", :class => "next_page")) if page < page_options.size
+        end
+        
+        html
+      end
+  
+      def per_page_select_tag(name, items_count, searcher, options = {})
+        options = options.dup
+        form_prefix = options.delete(:form_prefix) || determine_form_prefix(searcher)
+        options[:onchange] ||= "submit_form({form_prefix: '#{form_prefix}', dont_reset: true, fields: {per_page: this.value}});"
+        items_count = items_count.to_i
+        per_page = searcher.per_page.to_i
+        per_page = 0 if items_count <= per_page
+    
+        # set up per page options
+        per_page_options = per_page_options_for_select(items_count)
+    
+        return select_tag(name, options_for_select(per_page_options, per_page), options) if per_page_options.size > 0
+    
+        ""
+      end
+  
+      # utility methods
+      #------------------------------------------------------------------------------
+      def page_options_for_select(items_count, per_page)
+        page_count = per_page > 0 ? (items_count.to_f / per_page.to_f).ceil : 1
+        page_options = []
+        if page_count > 1
+          page_count.times do |page|
+            page_number = page + 1
+            page_options << ["Page #{page_number} of #{page_count}", page_number]
+          end
+        end
+        page_options
+      end
+  
+      def per_page_options_for_select(items_count)
+        per_page_options = []
+        per_page_values = [10, 20, 30, 40, 50, 75, 100, 125, 150, 175, 200, 300, 400, 500, 1000, 1500, 2000]
+        per_page_values.each do |per_page_num|
+          if items_count > per_page_num
+            per_page_options << ["#{per_page_num} per page", per_page_num] if per_page_num > 0
+          else
+            break
+          end
+        end
+    
+        if per_page_options.size > 0
+          per_page_options << ["Show all #{items_count}", 0]
+        end
+    
+        per_page_options
+      end
+      
+      def determine_form_prefix(searcher)
+        "#{searcher.class.name.underscore.gsub(/_searcher/, "").pluralize}_search_"
+      end
+    end
+  end
+end
+
+ActionController::Base.helper BinaryLogic::SearchGasm::Helpers