Chris@909: # encoding: utf-8
Chris@909: #
Chris@0: # Helpers to sort tables using clickable column headers.
Chris@0: #
Chris@0: # Author:  Stuart Rackham <srackham@methods.co.nz>, March 2005.
Chris@0: #          Jean-Philippe Lang, 2009
Chris@0: # License: This source code is released under the MIT license.
Chris@0: #
Chris@0: # - Consecutive clicks toggle the column's sort order.
Chris@0: # - Sort state is maintained by a session hash entry.
Chris@0: # - CSS classes identify sort column and state.
Chris@0: # - Typically used in conjunction with the Pagination module.
Chris@0: #
Chris@0: # Example code snippets:
Chris@0: #
Chris@0: # Controller:
Chris@0: #
Chris@0: #   helper :sort
Chris@0: #   include SortHelper
Chris@909: #
Chris@0: #   def list
Chris@0: #     sort_init 'last_name'
Chris@0: #     sort_update %w(first_name last_name)
Chris@0: #     @items = Contact.find_all nil, sort_clause
Chris@0: #   end
Chris@909: #
Chris@0: # Controller (using Pagination module):
Chris@0: #
Chris@0: #   helper :sort
Chris@0: #   include SortHelper
Chris@909: #
Chris@0: #   def list
Chris@0: #     sort_init 'last_name'
Chris@0: #     sort_update %w(first_name last_name)
Chris@0: #     @contact_pages, @items = paginate :contacts,
Chris@0: #       :order_by => sort_clause,
Chris@0: #       :per_page => 10
Chris@0: #   end
Chris@909: #
Chris@0: # View (table header in list.rhtml):
Chris@909: #
Chris@0: #   <thead>
Chris@0: #     <tr>
Chris@0: #       <%= sort_header_tag('id', :title => 'Sort by contact ID') %>
Chris@0: #       <%= sort_header_tag('last_name', :caption => 'Name') %>
Chris@0: #       <%= sort_header_tag('phone') %>
Chris@0: #       <%= sort_header_tag('address', :width => 200) %>
Chris@0: #     </tr>
Chris@0: #   </thead>
Chris@0: #
Chris@0: # - Introduces instance variables: @sort_default, @sort_criteria
Chris@0: # - Introduces param :sort
Chris@0: #
Chris@0: 
Chris@0: module SortHelper
Chris@0:   class SortCriteria
Chris@909: 
Chris@0:     def initialize
Chris@0:       @criteria = []
Chris@0:     end
Chris@909: 
Chris@0:     def available_criteria=(criteria)
Chris@0:       unless criteria.is_a?(Hash)
Chris@0:         criteria = criteria.inject({}) {|h,k| h[k] = k; h}
Chris@0:       end
Chris@0:       @available_criteria = criteria
Chris@0:     end
Chris@909: 
Chris@0:     def from_param(param)
Chris@0:       @criteria = param.to_s.split(',').collect {|s| s.split(':')[0..1]}
Chris@0:       normalize!
Chris@0:     end
Chris@909: 
Chris@0:     def criteria=(arg)
Chris@0:       @criteria = arg
Chris@0:       normalize!
Chris@0:     end
Chris@909: 
Chris@0:     def to_param
Chris@0:       @criteria.collect {|k,o| k + (o ? '' : ':desc')}.join(',')
Chris@0:     end
Chris@909: 
Chris@1464:     # Returns an array of SQL fragments used to sort the list
Chris@0:     def to_sql
Chris@0:       sql = @criteria.collect do |k,o|
Chris@0:         if s = @available_criteria[k]
Chris@1464:           (o ? s.to_a : s.to_a.collect {|c| append_desc(c)})
Chris@0:         end
Chris@1464:       end.flatten.compact
Chris@0:       sql.blank? ? nil : sql
Chris@0:     end
Chris@909: 
Chris@1115:     def to_a
Chris@1115:       @criteria.dup
Chris@1115:     end
Chris@1115: 
Chris@0:     def add!(key, asc)
Chris@0:       @criteria.delete_if {|k,o| k == key}
Chris@0:       @criteria = [[key, asc]] + @criteria
Chris@0:       normalize!
Chris@0:     end
Chris@909: 
Chris@0:     def add(*args)
Chris@0:       r = self.class.new.from_param(to_param)
Chris@0:       r.add!(*args)
Chris@0:       r
Chris@0:     end
Chris@909: 
Chris@0:     def first_key
Chris@0:       @criteria.first && @criteria.first.first
Chris@0:     end
Chris@909: 
Chris@0:     def first_asc?
Chris@0:       @criteria.first && @criteria.first.last
Chris@0:     end
Chris@909: 
Chris@0:     def empty?
Chris@0:       @criteria.empty?
Chris@0:     end
Chris@909: 
Chris@0:     private
Chris@909: 
Chris@0:     def normalize!
Chris@0:       @criteria ||= []
Chris@0:       @criteria = @criteria.collect {|s| s = s.to_a; [s.first, (s.last == false || s.last == 'desc') ? false : true]}
Chris@0:       @criteria = @criteria.select {|k,o| @available_criteria.has_key?(k)} if @available_criteria
Chris@0:       @criteria.slice!(3)
Chris@0:       self
Chris@0:     end
Chris@909: 
Chris@0:     # Appends DESC to the sort criterion unless it has a fixed order
Chris@0:     def append_desc(criterion)
Chris@0:       if criterion =~ / (asc|desc)$/i
Chris@0:         criterion
Chris@0:       else
Chris@0:         "#{criterion} DESC"
Chris@0:       end
Chris@0:     end
Chris@0:   end
Chris@909: 
Chris@0:   def sort_name
Chris@0:     controller_name + '_' + action_name + '_sort'
Chris@0:   end
Chris@0: 
Chris@0:   # Initializes the default sort.
Chris@0:   # Examples:
Chris@909:   #
Chris@0:   #   sort_init 'name'
Chris@0:   #   sort_init 'id', 'desc'
Chris@0:   #   sort_init ['name', ['id', 'desc']]
Chris@0:   #   sort_init [['name', 'desc'], ['id', 'desc']]
Chris@0:   #
Chris@0:   def sort_init(*args)
Chris@0:     case args.size
Chris@0:     when 1
Chris@0:       @sort_default = args.first.is_a?(Array) ? args.first : [[args.first]]
Chris@0:     when 2
Chris@0:       @sort_default = [[args.first, args.last]]
Chris@0:     else
Chris@0:       raise ArgumentError
Chris@0:     end
Chris@0:   end
Chris@0: 
Chris@0:   # Updates the sort state. Call this in the controller prior to calling
Chris@0:   # sort_clause.
Chris@0:   # - criteria can be either an array or a hash of allowed keys
Chris@0:   #
Chris@1115:   def sort_update(criteria, sort_name=nil)
Chris@1115:     sort_name ||= self.sort_name
Chris@0:     @sort_criteria = SortCriteria.new
Chris@0:     @sort_criteria.available_criteria = criteria
Chris@0:     @sort_criteria.from_param(params[:sort] || session[sort_name])
Chris@0:     @sort_criteria.criteria = @sort_default if @sort_criteria.empty?
Chris@0:     session[sort_name] = @sort_criteria.to_param
Chris@0:   end
Chris@909: 
Chris@0:   # Clears the sort criteria session data
Chris@0:   #
Chris@0:   def sort_clear
Chris@0:     session[sort_name] = nil
Chris@0:   end
Chris@0: 
Chris@0:   # Returns an SQL sort clause corresponding to the current sort state.
Chris@0:   # Use this to sort the controller's table items collection.
Chris@0:   #
Chris@0:   def sort_clause()
Chris@0:     @sort_criteria.to_sql
Chris@0:   end
Chris@0: 
Chris@1115:   def sort_criteria
Chris@1115:     @sort_criteria
Chris@1115:   end
Chris@1115: 
Chris@0:   # Returns a link which sorts by the named column.
Chris@0:   #
Chris@0:   # - column is the name of an attribute in the sorted record collection.
Chris@0:   # - the optional caption explicitly specifies the displayed link text.
Chris@0:   # - 2 CSS classes reflect the state of the link: sort and asc or desc
Chris@0:   #
Chris@0:   def sort_link(column, caption, default_order)
Chris@0:     css, order = nil, default_order
Chris@909: 
Chris@0:     if column.to_s == @sort_criteria.first_key
Chris@0:       if @sort_criteria.first_asc?
Chris@0:         css = 'sort asc'
Chris@0:         order = 'desc'
Chris@0:       else
Chris@0:         css = 'sort desc'
Chris@0:         order = 'asc'
Chris@0:       end
Chris@0:     end
Chris@0:     caption = column.to_s.humanize unless caption
Chris@909: 
Chris@0:     sort_options = { :sort => @sort_criteria.add(column.to_s, order).to_param }
Chris@441:     url_options = params.merge(sort_options)
Chris@909: 
Chris@0:      # Add project_id to url_options
Chris@0:     url_options = url_options.merge(:project_id => params[:project_id]) if params.has_key?(:project_id)
Chris@0: 
Chris@909:     link_to_content_update(h(caption), url_options, :class => css)
Chris@0:   end
Chris@0: 
Chris@0:   # Returns a table header <th> tag with a sort link for the named column
Chris@0:   # attribute.
Chris@0:   #
Chris@0:   # Options:
Chris@0:   #   :caption     The displayed link name (defaults to titleized column name).
Chris@0:   #   :title       The tag's 'title' attribute (defaults to 'Sort by :caption').
Chris@0:   #
Chris@0:   # Other options hash entries generate additional table header tag attributes.
Chris@0:   #
Chris@0:   # Example:
Chris@0:   #
Chris@0:   #   <%= sort_header_tag('id', :title => 'Sort by contact ID', :width => 40) %>
Chris@0:   #
Chris@0:   def sort_header_tag(column, options = {})
Chris@0:     caption = options.delete(:caption) || column.to_s.humanize
Chris@0:     default_order = options.delete(:default_order) || 'asc'
Chris@0:     options[:title] = l(:label_sort_by, "\"#{caption}\"") unless options[:title]
Chris@0:     content_tag('th', sort_link(column, caption, default_order), options)
Chris@0:   end
Chris@0: end
Chris@0: