JasonKing-good_sort 0.1.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Jason King
+
+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/README.markdown

@@ -0,0 +1,144 @@
+Good Sort
+=========
+
+Hate not having _the right way_™ to do column sorting in list (collection)
+views?  Well, fear not my dear friend, for good_sort has arrived.  Does Ajax for
+those with JS and regular links for those without.  Also, as long as you load it
+after will_paginate, it will sniff it out and make the will_paginate view helper
+do the right thing with your sorted collection.
+
+Installation
+------------
+
+### gem
+
+To perform a system wide installation:
+
+    gem source -a http://gems.github.com
+    gem install JasonKing-good_sort
+
+Then add it to your `config/environment.rb`:
+
+    config.gem 'JasonKing-good_sort', :lib => 'good_sort'
+
+### plugin
+
+    script/plugin install git://github.com/JasonKing/good_sort.git
+
+### git submodule
+
+    $ git submodule add git://github.com/JasonKing/good_sort.git vendor/plugins/good_sort
+
+Usage
+-----
+
+### app/models/author.rb
+    sort_on :name, :updated_at
+
+### app/controllers/site_controller.rb
+    def index
+      @authors = Author.all( Author.sort_by(params[:sort]) )
+
+      if request.xhr?
+        return render :partial => 'authors'
+      end
+    end
+
+### app/views/site/index.html.erb
+    <div id="authors">
+      <%= render :partial => 'authors' %>
+    </div>
+
+### app/views/site/_authors.html.erb
+    <table>
+      <thead>
+        <tr>
+          <%
+            sort_headers_for :author, %w{name ranking phone updated_at} do |header|
+              "Last Changed" if header == 'updated_at'
+            end
+          %>
+        </tr>
+      </thead>
+      <tbody>
+        <% @authors.each do |author| -%>
+        <tr>
+          <td><%=h author.name %></td>
+          <td><%=h author.ranking %></td>
+          <td><%=h author.phone %></td>
+          <td><%=h author.updated_at %></td>
+        </tr>
+        <% end -%>
+      </tbody>
+    </table>
+
+That's simple enough isn't it?
+
+The `sort_headers_for` helper will make a heading for each one of the elements
+in the array you pass in - if it's one of the fields that you've set sorting on
+in your model (using the `sort_on` class method).
+
+Methods
+-------
+
+### ActiveRecord::Base.sort\_on( *args )
+
+This is the class method that you use in your model in order to let `good_sort`
+know which attributes of your model can be used to sort the collection.
+Obviously these can't be virtual attributes because we're generating SQL here
+(if you don't know what virtual attributes are then google is your friend).
+
+As well as attributes in your model, you can also supply `belongs_to`
+association names which will make `good_sort` sort your collection based on the
+fields in a JOINed table.
+
+    class Author < ActiveRecord::Base
+      belongs_to :state
+      sort_on :name, :updated_at, :state
+    end
+
+The convention is that this will use the `name` attribute of the associated
+model, but if you want the sorting done using a different field then you can
+just specify it using key => value style params, like so:
+
+    class Author < ActiveRecord::Base
+      belongs_to :state
+      sort_on :name, :updated_at, :state => :long_name
+    end
+
+There's also no requirement to cram it all in on one line, you can have multiple
+`sort_on` declarations, and they will just be accumulated.
+
+### ActiveRecord::Base.sort\_by( params[:sort] )
+
+This produces a `:order` hash suitable to be merged into your `Model.find` (or
+`Model.paginate`) parameters based on the `:field` and `:down` input parameters.
+
+### ActionView::Base#sort\_headers\_for( model\_name, header\_array, options = {} )
+
+With no options, this will create `<th>` elements for each element of the
+header_array, they will be given an id which, for the `name` field of our
+`author` example would be `author_header_name`.  If it has sorting set for it
+with `sort_on` in your model, then it will also be wrapped in a gracefully
+degrading re-sorting ajaxified link which will replace the element with id of
+pluralized model name, so for our author example it will replace the element
+with the id of `"authors"` (it will also show/hide an element with id of
+`"spinner"` during the request).  If the list is already sorted by that field,
+then a class of either `"up"` or `"down"` will be added to the `<th>` element.
+
+So, all of those things can be overridden.  The options you can pass in are as
+follows:
+
+ * **:spinner** - The id of the element to show/hide during the AJAX request, defaults to `:spinner`
+ * **:tag** - The type of element to wrap your header links in, defaults to `:th`
+ * **:header** - Options passed to the content_tag for the :tag wrapper.
+  * No defaults, but :id is set to `<model>\_header\_<field>` and :class will have `"up"` or `"down"` added to it appropriately.
+ * **:remote** - Options passed to `link\_to\_remote` as second arg, see the docs for `link\_to\_remote` for these options, defaults below:
+  * **:update** - Defaults to the lower-case pluralized and underscored version of your model name - ie. model\_name.tablelize
+  * **:before** - Defaults to showing the `:spinner` element (whatever you set that to, or `"spinner"` if you don't set it).
+  * **:complete** - Defaults to hiding the `:spinner` element
+  * **:method** - :get - you probably shouldn't change this
+  * **:url** - No point in setting this, it is overridden with the link URL.
+ * **:html** - Options pass to the `link\_to\_remote` as the third argument, see the docs for `link\_to\_remote` for these, defaults below:
+  * **:title** - Defaults to "Sort by #{sort\_field\_tag}".  If you embed the sort\_field\_tag attribute in your string then that will be replaced with the field\_name.titlize for you, eg: :title => "Order by #{sort\_field\_tag}"  If you want anything fancier then you can override `sort\_header\_title` and do whatever you want.
+  * **:html** - No point in setting this, it is overridden with the link URL.

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:patch: 1
+:major: 0
+:minor: 1

data/lib/good_sort/sorter.rb

@@ -0,0 +1,53 @@
+module GoodSort
+  module Sorter
+    def sort_fields; @@sort_fields ||= {}; end
+    def sort_by(p)
+      return unless p && p[:field] && p[:down]
+      f = p[:field]
+      unless options = sort_fields[f.to_sym]
+        raise ArgumentError, "Requested field #{f} was not defined in #{class_name} for sorting"
+      end
+      options = options.dup
+      options[:order] += ' DESC' unless p[:down].blank?
+      options
+    end
+    protected
+    def sort_on(*fields)
+      fields.each do |f|
+
+        if f.is_a? String or f.is_a? Symbol
+          if self.columns_hash[f.to_s]
+            sort_fields[f.to_sym] = { :order => f.to_s }
+            next
+          else
+            # if it's not one of ours, we'll see if it's an association
+            f = { f => :name }
+          end
+        end
+
+        if f.is_a? Hash
+          f.each do |k,v|
+            ass = association_for( k )
+            unless ass_has_attr( ass, v )
+              raise ArgumentError, "belongs_to association #{k} does not have specified column #{v}"
+            end
+            sort_fields[k.to_sym] = { :order => ass_to_table(ass) + '.' + v.to_s, :joins => k.to_sym }
+          end
+          next
+        end
+        raise ArgumentError, "Unrecognized option to sort_by"
+      end
+    end
+    private
+    def association_for(k)
+      ass = self.reflect_on_association(k.to_sym) and ass.belongs_to? or raise ArgumentError, "belongs_to association not found for #{k}"
+      ass
+    end
+    def ass_has_attr(ass,v)
+      ass.klass.column_names.find{|e|e==v.to_s}
+    end
+    def ass_to_table(ass)
+      ass.class_name.tableize
+    end
+  end
+end

data/lib/good_sort/view_helpers.rb

@@ -0,0 +1,74 @@
+module GoodSort
+  module ViewHelpers
+    @@field_tag = '__FIELD__'
+    def sort_field_tag; @@field_tag; end
+    def sort_headers_for( m, h, options = {} )
+
+      id = m.to_s.singularize
+      m = m.to_s.classify
+      c = m.constantize
+
+      options.symbolize_keys!
+      options[:spinner] ||= :spinner
+      options[:tag] ||= :th
+
+      options[:header] ||= {}
+      options[:header].symbolize_keys!
+
+      options[:remote] ||= {}
+      options[:remote].symbolize_keys!
+      options[:remote][:update] ||= m.tableize
+      options[:remote][:before] = "$('#{options[:spinner]}').show()" unless options[:remote].has_key? :before
+      options[:remote][:complete]  = "$('#{options[:spinner]}').hide()" unless options[:remote].has_key? :complete
+      options[:remote][:method] ||= :get
+
+      # save these for pagination calls later in the request
+      @remote_options = options[:remote].dup
+
+      options[:html] ||= {}
+      options[:html].symbolize_keys!
+      options[:html][:title] ||= "Sort by #{sort_field_tag}"
+
+      sf = c.sort_fields
+      logger.warn "GoodSort: #{m} has not had any sort_on fields set" if sf.nil?
+
+      h.each do |f|
+        options[:header][:id] = "#{id}_header_#{f}"
+
+        text = yield(f) if block_given?
+        text ||= f.to_s.titleize
+
+        unless sf[f.to_sym]
+          concat content_tag(options[:tag], text, options[:header])
+          next
+        end
+
+        concat sort_header( f, text, options )
+      end
+    end
+
+    def sort_header(f, text, options )
+      params[:sort] ||= {}
+
+      tag_options = options[:header].dup
+      if params[:sort][:field] == f.to_s
+        tag_options[:class] ||= ''
+        (tag_options[:class] += params[:sort][:down].blank? ? ' up' : ' down' ).strip!
+      end
+      content_tag( options[:tag], sort_link(f, text, options), tag_options )
+    end
+
+    def sort_link(f, text, options)
+      s = { :field => f, :down => params[:sort][:field] == f.to_s && params[:sort][:down].blank? ? true : nil }
+      ps = params.merge( :sort => s, :page => nil )
+
+      options[:remote][:url] = options[:html][:href] = url_for( :params => ps )
+      title = sort_header_title( text, options)
+      link_to_remote(text, options[:remote], options[:html].merge( :title => title))
+    end
+
+    def sort_header_title( field, options )
+      options[:html][:title].gsub(sort_field_tag, field)
+    end
+  end
+end

data/lib/good_sort/will_paginate.rb

@@ -0,0 +1,14 @@
+module GoodSort
+  module WillPaginate
+    def self.included(base)
+      base.send :include, InstanceMethods
+      base.alias_method_chain :will_paginate, :good_sort
+    end
+
+    module InstanceMethods
+      def will_paginate_with_good_sort( collection = nil, options = {} )
+        will_paginate_without_good_sort( collection, options.merge( :remote => @remote_options, :params => params ) )
+      end
+    end
+  end
+end

data/lib/good_sort.rb

@@ -0,0 +1,18 @@
+module GoodSort
+  class << self
+    def shwing
+      require 'good_sort/view_helpers'
+      ActionView::Base.send :include, ViewHelpers
+
+      require 'good_sort/sorter'
+      ActiveRecord::Base.send :extend, Sorter
+
+      if ActionView::Base.instance_methods.include? 'will_paginate'
+        require 'good_sort/will_paginate'
+        ActionView::Base.send :include, WillPaginate
+      end
+    end
+  end
+end
+
+GoodSort.shwing

data/test/good_sort_test.rb

@@ -0,0 +1,83 @@
+require 'test_helper'
+require 'good_sort/sorter'
+require 'active_support'
+
+class GoodSortSorterTest < Test::Unit::TestCase
+  include GoodSort::Sorter
+  def columns_hash; { 'foo' => true, 'bar' => true }; end
+  def class_name; "foobar"; end
+
+  def reflect_on_association(a)
+    ass = mock()
+    ass.stubs(:belongs_to?).returns(a.to_sym == :ass_exist)
+
+    ass.stubs(:class_name).returns('ass_exists')
+
+    ass_klass = mock()
+    ass_klass.stubs(:column_names).returns( %w{name last_name} )
+
+    ass.stubs(:klass).returns(ass_klass)
+
+    ass
+  end
+
+  def test_sort_on_our_attributes
+    sort_on :foo, :bar
+    assert_equal 2, sort_fields.length
+    assert_equal( { :order => 'foo' }, sort_fields[:foo])
+    assert_equal( { :order => 'bar' }, sort_fields[:bar])
+  end
+
+  def test_association_sort_fields
+    sort_on :ass_exist => :last_name
+    assert_equal 'ass_exists.last_name', sort_fields[:ass_exist][:order]
+  end
+
+  def test_default_association_sort_field
+    sort_on :ass_exist
+    assert_equal 'ass_exists.name', sort_fields[:ass_exist][:order]
+  end
+
+  def test_argument_errors
+    assert_raise ArgumentError do
+      sort_on :ass_imaginary
+    end
+
+    assert_raise ArgumentError do
+      sort_on false
+    end
+
+    assert_raise ArgumentError do
+      sort_on :ass_exist => :nonexistent
+    end
+  end
+
+  def test_multiple_declarations
+    sort_on :foo
+    sort_on :bar
+    assert_equal 2, sort_fields.length
+    assert_equal( { :order => 'foo' }, sort_fields[:foo])
+    assert_equal( { :order => 'bar' }, sort_fields[:bar])
+  end
+
+  def test_sort_by
+    sort_on :foo
+    assert_equal( { :order => 'foo' }, sort_by( :field => 'foo', :down => '' ))
+    assert_equal( { :order => 'foo DESC'}, sort_by( :field => 'foo', :down => 'true' ))
+    assert_raise ArgumentError do
+      sort_by( :field => 'bar', :down => '' )
+    end
+    assert_nil sort_by nil
+    assert_nil sort_by( :field => 'foo' )
+    assert_nil sort_by( :down => '' )
+    assert_nil sort_by( :down => 'true' )
+
+    sort_on :ass_exist
+    assert_equal( { :joins => :ass_exist, :order => 'ass_exists.name' }, sort_by( :field => 'ass_exist', :down => '' ))
+    assert_equal( { :joins => :ass_exist, :order => 'ass_exists.name DESC' }, sort_by( :field => 'ass_exist', :down => 'true' ))
+  end
+
+  def teardown
+    GoodSort::Sorter.send :class_variable_set, :@@sort_fields, {}
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,7 @@
+require 'rubygems'
+require 'test/unit'
+require 'redgreen'
+require 'mocha'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification 
+name: JasonKing-good_sort
+version: !ruby/object:Gem::Version 
+  version: 0.1.1
+platform: ruby
+authors: 
+- Jason King
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-04-01 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: 
+email: jk@silentcow.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.markdown
+- LICENSE
+files: 
+- README.markdown
+- VERSION.yml
+- lib/good_sort
+- lib/good_sort/sorter.rb
+- lib/good_sort/view_helpers.rb
+- lib/good_sort/will_paginate.rb
+- lib/good_sort.rb
+- test/good_sort_test.rb
+- test/test_helper.rb
+- LICENSE
+has_rdoc: true
+homepage: http://github.com/JasonKing/good_sort
+post_install_message: 
+rdoc_options: 
+- --inline-source
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: TODO
+test_files: []
+