searchgasm 1.2.0 → 1.2.1

data/CHANGELOG.rdoc

@@ -1,3 +1,14 @@
+== 1.2.1 released 2008-09-24
+
+* Fixed problem when determining if an order_by_link is currently being ordered. Just "stringified" both comparable values.
+* Removed default order_by and order_as. They will ONLY have values if you specify how to order, otherwise they are nil.
+* Removed order_as requirement. order_as is optional.
+* Added in deep_merge methods for hash, copied over from ActiveSupport 2.1
+* Improved order by auto joins to be based off of what order_by returns instead of setting it when setting order_by.
+* Added priority_order_by. Useful if you want to order featured products first and then order as usual. See documentation in Searchgasm::Search::Ordering for more info.
+* Added in base64 support for order_by and priority_order_by so that it's value is safe in the URL
+* Added priority_order_by_link
+
 == 1.2.0 released 2008-09-24
 
 * Added searchgasm_params and searchgasm_url helper to use outside of the control type helpers.

data/Rakefile

@@ -10,7 +10,6 @@ Echoe.new 'searchgasm' do |p|
   p.project = 'searchgasm'
   p.summary = "Object based ActiveRecord searching, ordering, pagination, and more!"
   p.url = "http://github.com/binarylogic/searchgasm"
-  p.dependencies = ['activerecord', 'activesupport >= 2.1.0']
+  p.dependencies = ['activerecord', 'activesupport']
   p.include_rakefile = true
-end
-
+end

data/lib/searchgasm/config.rb

@@ -44,7 +44,7 @@ module Searchgasm
       end
       
       def hidden_fields # :nodoc:
-        @hidden_fields ||= (Search::Base::SPECIAL_FIND_OPTIONS - [:page])
+        @hidden_fields ||= (Search::Base::SPECIAL_FIND_OPTIONS - [:page, :priority_order])
       end
       
       # Which hidden fields to automatically include when creating a form with a Searchgasm object. See Searchgasm::Helpers::Form for more info.
@@ -135,7 +135,7 @@ module Searchgasm
       # The reason for this not to disturb regular queries such as Whatever.find(:all). You would not expect that to be limited.
       #
       # * <tt>Default:</tt> The 3rd option in your per_page_choices, default of 50
-      # * <tt>Accepts:</tt> Any value in your per_page choices, nil means "show all"
+      # * <tt>Accepts:</tt> Any value in your per_page choices, nil or a blank string means "show all"
       def per_page=(value)
         @per_page = value
       end

data/lib/searchgasm/core_ext/hash.rb

@@ -16,19 +16,53 @@ module Searchgasm
         new_hash
       end
       
-      def deep_delete_duplicates(hash)
+      def deep_delete_duplicate_keys(hash)
         hash.each do |k, v|
           if v.is_a?(Hash) && self[k]
             self[k].deep_delete_duplicates(v)
-            self.delete(k) if self[k].blank?
+            delete(k) if self[k].blank?
           else
-            self.delete(k)
+            delete(k)
           end
         end
         
         self
       end
       
+      def deep_delete(value)
+        case value
+        when Array
+          value.each { |v| deep_delete(v) }
+        when Hash
+          value.each do |k, v|
+            next unless self[k].is_a?(Hash)
+            
+            case v
+            when Hash, Array
+              self[k].deep_delete(v)
+            when String, Symbol
+              self[k].delete(v)
+            end
+          end
+        when String, Symbol
+          delete(value)
+        end
+      end
+      
+      def deep_merge(other_hash)
+        self.merge(other_hash) do |key, oldval, newval|
+          oldval = oldval.to_hash if oldval.respond_to?(:to_hash)
+          newval = newval.to_hash if newval.respond_to?(:to_hash)
+          oldval.class.to_s == 'Hash' && newval.class.to_s == 'Hash' ? oldval.deep_merge(newval) : newval
+        end
+      end
+
+      # Returns a new hash with +self+ and +other_hash+ merged recursively.
+      # Modifies the receiver in place.
+      def deep_merge!(other_hash)
+        replace(deep_merge(other_hash))
+      end
+      
       # assert_valid_keys was killing performance. Array.flatten was the culprit, so I rewrote this method, got a 35% performance increase
       def fast_assert_valid_keys(valid_keys)
         unknown_keys = keys - valid_keys

data/lib/searchgasm/helpers/control_types/link.rb

@@ -80,7 +80,10 @@ module Searchgasm
         # === Advanced Options
         # * <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.
         # * <tt>:search_obj</tt> -- default: @#{params_scope}, this is your search object, everything revolves around this. It will try to infer the name from your params_scope. If your params_scope is :search it will try to get @search, etc. If it can not be inferred by this, you need to pass the object itself.
-        # * <tt>:url_params</tt> -- default: nil, Additional params to add to the url, must be a hash
+        # * <tt>:params</tt> -- default: nil, Additional params to add to the url, must be a hash
+        # * <tt>:exclude_params</tt> -- default: nil, params you want to exclude. This is nifty because it does a "deep delete". So you can pass {:param1 => {:param2 => :param3}} and it will make sure param3 does not get include. param1 and param2 will not be touched. This also accepts an array or just a symbol or string.
+        # * <tt>:search_params</tt> -- default: nil, Additional search params to add to the url, must be a hash. Adds the options into the :params_scope.
+        # * <tt>:exclude_search_params</tt> -- default: nil, Same as :exclude_params but for the :search_params.
         def order_by_link(order_by, options = {})
           order_by = deep_stringify(order_by)
           add_order_by_link_defaults!(order_by, options)
@@ -110,7 +113,10 @@ module Searchgasm
         # === Advanced Options
         # * <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.
         # * <tt>:search_obj</tt> -- default: @#{params_scope}, this is your search object, everything revolves around this. It will try to infer the name from your params_scope. If your params_scope is :search it will try to get @search, etc. If it can not be inferred by this, you need to pass the object itself.
-        # * <tt>:url_params</tt> -- default: nil, Additional params to add to the url, must be a hash
+        # * <tt>:params</tt> -- default: nil, Additional params to add to the url, must be a hash
+        # * <tt>:exclude_params</tt> -- default: nil, params you want to exclude. This is nifty because it does a "deep delete". So you can pass {:param1 => {:param2 => :param3}} and it will make sure param3 does not get include. param1 and param2 will not be touched. This also accepts an array or just a symbol or string.
+        # * <tt>:search_params</tt> -- default: nil, Additional search params to add to the url, must be a hash. Adds the options into the :params_scope.
+        # * <tt>:exclude_search_params</tt> -- default: nil, Same as :exclude_params but for the :search_params.
         def order_as_link(order_as, options = {})
           add_order_as_link_defaults!(order_as, options)
           html = searchgasm_state_for(:order_as, options)
@@ -124,6 +130,48 @@ module Searchgasm
           html
         end
         
+        # This is similar to order_by_link but with a small difference. The best way to explain priority ordering is with an example. Let's say you wanted to list products on a page. You have "featured" products
+        # that you want to show up first, no matter what. This is what this is all about. It makes ordering by featured products a priority, then searching by price, quantity, etc. is the same as it has always been.
+        #
+        # The difference between order_by_link and priority_order_by_link is that priority_order_by_link it just a switch. Turn it on or turn it off. You don't neccessarily want to flip between ASC and DESC. If you do
+        # then you should just incorporate this into your regular order_by, like: order_by_link [:featured, :price]
+        #
+        # === Example uses for a User class that has many orders
+        #
+        #   priority_order_by_link(:featured, "DESC")
+        #   order_by_link([:featured, :created_at], "ASC")
+        #   order_by_link({:orders => :featured}, "ASC")
+        #   order_by_link([{:orders => :featured}, :featured], "ASC")
+        #   order_by_link(:featured, "ASC", :text => "Featured", :html => {:class => "featured_link"})
+        #
+        # === Options
+        # * <tt>:activate_text</tt> -- default: "Show #{column_name.to_s.humanize} first"
+        # * <tt>:deactivate_text</tt> -- default: "Don't show #{column_name.to_s.humanize} first", text for the link, text for the link
+        # * <tt>:column_name</tt> -- default: column_name.to_s.humanize, automatically inferred by what you are ordering by and is added into the active_text and deactive_text strings.
+        # * <tt>:text</tt> -- default: :activate_text or :deactivate_text depending on if its active or not, Overwriting this will make this text stay the same, no matter way. A good alternative would be "Toggle featured first"
+        # * <tt>:html</tt> -- html arrtributes for the <a> tag.
+        #
+        # === Advanced Options
+        # * <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.
+        # * <tt>:search_obj</tt> -- default: @#{params_scope}, this is your search object, everything revolves around this. It will try to infer the name from your params_scope. If your params_scope is :search it will try to get @search, etc. If it can not be inferred by this, you need to pass the object itself.
+        # * <tt>:params</tt> -- default: nil, Additional params to add to the url, must be a hash
+        # * <tt>:exclude_params</tt> -- default: nil, params you want to exclude. This is nifty because it does a "deep delete". So you can pass {:param1 => {:param2 => :param3}} and it will make sure param3 does not get include. param1 and param2 will not be touched. This also accepts an array or just a symbol or string.
+        # * <tt>:search_params</tt> -- default: nil, Additional search params to add to the url, must be a hash. Adds the options into the :params_scope.
+        # * <tt>:exclude_search_params</tt> -- default: nil, Same as :exclude_params but for the :search_params.
+        def priority_order_by_link(priority_order_by, priority_order_as, options = {})
+          priority_order_by = deep_stringify(priority_order_by)
+          add_priority_order_by_link_defaults!(priority_order_by, priority_order_as, options)
+          html = searchgasm_state_for(:priority_order_by, options) + searchgasm_state_for(:priority_order_as, options)
+          
+          if !options[:is_remote]
+            html += link_to(options[:text], options[:url], options[:html])
+          else
+            html += link_to_remote(options[:text], options[:remote].merge(:url => options[:url]), options[:html])
+          end
+          
+          html
+        end
+        
         # Creates a link for limiting how many items are on each page
         #
         # === Example uses
@@ -141,7 +189,10 @@ module Searchgasm
         # === Advanced Options
         # * <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.
         # * <tt>:search_obj</tt> -- default: @#{params_scope}, this is your search object, everything revolves around this. It will try to infer the name from your params_scope. If your params_scope is :search it will try to get @search, etc. If it can not be inferred by this, you need to pass the object itself.
-        # * <tt>:url_params</tt> -- default: nil, Additional params to add to the url, must be a hash
+        # * <tt>:params</tt> -- default: nil, Additional params to add to the url, must be a hash
+        # * <tt>:exclude_params</tt> -- default: nil, params you want to exclude. This is nifty because it does a "deep delete". So you can pass {:param1 => {:param2 => :param3}} and it will make sure param3 does not get include. param1 and param2 will not be touched. This also accepts an array or just a symbol or string.
+        # * <tt>:search_params</tt> -- default: nil, Additional search params to add to the url, must be a hash. Adds the options into the :params_scope.
+        # * <tt>:exclude_search_params</tt> -- default: nil, Same as :exclude_params but for the :search_params.
         def per_page_link(per_page, options = {})
           add_per_page_link_defaults!(per_page, options)
           html = searchgasm_state_for(:per_page, options)
@@ -170,7 +221,10 @@ module Searchgasm
         # === Advanced Options
         # * <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.
         # * <tt>:search_obj</tt> -- default: @#{params_scope}, this is your search object, everything revolves around this. It will try to infer the name from your params_scope. If your params_scope is :search it will try to get @search, etc. If it can not be inferred by this, you need to pass the object itself.
-        # * <tt>:url_params</tt> -- default: nil, Additional params to add to the url, must be a hash
+        # * <tt>:params</tt> -- default: nil, Additional params to add to the url, must be a hash
+        # * <tt>:exclude_params</tt> -- default: nil, params you want to exclude. This is nifty because it does a "deep delete". So you can pass {:param1 => {:param2 => :param3}} and it will make sure param3 does not get include. param1 and param2 will not be touched. This also accepts an array or just a symbol or string.
+        # * <tt>:search_params</tt> -- default: nil, Additional search params to add to the url, must be a hash. Adds the options into the :params_scope.
+        # * <tt>:exclude_search_params</tt> -- default: nil, Same as :exclude_params but for the :search_params.
         def page_link(page, options = {})
           add_page_link_defaults!(page, options)
           html = searchgasm_state_for(:page, options)
@@ -190,7 +244,7 @@ module Searchgasm
             options[:text] ||= determine_order_by_text(order_by)
             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 == order_by
+            options[:text] += options[:search_obj].desc? ? options[:desc_indicator] : options[:asc_indicator] if deep_stringify(options[:search_obj].order_by) == order_by
             options[:url] = searchgasm_params(options.merge(:search_params => {:order_by => order_by}))
             options
           end
@@ -202,6 +256,22 @@ module Searchgasm
             options
           end
           
+          def add_priority_order_by_link_defaults!(priority_order_by, priority_order_as, options = {})
+            add_searchgasm_control_defaults!(:priority_order_by, options)
+            options[:column_name] ||= determine_order_by_text(priority_order_by).downcase 
+            options[:activate_text] ||= "Show #{options[:column_name]} first"
+            options[:deactivate_text] ||= "Don't show #{options[:column_name]} first"
+            active = deep_stringify(options[:search_obj].priority_order_by) == priority_order_by && options[:search_obj].priority_order_as == priority_order_as
+            options[:text] ||= active ? options[:deactivate_text] : options[:activate_text]
+            if active
+              options.merge!(:search_params => {:priority_order_by => nil, :priority_order_as => nil})
+            else
+              options.merge!(:search_params => {:priority_order_by => priority_order_by, :priority_order_as => priority_order_as})
+            end
+            options[:url] = searchgasm_params(options)
+            options
+          end
+          
           def add_per_page_link_defaults!(per_page, options = {})
             add_searchgasm_control_defaults!(:per_page, options)
             options[:text] ||= per_page.blank? ? "Show all" : "#{per_page} per page"
@@ -234,13 +304,15 @@ module Searchgasm
             when String
               obj
             when Symbol
-              obj = obj.to_s
+              obj.to_s
             when Array
-              obj = obj.collect { |item| deep_stringify(item) }
+              obj.collect { |item| deep_stringify(item) }
             when Hash
               new_obj = {}
               obj.each { |key, value| new_obj[key.to_s] = deep_stringify(value) }
               new_obj
+            else
+              obj
             end
           end
       end

data/lib/searchgasm/helpers/control_types/remote_select.rb

@@ -23,7 +23,7 @@ module Searchgasm
           per_page_select(options)
         end
         
-        # Please see page_links. All options are the same and applicable here, excep the :prev, :next, :first, and :last options. The only difference is that instead of a group of links, this gets returned as a select form element that will perform the same function when the value is changed.
+        # Please see page_links. All options are the same and applicable here, except the :prev, :next, :first, and :last options. The only difference is that instead of a group of links, this gets returned as a select form element that will perform the same function when the value is changed.
         def remote_page_select(options = {})
           add_remote_defaults!(options)
           page_select(options)

data/lib/searchgasm/helpers/form.rb

@@ -122,7 +122,7 @@ module Searchgasm
             options = args.extract_options!
             options
             search_options[:hidden_fields].each do |field|
-              html = hidden_field(name, field, :object => search_object, :id => "#{name}_#{field}_hidden", :value => (field == :order_by ? searchgasm_order_by_value(search_object.order_by) : search_object.send(field)))
+              html = hidden_field(name, field, :object => search_object, :id => "#{name}_#{field}_hidden", :value => (field == :order_by ? searchgasm_base64_value(search_object.order_by) : search_object.send(field)))
               
               # For edge rails and older version compatibility, passing a binding to concat was deprecated
               begin

data/lib/searchgasm/helpers/utilities.rb

@@ -1,11 +1,31 @@
 module Searchgasm
   module Helpers #:nodoc:
     module Utilities # :nodoc:
-      # Builds a hash of params for creating a url.
+      # Builds a hash of params for creating a url and preserves any existing params. You can pass this into url_for and build your url. Although most rails helpers accept a hash.
+      #
+      # Let's take the page_link helper. Here is the code behind that helper:
+      #
+      #   link_to("Page 2", searchgasm_params(:search_params => {:page => 2}))
+      #
+      # That's pretty much it. So if you wanted to roll your own link to execute a search, go for it. It's pretty simple. Pass conditions instead of the page, set how the search will be ordered, etc.
+      #
+      # <b>Be careful</b> when taking this approach though. Searchgasm helps you out when you use form_for. For example, when you use the per_page_select helper, it adds in a hidden form field with the value of the page. So when
+      # your search form is submitted it searches the document for that element, finds the current value, which is the current per_page value, and includes that in the search. So when a user searches the per_page
+      # value stays consistent. If you use the searchgasm_params you are on your own. I am always curious how people are using searchgasm. So if you are building your own helpers contact me and maybe I can help you
+      # and add in a helper for you, making it an *official* feature.
+      #
+      # === Options
+      # * <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.
+      # * <tt>:search_obj</tt> -- default: @#{params_scope}, this is your search object, everything revolves around this. It will try to infer the name from your params_scope. If your params_scope is :search it will try to get @search, etc. If it can not be inferred by this, you need to pass the object itself.
+      # * <tt>:params</tt> -- default: nil, Additional params to add to the url, must be a hash
+      # * <tt>:exclude_params</tt> -- default: nil, params you want to exclude. This is nifty because it does a "deep delete". So you can pass {:param1 => {:param2 => :param3}} and it will make sure param3 does not get include. param1 and param2 will not be touched. This also accepts an array or just a symbol or string.
+      # * <tt>:search_params</tt> -- default: nil, Additional search params to add to the url, must be a hash. Adds the options into the :params_scope.
+      # * <tt>:exclude_search_params</tt> -- default: nil, Same as :exclude_params but for the :search_params.
       def searchgasm_params(options = {})
         add_searchgasm_defaults!(options)
         options[:search_params] ||= {}
         options[:literal_search_params] ||= {}
+        
         options[:params] ||= {}
         params_copy = params.deep_dup.with_indifferent_access
         search_params = options[:params_scope].blank? ? params_copy : params_copy.delete(options[:params_scope])
@@ -13,18 +33,22 @@ module Searchgasm
         search_params = search_params.with_indifferent_access
         search_params.delete(:commit)
         search_params.delete(:page)
-        search_params.deep_delete_duplicates(options[:literal_search_params])
+        search_params.deep_delete_duplicate_keys(options[:literal_search_params])
+        search_params.deep_delete(options[:exclude_search_params])
         
         if options[:search_params]
           search_params.deep_merge!(options[:search_params])
           
           if options[:search_params][:order_by] && !options[:search_params][:order_as]
-            search_params[:order_as] = (options[:search_obj].order_by == options[:search_params][:order_by] && options[:search_obj].asc?) ? "DESC" : "ASC"
+            search_params[:order_as] = (options[:search_obj].order_by == options[:search_params][:order_by] && options[:search_obj].asc?) ? "DESC" : "ASC" 
           end
+          
+          [:order_by, :priority_order_by].each { |base64_field| search_params[base64_field] = searchgasm_base64_value(search_params[base64_field]) if search_params.has_key?(base64_field) }
         end
         
         new_params = params_copy
         new_params.deep_merge!(options[:params])
+        new_params.deep_delete(options[:exclude_params])
         
         if options[:params_scope].blank? || search_params.blank?
           new_params
@@ -33,6 +57,32 @@ module Searchgasm
         end
       end
       
+      # Similar to searchgasm_hash, but instead returns a string url. The reason this exists is to assist in creating urls in javascript. It's the muscle behind all of the select helpers that searchgasm provides.
+      # Take the instance where you want to do:
+      #
+      #   :onchange => "window.location = '#{url_for(searchgasm_params)}&my_param=' + this.value;"
+      #
+      # Well the above obviously won't work. Do you need to apped the url with a ? or a &? What about that tricky :params_scope? That's where this is handy, beacuse it does all of the params string building for you. Check it out:
+      #
+      #   :onchange => "window.location = '" + searchgasm_url(:literal_search_params => {:per_page => "' + escape(this.value) + '"}) + "';"
+      #
+      # or what about something a little more tricky?
+      #
+      #   :onchange => "window.location = '" + searchgasm_url(:literal_search_params => {:conditions => {:name_contains => "' + escape(this.value) + '"}}) + "';"
+      #
+      # I have personally used this for an event calendar. Above the calendar there was a drop down for each month. Here is the code:
+      #
+      #   :onchange => "window.location = '" + searchgasm_url(:literal_search_params => {:conditions => {:occurs_at_after => "' + escape(this.value) + '"}}) + "';"
+      #
+      # Now when the user changes the month in the drop down it just runs a new search that sets my conditions to occurs_at_after = selected month. Then in my controller I set occurs_at_before = occurs_at_after.at_end_of_month.
+      #
+      # === Options
+      # * <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.
+      # * <tt>:search_obj</tt> -- default: @#{params_scope}, this is your search object, everything revolves around this. It will try to infer the name from your params_scope. If your params_scope is :search it will try to get @search, etc. If it can not be inferred by this, you need to pass the object itself.
+      # * <tt>:params</tt> -- default: nil, Additional params to add to the url, must be a hash
+      # * <tt>:exclude_params</tt> -- default: nil, params you want to exclude. This is nifty because it does a "deep delete". So you can pass {:param1 => {:param2 => :param3}} and it will make sure param3 does not get include. param1 and param2 will not be touched. This also accepts an array or just a symbol or string.
+      # * <tt>:search_params</tt> -- default: nil, Additional search params to add to the url, must be a hash. Adds the options into the :params_scope.
+      # * <tt>:exclude_search_params</tt> -- default: nil, Same as :exclude_params but for the :search_params.
       def searchgasm_url(options = {})
         search_params = searchgasm_params(options)
         url = url_for(search_params)
@@ -65,7 +115,7 @@ module Searchgasm
           html_options[:class] = classes.join(" ")
         end
         
-        def searchgasm_order_by_value(order_by)
+        def searchgasm_base64_value(order_by)
           case order_by
           when String
             order_by
@@ -79,7 +129,7 @@ module Searchgasm
           html = ""
           unless @added_state_for.include?(option)
             value = options[:search_obj].send(option)
-            html = hidden_field(options[:params_scope], option, :value => (option == :order_by ? searchgasm_order_by_value(value) : value))
+            html = hidden_field(options[:params_scope], option, :value => (option == :order_by ? searchgasm_base64_value(value) : value))
             @added_state_for << option
           end
           html

data/lib/searchgasm/search/base.rb

@@ -16,7 +16,7 @@ module Searchgasm #:nodoc:
       AR_OPTIONS = (AR_FIND_OPTIONS + AR_CALCULATIONS_OPTIONS).uniq
       
       # Options that ActiveRecord doesn't suppport, but Searchgasm does
-      SPECIAL_FIND_OPTIONS = [:order_by, :order_as, :page, :per_page]
+      SPECIAL_FIND_OPTIONS = [:order_by, :order_as, :page, :per_page, :priority_order, :priority_order_by, :priority_order_as]
       
       # Valid options you can use when searching
       OPTIONS = SPECIAL_FIND_OPTIONS + AR_OPTIONS # the order is very important, these options get set in this order
@@ -100,13 +100,7 @@ module Searchgasm #:nodoc:
       def options=(values)
         return unless values.is_a?(Hash)
         values.symbolize_keys.fast_assert_valid_keys(OPTIONS)
-        
-        OPTIONS.each do |option|
-          next unless values.has_key?(option)
-          send("#{option}=", values[option])
-        end
-        
-        values
+        values.each { |key, value| send("#{key}=", value) }
       end
       
       # Sanitizes everything down into options ActiveRecord::Base.find can understand

data/lib/searchgasm/search/ordering.rb

@@ -20,75 +20,67 @@ module Searchgasm
         klass.class_eval do
           alias_method_chain :auto_joins, :ordering
           alias_method_chain :order=, :ordering
+          alias_method_chain :sanitize, :ordering
+          attr_reader :priority_order
         end
       end
       
       def auto_joins_with_ordering # :nodoc:
-        @memoized_auto_joins ||= merge_joins(auto_joins_without_ordering, order_by_auto_joins)
+        @memoized_auto_joins ||= merge_joins(auto_joins_without_ordering, order_by_auto_joins, priority_order_by_auto_joins)
       end
       
       def order_with_ordering=(value) # :nodoc
         @order_by = nil
         @order_as = nil
-        self.order_by_auto_joins.clear
+        @order_by_auto_joins = nil
         @memoized_auto_joins = nil
         self.order_without_ordering = value
       end
       
       # Convenience method for determining if the ordering is ascending
       def asc?
+        return false if order_as.nil?
         !desc?
       end
       
       # Convenience method for determining if the ordering is descending
       def desc?
+        return false if order_as.nil?
         order_as == "DESC"
       end
       
       # Determines how the search is being ordered: as DESC or ASC
       def order_as
-        @order_as ||= (order.blank? || order =~ /ASC$/i) ? "ASC" : "DESC"
+        return if order.blank?
+        return @order_as if @order_as
+        
+        case order
+        when /ASC$/i
+          @order_as = "ASC"
+        when /DESC$/i 
+          @order_as = "DESC"
+        else
+          nil
+        end
       end
       
       # Sets how the results will be ordered: ASC or DESC
       def order_as=(value)
-        value = value.to_s.upcase
-        raise(ArgumentError, "order_as only accepts a string as ASC or DESC") unless ["ASC", "DESC"].include?(value)
-        
-        if order.blank?
-          @order = order_by_to_order(order_by, value)
-        else
+        value = value.blank? ? nil : value.to_s.upcase
+        raise(ArgumentError, "order_as only accepts a blank string / nil or a string as 'ASC' or 'DESC'") if !value.blank? && !["ASC", "DESC"].include?(value)
+        if @order_by
+          @order = order_by_to_order(@order_by, value)
+        elsif order
           @order.gsub!(/(ASC|DESC)/i, value)
         end
-        
         @order_as = value
       end
       
       # Determines by what columns the search is being ordered. This is nifty in that is reverse engineers the order SQL to determine this, only
       # if you haven't explicitly set the order_by option yourself.
       def order_by
-        return @order_by if @order_by
-        
-        if !order.blank?
-          # Reversege engineer order, only go 1 level deep with relationships, anything beyond that is probably excessive and not good for performance
-          order_parts = order.split(",").collect do |part|
-            part.strip!
-            part.gsub!(/ (ASC|DESC)$/i, "").gsub!(/(.*)\./, "")
-            table_name = ($1 ? $1.gsub(/[^a-z0-9_]/i, "") : nil)
-            part.gsub!(/[^a-z0-9_]/i, "")
-            reflection = nil
-            if table_name && table_name != klass.table_name
-              reflection = klass.reflect_on_association(table_name.to_sym) || klass.reflect_on_association(table_name.singularize.to_sym)
-              next unless reflection
-              {reflection.name.to_s => part}
-            else
-              part
-            end
-          end.compact
-          @order_by = order_parts.size <= 1 ? order_parts.first : order_parts
-        else
-          @order_by = klass.primary_key
-        end
+        return if order.blank?
+        @order_by ||= order_to_order_by(order)
       end
       
       # Lets you set how to order the data
@@ -101,23 +93,86 @@ module Searchgasm
       #   order_by = [:id, name] # => users.id ASC, user.name ASC
       #   order_by = [:id, {:user_group => :name}] # => users.id ASC, user_groups.name ASC
       def order_by=(value)  
-        self.order_by_auto_joins.clear
+        @order_by_auto_joins = nil
         @memoized_auto_joins = nil
         @order_by = get_order_by_value(value)
-        @order = order_by_to_order(@order_by, order_as)
+        @order = order_by_to_order(@order_by, @order_as)
         @order_by
       end
       
       # Returns the joins neccessary for the "order" statement so that we don't get an SQL error
       def order_by_auto_joins
-        @order_by_auto_joins ||= []
-        @order_by_auto_joins.compact!
-        @order_by_auto_joins.uniq!
-        @order_by_auto_joins
+        @order_by_auto_joins ||= build_order_by_auto_joins(order_by)
+      end
+      
+      # Let's you set a priority order. Meaning this will get ordered first before anything else, but is unnoticeable and abstracted out from your regular order. For example, lets say you have a model called Product
+      # that had a "featured" boolean column. You want to order the products by the price, quantity, etc., but you want the featured products to always be first.
+      #
+      # Without a priority order your controller would get cluttered and your code would be much more complicated. All of your order_by_link methods would have to be order_by_link [:featured, :price], :text => "Price"
+      # Your order_by_link methods alternate between ASC and DESC, so the featured products would jump from the top the bottom. It presents a lot of "work arounds". So priority_order solves this.
+      def priority_order=(value)
+        @priority_order = value
+      end
+      
+      # Same as order_by but for your priority order. See priority_order= for more informaton on priority_order.
+      def priority_order_by
+        return if priority_order.blank?
+        @priority_order_by ||= order_to_order_by(priority_order)
+      end
+      
+      # Same as order_by= but for your priority order. See priority_order= for more informaton on priority_order.
+      def priority_order_by=(value)
+        @priority_order_by_auto_joins = nil
+        @memoized_auto_joins = nil
+        @priority_order_by = get_order_by_value(value)
+        @priority_order = order_by_to_order(@priority_order_by, @priority_order_as)
+        @priority_order_by
+      end
+      
+      # Same as order_as but for your priority order. See priority_order= for more informaton on priority_order.
+      def priority_order_as
+        return if priority_order.blank?
+        return @priority_order_as if @priority_order_as
+        
+        case priority_order
+        when /ASC$/i
+          @priority_order_as = "ASC"
+        when /DESC$/i 
+          @priority_order_as = "DESC"
+        else
+          nil
+        end
+      end
+      
+      # Same as order_as= but for your priority order. See priority_order= for more informaton on priority_order.
+      def priority_order_as=(value)
+        value = value.blank? ? nil : value.to_s.upcase
+        raise(ArgumentError, "priority_order_as only accepts a blank string / nil or a string as 'ASC' or 'DESC'") if !value.blank? && !["ASC", "DESC"].include?(value)
+        if @priority_order_by
+          @priority_order = order_by_to_order(@priority_order_by, value)
+        elsif priority_order
+          @priority_order.gsub!(/(ASC|DESC)/i, value)
+        end
+        @priority_order_as = value
+      end
+      
+      def priority_order_by_auto_joins
+        @priority_order_by_auto_joins ||= build_order_by_auto_joins(priority_order_by)
+      end
+      
+      def sanitize_with_ordering(searching = true)
+        find_options = sanitize_without_ordering(searching)
+        unless priority_order.blank?
+          order_parts = [priority_order, find_options[:order]].compact
+          find_options[:order] = order_parts.join(", ")
+        end
+        find_options
       end
       
       private
-        def order_by_to_order(order_by, order_as, alt_klass = nil, new_joins = [])
+        def order_by_to_order(order_by, order_as, alt_klass = nil)
+          return if order_by.blank?
+          
           k = alt_klass || klass
           table_name = k.table_name
           sql_parts = []
@@ -130,23 +185,51 @@ module Searchgasm
             key = order_by.keys.first
             reflection = k.reflect_on_association(key.to_sym)
             value = order_by.values.first
-            new_joins << key.to_sym
-            sql_parts << order_by_to_order(value, order_as, reflection.klass, new_joins)
+            sql_parts << order_by_to_order(value, order_as, reflection.klass)
           when Symbol, String
-            new_join = build_order_by_auto_joins(new_joins)
-            self.order_by_auto_joins << new_join if new_join
-            sql_parts << "#{quote_table_name(table_name)}.#{quote_column_name(order_by)} #{order_as}"
+            part = "#{quote_table_name(table_name)}.#{quote_column_name(order_by)}"
+            part += " #{order_as}" unless order_as.blank?
+            sql_parts << part
           end
           
           sql_parts.join(", ")
         end
         
-        def build_order_by_auto_joins(joins)
-          return joins.first if joins.size <= 1
-          joins = joins.dup
-          
-          key = joins.shift
-          {key => build_order_by_auto_joins(joins)}
+        def order_to_order_by(order)
+          # Reversege engineer order, only go 1 level deep with relationships, anything beyond that is probably excessive and not good for performance
+          order_parts = order.split(",").collect do |part|
+            part.strip!
+            part.gsub!(/ (ASC|DESC)$/i, "").gsub!(/(.*)\./, "")
+            table_name = ($1 ? $1.gsub(/[^a-z0-9_]/i, "") : nil)
+            part.gsub!(/[^a-z0-9_]/i, "")
+            reflection = nil
+            if table_name && table_name != klass.table_name
+              reflection = klass.reflect_on_association(table_name.to_sym) || klass.reflect_on_association(table_name.singularize.to_sym)
+              next unless reflection
+              {reflection.name.to_s => part}
+            else
+              part
+            end
+          end.compact
+          order_parts.size <= 1 ? order_parts.first : order_parts
+        end
+        
+        def build_order_by_auto_joins(order_by_value)
+          case order_by_value
+          when Array
+            order_by_value.collect { |value| build_order_by_auto_joins(value) }.uniq.compact
+          when Hash
+            key = order_by_value.keys.first
+            value = order_by_value.values.first
+            case value
+            when Hash
+              {key => build_order_by_auto_joins(value)}
+            else
+              key
+            end
+          else
+            nil
+          end
         end
         
         def get_order_by_value(value)

data/lib/searchgasm/search/protection.rb

@@ -22,11 +22,11 @@ module Searchgasm
     #   User.all(params[:search])
     module Protection
       # Options that are allowed when protecting against SQL injections (still checked though)
-      SAFE_OPTIONS = Base::SPECIAL_FIND_OPTIONS + [:conditions, :limit, :offset]
+      SAFE_OPTIONS = Base::SPECIAL_FIND_OPTIONS + [:conditions, :limit, :offset] - [:priority_order]
       
-      VULNERABLE_FIND_OPTIONS = Base::AR_FIND_OPTIONS - SAFE_OPTIONS
+      VULNERABLE_FIND_OPTIONS = Base::AR_FIND_OPTIONS - SAFE_OPTIONS + [:priority_order]
       
-      VULNERABLE_CALCULATIONS_OPTIONS = Base::AR_CALCULATIONS_OPTIONS - SAFE_OPTIONS
+      VULNERABLE_CALCULATIONS_OPTIONS = Base::AR_CALCULATIONS_OPTIONS - SAFE_OPTIONS + [:priority_order]
       
       # Options that are not allowed, at all, when protecting against SQL injections
       VULNERABLE_OPTIONS = Base::OPTIONS - SAFE_OPTIONS

data/lib/searchgasm/version.rb

@@ -67,7 +67,7 @@ module Searchgasm
 
     MAJOR = 1
     MINOR = 2
-    TINY  = 0
+    TINY  = 1
 
     # The current version as a Version instance
     CURRENT = new(MAJOR, MINOR, TINY)

data/searchgasm.gemspec

@@ -1,18 +1,18 @@
 
-# Gem::Specification for Searchgasm-1.2.0
+# Gem::Specification for Searchgasm-1.2.1
 # Originally generated by Echoe
 
 --- !ruby/object:Gem::Specification 
 name: searchgasm
 version: !ruby/object:Gem::Version 
-  version: 1.2.0
+  version: 1.2.1
 platform: ruby
 authors: 
 - Ben Johnson of Binary Logic
 autorequire: 
 bindir: bin
 
-date: 2008-09-24 00:00:00 -04:00
+date: 2008-09-26 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -34,9 +34,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version 
         version: "0"
-    - - "="
-      - !ruby/object:Gem::Version 
-        version: 2.1.0
     version: 
 - !ruby/object:Gem::Dependency 
   name: echoe

data/test/test_search_ordering.rb

@@ -1,49 +1,22 @@
 require File.dirname(__FILE__) + '/test_helper.rb'
 
 class TestSearchOrdering < Test::Unit::TestCase
-  def test_order_as
-    search = Account.new_search
-    assert_equal nil, search.order
-    assert_equal "ASC", search.order_as
-    assert search.asc?
-    
-    search.order_as = "DESC"
-    assert_equal "DESC", search.order_as
-    assert search.desc?
-    assert_equal "\"accounts\".\"id\" DESC", search.order
-    
-    search.order = "id ASC"
-    assert_equal "ASC", search.order_as
-    assert search.asc?
-    assert_equal "id ASC", search.order
-    
-    search.order = "id DESC"
-    assert_equal "DESC", search.order_as
-    assert search.desc?
-    assert_equal "id DESC", search.order
-    
-    search.order_by = "name"
-    assert_equal "DESC", search.order_as
-    assert search.desc?
-    assert_equal "\"accounts\".\"name\" DESC", search.order
-  end
-  
   def test_order_by
     search = Account.new_search
     assert_equal nil, search.order
-    assert_equal "id", search.order_by
+    assert_equal nil, search.order_by
     
     search.order_by = "first_name"
     assert_equal "first_name", search.order_by
-    assert_equal "\"accounts\".\"first_name\" ASC", search.order
+    assert_equal "\"accounts\".\"first_name\"", search.order
     
     search.order_by = "last_name"
     assert_equal "last_name", search.order_by
-    assert_equal "\"accounts\".\"last_name\" ASC", search.order
+    assert_equal "\"accounts\".\"last_name\"", search.order
     
     search.order_by = ["first_name", "last_name"]
     assert_equal ["first_name", "last_name"], search.order_by
-    assert_equal "\"accounts\".\"first_name\" ASC, \"accounts\".\"last_name\" ASC", search.order
+    assert_equal "\"accounts\".\"first_name\", \"accounts\".\"last_name\"", search.order
     
     search.order = "created_at DESC"
     assert_equal "created_at", search.order_by
@@ -77,4 +50,98 @@ class TestSearchOrdering < Test::Unit::TestCase
     assert_equal nil, search.order_by
     assert_equal "`line_items`.id DESC", search.order
   end
+  
+  def test_order_as
+    search = Account.new_search
+    assert_equal nil, search.order
+    assert_equal nil, search.order_as
+    assert !search.asc?
+    
+    search.order_as = "DESC"
+    assert_equal nil, search.order_as
+    assert !search.desc?
+    assert_equal nil, search.order
+    
+    search.order_by = "name"
+    assert_equal "\"accounts\".\"name\" DESC", search.order
+    
+    search.order_as = "ASC"
+    assert_equal "\"accounts\".\"name\" ASC", search.order
+    assert search.asc?
+    
+    search.order = "id ASC"
+    assert_equal "ASC", search.order_as
+    assert search.asc?
+    assert_equal "id ASC", search.order
+    
+    search.order = "id DESC"
+    assert_equal "DESC", search.order_as
+    assert search.desc?
+    assert_equal "id DESC", search.order
+    
+    search.order_by = "name"
+    assert_equal "DESC", search.order_as
+    assert search.desc?
+    assert_equal "\"accounts\".\"name\" DESC", search.order
+    
+    assert_raise(ArgumentError) { search.order_as = "awesome" }
+  end
+  
+  def test_order_by_auto_joins
+    search = Account.new_search
+    assert_equal nil, search.order_by_auto_joins
+    search.order_by = :name
+    assert_equal nil, search.order_by_auto_joins
+    search.order_by = {:users => :first_name}
+    assert_equal :users, search.order_by_auto_joins
+    search.order_by = [{:users => :first_name}, {:orders => :total}, {:users => {:user_groups => :name}}]
+    assert_equal [:users, :orders, {:users => :user_groups}], search.order_by_auto_joins
+    search.priority_order_by = {:users => :first_name}
+    assert_equal [:users, :orders, {:users => :user_groups}], search.order_by_auto_joins
+    search.priority_order_by = {:users => {:orders => :total}}
+    assert_equal({:users => :orders}, search.priority_order_by_auto_joins)
+    assert_equal [:users, :orders, {:users => :user_groups}, {:users => :orders}], search.auto_joins
+  end
+  
+  def test_priority_order_by
+    search = Account.new_search
+    assert_equal nil, search.priority_order
+    assert_equal nil, search.priority_order_by
+    assert_equal nil, search.priority_order_as
+    
+    search.priority_order_by = :name
+    assert_equal "\"accounts\".\"name\"", search.priority_order
+    assert_equal "\"accounts\".\"name\"", search.sanitize[:order]
+    assert_equal nil, search.order
+    assert_equal :name, search.priority_order_by
+    assert_equal nil, search.priority_order_as
+    
+    search.order_by = :id
+    assert_equal "\"accounts\".\"name\", \"accounts\".\"id\"", search.sanitize[:order]
+    search.order_as = "DESC"
+    assert_equal "\"accounts\".\"name\", \"accounts\".\"id\" DESC", search.sanitize[:order]
+  end
+  
+  def test_priority_order_as
+    search = Account.new_search
+    assert_equal nil, search.priority_order_as
+    assert_equal nil, search.order_as
+    search.priority_order_as = "ASC"
+    assert_equal nil, search.priority_order_as
+    assert_equal nil, search.order_as
+    search.priority_order_by = :name
+    assert_equal "ASC", search.priority_order_as
+    assert_equal nil, search.order_as
+    search.priority_order_as = "DESC"
+    assert_equal "DESC", search.priority_order_as
+    assert_equal nil, search.order_as
+    assert_raise(ArgumentError) { search.priority_order_as = "awesome" }
+    search.priority_order = nil
+    assert_equal nil, search.priority_order_as
+    assert_equal nil, search.order_as
+  end
+  
+  def test_sanitize
+    # tested in test_priority_order_by
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: searchgasm
 version: !ruby/object:Gem::Version 
-  version: 1.2.0
+  version: 1.2.1
 platform: ruby
 authors: 
 - Ben Johnson of Binary Logic
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-09-24 00:00:00 -04:00
+date: 2008-09-26 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -31,9 +31,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version 
         version: "0"
-    - - "="
-      - !ruby/object:Gem::Version 
-        version: 2.1.0
     version: 
 - !ruby/object:Gem::Dependency 
   name: echoe