Module: SortHelper

Included in:
BoardsController, FilesController, UsersController
Defined in:
app/helpers/sort_helper.rb

Overview

Helpers to sort tables using clickable column headers.

Author: Stuart Rackham <srackham@methods.co.nz>, March 2005.

Jean-Philippe Lang, 2009

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.

  • CSS classes identify sort column and state.

  • Typically used in conjunction with the Pagination module.

Example code snippets:

Controller:

helper :sort
include SortHelper

def list
  sort_init 'last_name'
  sort_update %w(first_name last_name)
  @items = Contact.find_all nil, sort_clause
end

Controller (using Pagination module):

helper :sort
include SortHelper

def list
  sort_init 'last_name'
  sort_update %w(first_name last_name)
  @contact_pages, @items = paginate :contacts,
    :order_by => sort_clause,
    :per_page => 10
end

View (table header in list.rhtml):

<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>

  • Introduces instance variables: @sort_default, @sort_criteria

  • Introduces param :sort

Since:

  • 0.4.0

Instance Method Summary collapse

Instance Method Details

#sort_clause ⇒ Object

Returns an SQL sort clause corresponding to the current sort state. Use this to sort the controller's table items collection.



99
100
101
 
# File 'app/helpers/sort_helper.rb', line 99

def sort_clause()
  @sort_criteria.sort_clause(@sortable_columns)
end

#sort_clear ⇒ Object

Clears the sort criteria session data

Since:

  • 0.9.0



92
93
94
 
# File 'app/helpers/sort_helper.rb', line 92

def sort_clear
  session[sort_name] = nil
end

#sort_criteria ⇒ Object

Since:

  • 2.2.0



103
104
105
 
# File 'app/helpers/sort_helper.rb', line 103

def sort_criteria
  @sort_criteria
end

#sort_css_classes ⇒ Object

Returns the css classes for the current sort order

Example:

sort_css_classes
# => "sort-by-created-on sort-desc"

Since:

  • 2.6.0



157
158
159
160
161
 
# File 'app/helpers/sort_helper.rb', line 157

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

#sort_header_tag(column, options = {}) ⇒ Object

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) %>



144
145
146
147
148
149
 
# File 'app/helpers/sort_helper.rb', line 144

def sort_header_tag(column, options = {})
  caption = options.delete(:caption) || column.to_s.humanize
  default_order = options.delete(:default_order) || 'asc'
  options[:title] = l(:label_sort_by, "\"#{caption}\"") unless options[:title]
  content_tag('th', sort_link(column, caption, default_order), options)
end

#sort_init(*args) ⇒ Object

Initializes the default sort. Examples:

sort_init 'name'
sort_init 'id', 'desc'
sort_init ['name', ['id', 'desc']]
sort_init [['name', 'desc'], ['id', 'desc']]



68
69
70
71
72
73
74
75
76
77
 
# File 'app/helpers/sort_helper.rb', line 68

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
end

#sort_link(column, caption, default_order) ⇒ Object

Returns a link which sorts by the named column.

  • column is the name of an attribute in the sorted record collection.

  • the optional caption explicitly specifies the displayed link text.

  • 2 CSS classes reflect the state of the link: sort and asc or desc



113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'app/helpers/sort_helper.rb', line 113

def sort_link(column, caption, default_order)
  css, order = nil, default_order

  if column.to_s == @sort_criteria.first_key
    if @sort_criteria.first_asc?
      css = 'sort asc'
      order = 'desc'
    else
      css = 'sort desc'
      order = 'asc'
    end
  end
  caption = column.to_s.humanize unless caption

  sort_options = { :sort => @sort_criteria.add(column.to_s, order).to_param }
  link_to(caption, {:params => request.query_parameters.merge(sort_options)}, :class => css)
end

#sort_name ⇒ Object

Since:

  • 0.9.0



56
57
58
 
# File 'app/helpers/sort_helper.rb', line 56

def sort_name
  controller_name + '_' + action_name + '_sort'
end

#sort_update(criteria, sort_name = nil) ⇒ Object

Updates the sort state. Call this in the controller prior to calling sort_clause.

  • criteria can be either an array or a hash of allowed keys



83
84
85
86
87
88
 
# File 'app/helpers/sort_helper.rb', line 83

def sort_update(criteria, sort_name=nil)
  sort_name ||= self.sort_name
  @sort_criteria = Redmine::SortCriteria.new(params[:sort] || session[sort_name] || @sort_default)
  @sortable_columns = criteria
  session[sort_name] = @sort_criteria.to_param
end