searchgasm 0.9.6 → 0.9.7

data/lib/searchgasm/helpers/search_helper.rb

@@ -0,0 +1,178 @@
+module Searchgasm
+  module Helpers
+    # = Search Helper
+    #
+    # Helper methods for paginating and ordering through a search.
+    module SearchHelper
+      # Creates a link for ordering data in a certain way. See Searchgasm::Config for setting default configuration.
+      #
+      # === Example uses for a User class that has many orders
+      #   order_by(:first_name)
+      #   order_by([:first_name, :last_name])
+      #   order_by({:orders => :total})
+      #   order_bt([{:orders => :total}, :first_name])
+      #
+      # If the output just isn't cutting it for you, then you can pass it a block and it will spit out the result of the block. The block is passed "options" which is all of the information you should need
+      # for doing whatever you need to do. It's the options you are allowed to pass, but with their proper values.
+      #
+      #   <%= order_by(:id) { |options| link_to(options[:text], options[:url], options[:html]) } %>
+      #
+      # or
+      #
+      #   <% order_by(:id) do |options| %><%= link_to(options[:text], options[:url]) %><% end %>
+      #
+      # Another thing to keep in mind is that the value gets "serialized", if it is not a string or a simple, so that it can be passed via a param in the url. Searchgasm will automatically try to "unserializes" this value and use it. This allows you
+      # to pass complex objects besides strings and symbols, such as arrays and hashes.
+      #
+      # === Options
+      # * <tt>:text</tt> -- default: column_name.to_s.humanize, text for the link
+      # * <tt>:desc_indicator</tt> -- default: &nbsp;&#9660;, the indicator that this column is descending
+      # * <tt>:asc_indicator</tt> -- default: &nbsp;&#9650;, the indicator that this column is ascending
+      #
+      # === Advanced Options
+      # * <tt>:action</tt> -- this is automatically determined for you based on the type. For a :select type, its :onchange. For a :links type, its :onclick. You shouldn't have to use this option unless you are doing something out of the norm. The point of this option is to return a URL that will include this.value or not
+      # * <tt>:url</tt> -- default: uses url_for to preserve your params and search, I can not think of a reason to pass this, but its there just incase
+      # * <tt>:html</tt> -- if type is :links then these will apply to the outermost <div>, if type is :select then these will apply to the select tag
+      # * <tt>:search_obj</tt> -- default: @search, this is your search object, if it is in an instance variable other than @search please pass it here. Ex: :@my_search, or :my_search
+      # * <tt>:params_scope</tt> -- default: :search, this is the scope in which your search params will be preserved (params[:search]). If you don't want a scope and want your options to be at base leve in params such as params[:page], params[:per_page], etc, then set this to nil.
+      def order_by(column_name, options = {}, &block)
+        add_searchgasm_helper_defaults!(options, :order_by, column_name)
+        column_name = stringify_everything(column_name)
+        options[:text] = determine_order_by_text(column_name) unless options.has_key?(:text)
+        options[:asc_indicator] ||= Config.asc_indicator
+        options[:desc_indicator] ||= Config.desc_indicator
+        options[:text] += options[:search_obj].desc? ? options[:desc_indicator] : options[:asc_indicator] if options[:search_obj].order_by == column_name
+        
+        if block_given?
+          yield options
+        else
+          if options[:remote]
+            link_to_function(options[:text], options[:url], options[:html])
+          else
+            link_to(options[:text], options[:url], options[:html])
+          end
+        end
+      end
+      
+      # Creates navigation for paginating through a search. See Searchgasm::Config for setting default configuration.
+      #
+      # === Examples
+      #   pages
+      #   pages(:search => @my_search)
+      #   pages(:html => {:id => "my_id"})
+      #
+      # If the output just isn't cutting it for you, then you can pass it a block and it will spit out the result of the block. The block is passed "options" which is all of the information you should need
+      # for doing whatever you need to do. It's the options you are allowed to pass, but with their proper values.
+      #
+      #   <%= pages { |options| select(:search, :page, (1..options[:search_obj].page_count), {}, options[:html]) } %>
+      #
+      # or
+      #
+      #   <% pages do |options| %><%= select(:search, :page, (1..options[:search_obj].page_count), {}, options[:html]) %><% end %>
+      #
+      # === Options
+      # * <tt>:type</tt> -- default: :select, pass :links as an alternative to have flickr like pagination
+      # * <tt>:remote</tt> -- default: false, if true requests will be AJAX
+      #
+      # === Advanced Options
+      # * <tt>:action</tt> -- this is automatically determined for you based on the type. For a :select type, its :onchange. For a :links type, its :onclick. You shouldn't have to use this option unless you are doing something out of the norm. The point of this option is to return a URL that will include this.value or not
+      # * <tt>:url</tt> -- default: uses url_for to preserve your params and search, I can not think of a reason to pass this, but its there just incase
+      # * <tt>:html</tt> -- if type is :links then these will apply to the outermost <div>, if type is :select then these will apply to the select tag
+      # * <tt>:search_obj</tt> -- default: @search, this is your search object, if it is in an instance variable other than @search please pass it here. Ex: :@my_search, or :my_search
+      # * <tt>:params_scope</tt> -- default: :search, this is the scope in which your search params will be preserved (params[:search]). If you don't want a scope and want your options to be at base leve in params such as params[:page], params[:per_page], etc, then set this to nil.
+      def pages(options = {})
+        options[:type] ||= Config.pages_type
+        add_searchgasm_helper_defaults!(options, :page)
+        return "" if options[:search_obj].page_count <= 1
+        
+        if block_given?
+          yield options
+        else
+          case options[:type]
+          when :select
+            options[:html] ||= {}
+            options[:html][options[:action]] ||= ""
+            options[:html][options[:action]] += ";"
+            options[:html][options[:action]] += options[:url]
+            select(:search, :page, (1..options[:search_obj].page_count), {}, options[:html])
+          else
+            # HTML for links
+          end
+        end
+      end
+      
+      # Creates navigation for setting how many items per page. See Searchgasm::Config for setting default configuration.
+      #
+      # === Examples
+      #   per_page
+      #   per_page(:search => @my_search)
+      #   per_page(:choices => [50, 100])
+      #   per_page(:html => {:id => "my_id"})
+      #
+      # If the output just isn't cutting it for you, then you can pass it a block and it will spit out the result of the block. The block is passed "options" which is all of the information you should need
+      # for doing whatever you need to do. It's the options you are allowed to pass, but with their proper values.
+      #
+      #   <%= per_page { |options| select(:search, :per_page, options[:choices], {}, options[:html]) } %>
+      #
+      # or
+      #
+      #   <% per_page do |options| %><%= select(:search, :per_page, options[:choices], {}, options[:html]) %><% end %>
+      #
+      # === Options
+      # * <tt>:type</tt> -- default: :select, pass :links as an alternative to links like: 10 | 25 | 50 | 100, etc
+      # * <tt>:remote</tt> -- default: false, if true requests will be AJAX
+      # * <tt>:choices</tt> -- default: [10, 25, 50, 100, 150, 200, nil], nil means "show all"
+      #
+      # === Advanced Options
+      # * <tt>:choices</tt> -- default: [10, 25, 50, 100, 150, 200, nil], nil means "show all"
+      # * <tt>:action</tt> -- this is automatically determined for you based on the type. For a :select type, its :onchange. For a :links type, its :onclick. You shouldn't have to use this option unless you are doing something out of the norm. The point of this option is to return a URL that will include this.value or not
+      # * <tt>:url</tt> -- default: uses url_for to preserve your params and search, I can not think of a reason to pass this, but its there just incase
+      # * <tt>:html</tt> -- if type is :links then these will apply to the outermost <div>, if type is :select then these will apply to the select tag
+      # * <tt>:search_obj</tt> -- default: @search, this is your search object, if it is in an instance variable other than @search please pass it here. Ex: :@my_search, or :my_search
+      # * <tt>:params_scope</tt> -- default: :search, this is the scope in which your search params will be preserved (params[:search]). If you don't want a scope and want your options to be at base leve in params such as params[:page], params[:per_page], etc, then set this to nil.
+      def per_page(options = {})
+        options[:type] ||= Config.per_page_type
+        add_searchgasm_helper_defaults!(options, :per_page)
+        
+        options[:choices] ||= Config.per_page_choices
+        if !options[:search_obj].per_page.blank? && !options[:choices].include?(options[:search_obj].per_page)
+          options[:choices] << options[:search_obj].per_page
+          has_nil = options[:choices].include?(nil)
+          options[:choices].delete(nil) if has_nil
+          options[:choices].sort!
+          options[:choices] << nil if has_nil
+        end
+        options[:choices] = options[:choices].collect { |choice| [choice == nil ? "Show all" : "#{choice} per page", choice] }
+                
+        if block_given?
+          yield options
+        else
+          case options[:type]
+          when :select
+            options[:html] ||= {}
+            options[:html][options[:action]] ||= ""
+            options[:html][options[:action]] += ";"
+            options[:html][options[:action]] += options[:url]
+            select(:search, :per_page, options[:choices], {}, options[:html])
+          end
+        end
+      end
+      
+      private
+        def determine_order_by_text(column_name, relationship_name = nil)
+          case column_name
+          when String, Symbol
+            relationship_name.blank? ? column_name.titleize : "#{relationship_name.titleize} #{column_name.titleize}"
+          when Array
+            determine_order_by_text(column_name.last)
+          when Hash
+            k = column_name.keys.first
+            v = column_name.values.first
+            determine_order_by_text(v, k)
+          end
+        end
+    end
+  end
+end
+
+ActionController::Base.helper Searchgasm::Helpers::SearchHelper if defined?(ActionController)

data/lib/searchgasm/helpers/utilities_helper.rb

@@ -0,0 +1,125 @@
+module Searchgasm
+  module Helpers #:nodoc:
+    module UtilitiesHelper # :nodoc:
+      private
+        # Adds default options for all helper methods.
+        def add_searchgasm_helper_defaults!(options, method_name, method_value = nil)
+          options[:search_obj] ||= instance_variable_get(Config.search_obj_name)
+          raise(ArgumentError, "@search object could not be inferred, please specify: :search_obj => @search)") unless options[:search_obj].is_a?(Searchgasm::Search::Base)
+          method_value = stringify_everything(method_value) unless method_value.nil?
+          options[:params_scope] = :search unless options.has_key?(:params_scope)
+          options[:remote] = Config.remote_helpers? unless options.has_key?(:remote)
+          
+          if !options.has_key?(:action)
+            if options[:type] == :select
+              options[:action] = :onchange
+            elsif options[:remote]
+              options[:action] = :onclick
+            end
+          end
+          
+          options[:url] = searchgasm_url(options, method_name, method_value) unless options.has_key?(:url)
+
+          options
+        end
+        
+        def searchgasm_url(options, method_name, method_value = nil)
+          params = (params || {}).dup
+          params.delete(:commit)
+          
+          # Extract search params from params
+          search_params = options[:params_scope].blank? ? params : params[options[:params_scope]] ||= {}
+          
+          # Rewrite :order_by and :per_page with what's in our search obj
+          ([:order_by, :per_page] - [method_name]).each { |search_option| search_params[search_option] = options[:search_obj].send(search_option) }
+          
+          # Rewrite :conditions, separated due to unique call
+          conditions = options[:search_obj].conditions.conditions
+          search_params[:conditions] = conditions unless conditions.blank?
+          
+          # Never want to keep page or the option we are trying to set
+          [:page, method_name].each { |option| search_params.delete(option) }
+          
+          # Alternate :order_by if we are ordering
+          if method_name == :order_by
+            search_params[:order_as] = (options[:search_obj].order_by == method_value && options[:search_obj].asc?) ? "DESC" : "ASC"
+          else
+            search_params[:order_as] = options[:search_obj].order_as
+          end
+          
+          # Determine if this.value should be included or not, and set up url
+          url = nil
+          case options[:action]
+          when :onchange
+            # Include this.value
+            url = url_for(params)
+            url_option = CGI.escape((options[:params_scope].blank? ? "#{method_name}" : "#{options[:params_scope]}[#{method_name}]")) + "='+this.value"
+            url += (url.last == "?" ? "" : (url.include?("?") ? "&" : "?")) + url_option
+          else
+            # Build the plain URL
+            search_params[method_name] = method_name == :order_by ? searchgasm_order_by_value(method_value) : method_value
+            url = url_for(params)
+          end
+          
+          # Now update options if remote
+          if options[:remote]
+            url = remote_function(:url => url, :method => :get).gsub(/\\'\+this.value'/, "'+this.value") + ";"
+            
+            update_fields = {method_name => method_value}
+            update_fields[:order_as] = search_params[:order_as] if method_name == :order_by
+            update_fields.each { |field, value| url += ";" + searchgasm_update_search_field_javascript(field, value, options) }
+          elsif !options[:action].blank?
+            # Add some javascript if its onclick
+            url = "window.location = '" + url + ";"
+          end
+          
+          url
+        end
+        
+        def searchgasm_update_search_field_javascript(field, value, options)
+          field_value = nil
+          
+          case options[:action]
+          when :onchange
+            field_value = "this.value";
+          else
+            field_value = field == :order_by ? searchgasm_order_by_value(value) : value
+            field_value = "'#{CGI.escape(field_value)}'"
+          end
+          
+          field_name = options[:params_scope] ? "#{options[:params_scope]}[#{field}]" : "#{field}"
+          "#{field} = $('#{searchgasm_form_id(options[:search_obj])}').getInputs('hidden', '#{field_name}'); if(#{field}.length > 0) {  #{field}[0].value = #{field_value}; }"
+        end
+        
+        def searchgasm_form_id(search_obj)
+          "#{search_obj.klass.name.pluralize.underscore}_search_form"
+        end
+        
+        def searchgasm_order_by_value(order_by)
+          case order_by
+          when String
+            order_by
+          when Array, Hash
+            [Marshal.dump(order_by)].pack("m")
+          end
+        end
+        
+        def stringify_everything(obj)
+          case obj
+          when String
+            obj
+          when Symbol
+            obj = obj.to_s
+          when Array
+            obj = obj.collect { |item| stringify_everything(item) }
+          when Hash
+            new_obj = {}
+            obj.each { |key, value| new_obj[key.to_s] = stringify_everything(value) }
+            new_obj
+          end
+        end
+    end
+  end
+end
+
+ActionController::Base.helper(Searchgasm::Helpers::UtilitiesHelper) if defined?(ActionController)

data/lib/searchgasm/search/base.rb

@@ -1,183 +1,77 @@
-module BinaryLogic
-  module Searchgasm
-    module Search      
-      class Base
-        include Utilities
-        
-        SPECIAL_FIND_OPTIONS = [:order_by, :order_as, :page, :per_page]
-        VALID_FIND_OPTIONS = ::ActiveRecord::Base.valid_find_options + SPECIAL_FIND_OPTIONS
-        SAFE_OPTIONS = SPECIAL_FIND_OPTIONS + [:conditions, :limit, :offset]
-        VULNERABLE_OPTIONS = VALID_FIND_OPTIONS - SAFE_OPTIONS
-        
-        attr_accessor :klass
-        attr_reader :conditions, :protect
-        attr_writer :options
-        
-        def self.needed?(klass, options)
-          SPECIAL_FIND_OPTIONS.each do |option|
-            return true if options.symbolize_keys.keys.include?(option)
-          end
-          
-          Conditions.needed?(klass, options[:conditions])
-        end
-        
-        def initialize(klass, options = {})
-          self.klass = klass
-          self.conditions = Conditions.new(klass)
-          self.options = options
-        end
-        
-        # Setup methods for all options for finding
-        (::ActiveRecord::Base.valid_find_options - [:conditions]).each do |option|
-          class_eval <<-end_eval
-            def #{option}(sanitize = false); options[:#{option}]; end
-            def #{option}=(value); self.options[:#{option}] = value; end
-          end_eval
-        end
-                
-        alias_method :per_page, :limit
-        
-        # Setup methods for searching
-        [:all, :average, :calculate, :count, :find, :first, :maximum, :minimum, :sum].each do |method|
-          class_eval <<-end_eval
-            def #{method}(*args)
-              self.options = args.extract_options!
-              args << sanitize
-              klass.#{method}(*args)
-            end
-          end_eval
-        end
-        
-        def conditions=(value)
-          case value
-          when Conditions
-            @conditions = value
-          else
-            @conditions.value = value
-          end
-        end
-        
-        def conditions(sanitize = false)
-          sanitize ? @conditions.sanitize : @conditions
-        end
-        
-        def include(sanitize = false)
-          includes = [self.options[:include], conditions.includes].flatten.compact
-          includes.blank? ? nil : (includes.size == 1 ? includes.first : includes)
-        end
-        
-        def inspect
-          options_as_nice_string = ::ActiveRecord::Base.valid_find_options.collect { |name| "#{name}: #{send(name)}" }.join(", ")
-          "#<#{klass} #{options_as_nice_string}>"
-        end
-        
-        def limit=(value)
-          return options[:limit] = nil if value.nil? || value == 0
-          
-          old_limit = options[:limit]
-          options[:limit] = value
-          self.page = @page if !@page.blank? # retry page now that limit is set
-          value
-        end
-        alias_method :per_page=, :limit=
-        
-        def options
-          @options ||= {}
-        end
-        
-        def options=(values)
-          return unless values.is_a?(Hash)
-          self.protect = values.delete(:protect) if values.has_key?(:protect) # make sure we do this first
-          values.symbolize_keys.assert_valid_keys(VALID_FIND_OPTIONS)
-          frisk!(values) if protect?
-          values.each { |option, value| send("#{option}=", value) }
-        end
-        
-        def order_as
-          return "DESC" if order.blank?
-          order =~ /ASC$/i ? "ASC" : "DESC"
-        end
-        
-        def order_as=(value)
-          # reset order
-        end
-        
-        def order_by
-          # need to return a cached value of order_by, not smart to figure it out from order
-        end
-        
-        def order_by=(value)
-          # do your magic here and set order approperiately
-        end
-        
-        def page
-          return 1 if offset.blank?
-          (offset.to_f / limit).ceil
-        end
-        
-        def page=(value)
-          return self.offset = nil if value.nil?
-          
-          if limit.blank?
-            @page = value
-          else
-            @page = nil
-            self.offset = value * limit
-          end
-          value
-        end
-        
-        def protect=(value)
-          conditions.protect = value
-          @protect = value
-        end
-        
-        def protect?
-          protect == true
-        end
-        
-        def sanitize
-          find_options = {}
-          ::ActiveRecord::Base.valid_find_options.each do |find_option|
-            value = send(find_option, true)
-            next if value.blank?
-            find_options[find_option] = value
-          end
-          find_options
-        end
-        
-        def scope
-          conditions.scope
-        end
-        
-        def scope=(value)
-          conditions.scope = value
-        end
-        
-        private
-          def order_by_safe?(order_by)
-            return true if order_by.blank?
-            
-            column_names = klass.column_names
-            
-            [order_by].flatten.each do |column|
-              case column
-              when Hash
-                return false unless order_by_safe?(column.to_a)
-              when Array
-                return false unless order_by_safe?(column)
-              else
-                return false unless column_names.include?(column)
-              end
-            end
-            
-            true
-          end
-          
-          def frisk!(options)
-            options.symbolize_keys.assert_valid_keys(SAFE_OPTIONS)
-            raise(ArgumentError, ":order_by can only contain colum names in the string, hash, or array format") unless order_by_safe?(options[:order_by])
+module Searchgasm #:nodoc:
+  module Search #:nodoc:
+    # = Searchgasm
+    #
+    # Please refer the README.rdoc for usage, examples, and installation.
+    
+    class Base
+      include Searchgasm::Utilities
+      
+      # Options that ActiveRecord doesn't suppport, but Searchgasm does
+      SPECIAL_FIND_OPTIONS = [:order_by, :order_as, :page, :per_page]
+      
+      # Valid options you can use when searching
+      VALID_FIND_OPTIONS = ::ActiveRecord::Base.valid_find_options + SPECIAL_FIND_OPTIONS
+      
+      # Use these methods just like you would in ActiveRecord
+      SEARCH_METHODS = [:all, :average, :calculate, :count, :find, :first, :maximum, :minimum, :sum]
+      
+      attr_accessor :klass, *::ActiveRecord::Base.valid_find_options
+      
+      # Used in the ActiveRecord methods to determine if Searchgasm should get involved or not.
+      # This keeps Searchgasm out of the way unless it is needed.
+      def self.needed?(klass, options)
+        SPECIAL_FIND_OPTIONS.each do |option|
+          return true if options.symbolize_keys.keys.include?(option)
+        end
+        
+        Searchgasm::Conditions::Base.needed?(klass, options[:conditions])
+      end
+      
+      def initialize(klass, init_options = {})
+        self.klass = klass
+        self.options = init_options
+      end
+      
+      # Setup methods for searching
+      SEARCH_METHODS.each do |method|
+        class_eval <<-"end_eval", __FILE__, __LINE__
+          def #{method}(*args)
+            self.options = args.extract_options!
+            args << sanitize(:#{method})
+            klass.#{method}(*args)
           end
+        end_eval
+      end
+      
+      def inspect
+        options_as_nice_string = ::ActiveRecord::Base.valid_find_options.collect { |name| "#{name}: #{send(name)}" }.join(", ")
+        "#<#{klass} #{options_as_nice_string}>"
+      end
+      
+      def limit=(value)
+        @limit = value.blank? || value == 0 ? nil : value.to_i
+      end
+      
+      def offset=(value)
+        @offset = value.to_i
+      end
+      
+      def options=(values)
+        return unless values.is_a?(Hash)
+        values.symbolize_keys.assert_valid_keys(VALID_FIND_OPTIONS)
+        values.each { |option, value| send("#{option}=", value) }
+      end
+      
+      # Sanitizes everything down into options ActiveRecord::Base.find can understand
+      def sanitize(for_method = nil)
+        find_options = {}
+        ::ActiveRecord::Base.valid_find_options.each do |find_option|
+          value = send(find_option)
+          next if value.blank? || (for_method == :count && [:limit, :offset].include?(find_option))
+          find_options[find_option] = value
+        end
+        find_options
       end
     end
   end