sort_helper.rb 4.51 KB
Newer Older
1 2
# encoding: utf-8
#
jplang's avatar
jplang committed
3 4 5
# Helpers to sort tables using clickable column headers.
#
# Author:  Stuart Rackham <srackham@methods.co.nz>, March 2005.
jplang's avatar
jplang committed
6
#          Jean-Philippe Lang, 2009
jplang's avatar
jplang committed
7 8 9 10
# License: This source code is released under the MIT license.
#
# - Consecutive clicks toggle the column's sort order.
# - Sort state is maintained by a session hash entry.
jplang's avatar
jplang committed
11
# - CSS classes identify sort column and state.
jplang's avatar
jplang committed
12 13 14 15 16 17 18 19
# - Typically used in conjunction with the Pagination module.
#
# Example code snippets:
#
# Controller:
#
#   helper :sort
#   include SortHelper
20
#
jplang's avatar
jplang committed
21 22
#   def list
#     sort_init 'last_name'
jplang's avatar
jplang committed
23
#     sort_update %w(first_name last_name)
jplang's avatar
jplang committed
24 25
#     @items = Contact.find_all nil, sort_clause
#   end
26
#
jplang's avatar
jplang committed
27 28 29 30
# Controller (using Pagination module):
#
#   helper :sort
#   include SortHelper
31
#
jplang's avatar
jplang committed
32 33
#   def list
#     sort_init 'last_name'
jplang's avatar
jplang committed
34
#     sort_update %w(first_name last_name)
jplang's avatar
jplang committed
35 36 37 38
#     @contact_pages, @items = paginate :contacts,
#       :order_by => sort_clause,
#       :per_page => 10
#   end
39
#
jplang's avatar
jplang committed
40
# View (table header in list.rhtml):
41
#
jplang's avatar
jplang committed
42 43 44 45 46 47 48 49 50
#   <thead>
#     <tr>
#       <%= sort_header_tag('id', :title => 'Sort by contact ID') %>
#       <%= sort_header_tag('last_name', :caption => 'Name') %>
#       <%= sort_header_tag('phone') %>
#       <%= sort_header_tag('address', :width => 200) %>
#     </tr>
#   </thead>
#
jplang's avatar
jplang committed
51 52
# - Introduces instance variables: @sort_default, @sort_criteria
# - Introduces param :sort
jplang's avatar
jplang committed
53
#
jplang's avatar
jplang committed
54

jplang's avatar
jplang committed
55
module SortHelper
56 57 58
  def sort_name
    controller_name + '_' + action_name + '_sort'
  end
jplang's avatar
jplang committed
59

60 61
  # Initializes the default sort.
  # Examples:
62
  #
63 64 65 66
  #   sort_init 'name'
  #   sort_init 'id', 'desc'
  #   sort_init ['name', ['id', 'desc']]
  #   sort_init [['name', 'desc'], ['id', 'desc']]
jplang's avatar
jplang committed
67
  #
68 69 70 71 72 73 74 75 76
  def sort_init(*args)
    case args.size
    when 1
      @sort_default = args.first.is_a?(Array) ? args.first : [[args.first]]
    when 2
      @sort_default = [[args.first, args.last]]
    else
      raise ArgumentError
    end
jplang's avatar
jplang committed
77 78 79 80
  end

  # Updates the sort state. Call this in the controller prior to calling
  # sort_clause.
jplang's avatar
jplang committed
81 82
  # - criteria can be either an array or a hash of allowed keys
  #
83 84
  def sort_update(criteria, sort_name=nil)
    sort_name ||= self.sort_name
85 86
    @sort_criteria = Redmine::SortCriteria.new(params[:sort] || session[sort_name] || @sort_default)
    @sortable_columns = criteria
jplang's avatar
jplang committed
87
    session[sort_name] = @sort_criteria.to_param
jplang's avatar
jplang committed
88
  end
89

90 91 92 93 94
  # Clears the sort criteria session data
  #
  def sort_clear
    session[sort_name] = nil
  end
jplang's avatar
jplang committed
95 96 97 98 99

  # Returns an SQL sort clause corresponding to the current sort state.
  # Use this to sort the controller's table items collection.
  #
  def sort_clause()
100
    @sort_criteria.sort_clause(@sortable_columns)
jplang's avatar
jplang committed
101 102
  end

103 104 105 106
  def sort_criteria
    @sort_criteria
  end

jplang's avatar
jplang committed
107 108 109
  # Returns a link which sorts by the named column.
  #
  # - column is the name of an attribute in the sorted record collection.
jplang's avatar
jplang committed
110 111
  # - the optional caption explicitly specifies the displayed link text.
  # - 2 CSS classes reflect the state of the link: sort and asc or desc
jplang's avatar
jplang committed
112
  #
113
  def sort_link(column, caption, default_order)
jplang's avatar
jplang committed
114
    css, order = nil, default_order
115

jplang's avatar
jplang committed
116 117 118
    if column.to_s == @sort_criteria.first_key
      if @sort_criteria.first_asc?
        css = 'sort asc'
jplang's avatar
jplang committed
119 120
        order = 'desc'
      else
jplang's avatar
jplang committed
121
        css = 'sort desc'
jplang's avatar
jplang committed
122 123 124
        order = 'asc'
      end
    end
jplang's avatar
jplang committed
125
    caption = column.to_s.humanize unless caption
126

jplang's avatar
jplang committed
127
    sort_options = { :sort => @sort_criteria.add(column.to_s, order).to_param }
128
    link_to(caption, {:params => request.query_parameters.merge(sort_options)}, :class => css)
jplang's avatar
jplang committed
129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144
  end

  # Returns a table header <th> tag with a sort link for the named column
  # attribute.
  #
  # Options:
  #   :caption     The displayed link name (defaults to titleized column name).
  #   :title       The tag's 'title' attribute (defaults to 'Sort by :caption').
  #
  # Other options hash entries generate additional table header tag attributes.
  #
  # Example:
  #
  #   <%= sort_header_tag('id', :title => 'Sort by contact ID', :width => 40) %>
  #
  def sort_header_tag(column, options = {})
jplang's avatar
jplang committed
145
    caption = options.delete(:caption) || column.to_s.humanize
146
    default_order = options.delete(:default_order) || 'asc'
jplang's avatar
jplang committed
147
    options[:title] = l(:label_sort_by, "\"#{caption}\"") unless options[:title]
148
    content_tag('th', sort_link(column, caption, default_order), options)
jplang's avatar
jplang committed
149
  end
150 151 152 153 154 155 156 157 158 159 160 161

  # Returns the css classes for the current sort order
  #
  # Example:
  #
  #   sort_css_classes
  #   # => "sort-by-created-on sort-desc"
  def sort_css_classes
    if @sort_criteria.first_key
      "sort-by-#{@sort_criteria.first_key.to_s.dasherize} sort-#{@sort_criteria.first_asc? ? 'asc' : 'desc'}"
    end
  end
jplang's avatar
jplang committed
162
end
jplang's avatar
jplang committed
163