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 <[email protected]>, 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
Instance Method Summary collapse
-
#sort_clause ⇒ Object
Returns an SQL sort clause corresponding to the current sort state.
-
#sort_clear ⇒ Object
Clears the sort criteria session data.
- #sort_criteria ⇒ Object
-
#sort_css_classes ⇒ Object
Returns the css classes for the current sort order.
-
#sort_header_tag(column, options = {}) ⇒ Object
Returns a table header <th> tag with a sort link for the named column attribute.
-
#sort_init(*args) ⇒ Object
Initializes the default sort.
-
#sort_link(column, caption, default_order) ⇒ Object
Returns a link which sorts by the named column.
- #sort_name ⇒ Object
-
#sort_update(criteria, sort_name = nil) ⇒ Object
Updates the sort state.
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
92 93 94 |
# File 'app/helpers/sort_helper.rb', line 92 def sort_clear session[sort_name] = nil end |
#sort_criteria ⇒ Object
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"
159 160 161 162 163 |
# File 'app/helpers/sort_helper.rb', line 159 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) %>
146 147 148 149 150 151 |
# File 'app/helpers/sort_helper.rb', line 146 def sort_header_tag(column, = {}) = .delete(:caption) || column.to_s.humanize default_order = .delete(:default_order) || 'asc' [:title] = l(:label_sort_by, "\"#{}\"") unless [:title] content_tag('th', sort_link(column, , default_order), ) 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 130 131 |
# File 'app/helpers/sort_helper.rb', line 113 def sort_link(column, , default_order) css, order = nil, default_order if column.to_s == @sort_criteria.first_key if @sort_criteria.first_asc? css = 'sort asc icon icon-sorted-desc' icon = 'angle-up' order = 'desc' else css = 'sort desc icon icon-sorted-asc' icon = 'angle-down' order = 'asc' end end = column.to_s.humanize unless = {:sort => @sort_criteria.add(column.to_s, order).to_param} link_to(sprite_icon(icon, ), { :params => request.query_parameters.merge()}, :class => css) end |
#sort_name ⇒ Object
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 |