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