| @@ -1,256 +1,256 | |||||
| 1 | # encoding: utf-8 |
|
1 | # encoding: utf-8 | |
| 2 | # |
|
2 | # | |
| 3 | # Helpers to sort tables using clickable column headers. |
|
3 | # Helpers to sort tables using clickable column headers. | |
| 4 | # |
|
4 | # | |
| 5 | # Author: Stuart Rackham <srackham@methods.co.nz>, March 2005. |
|
5 | # Author: Stuart Rackham <srackham@methods.co.nz>, March 2005. | |
| 6 | # Jean-Philippe Lang, 2009 |
|
6 | # Jean-Philippe Lang, 2009 | |
| 7 | # License: This source code is released under the MIT license. |
|
7 | # License: This source code is released under the MIT license. | |
| 8 | # |
|
8 | # | |
| 9 | # - Consecutive clicks toggle the column's sort order. |
|
9 | # - Consecutive clicks toggle the column's sort order. | |
| 10 | # - Sort state is maintained by a session hash entry. |
|
10 | # - Sort state is maintained by a session hash entry. | |
| 11 | # - CSS classes identify sort column and state. |
|
11 | # - CSS classes identify sort column and state. | |
| 12 | # - Typically used in conjunction with the Pagination module. |
|
12 | # - Typically used in conjunction with the Pagination module. | |
| 13 | # |
|
13 | # | |
| 14 | # Example code snippets: |
|
14 | # Example code snippets: | |
| 15 | # |
|
15 | # | |
| 16 | # Controller: |
|
16 | # Controller: | |
| 17 | # |
|
17 | # | |
| 18 | # helper :sort |
|
18 | # helper :sort | |
| 19 | # include SortHelper |
|
19 | # include SortHelper | |
| 20 | # |
|
20 | # | |
| 21 | # def list |
|
21 | # def list | |
| 22 | # sort_init 'last_name' |
|
22 | # sort_init 'last_name' | |
| 23 | # sort_update %w(first_name last_name) |
|
23 | # sort_update %w(first_name last_name) | |
| 24 | # @items = Contact.find_all nil, sort_clause |
|
24 | # @items = Contact.find_all nil, sort_clause | |
| 25 | # end |
|
25 | # end | |
| 26 | # |
|
26 | # | |
| 27 | # Controller (using Pagination module): |
|
27 | # Controller (using Pagination module): | |
| 28 | # |
|
28 | # | |
| 29 | # helper :sort |
|
29 | # helper :sort | |
| 30 | # include SortHelper |
|
30 | # include SortHelper | |
| 31 | # |
|
31 | # | |
| 32 | # def list |
|
32 | # def list | |
| 33 | # sort_init 'last_name' |
|
33 | # sort_init 'last_name' | |
| 34 | # sort_update %w(first_name last_name) |
|
34 | # sort_update %w(first_name last_name) | |
| 35 | # @contact_pages, @items = paginate :contacts, |
|
35 | # @contact_pages, @items = paginate :contacts, | |
| 36 | # :order_by => sort_clause, |
|
36 | # :order_by => sort_clause, | |
| 37 | # :per_page => 10 |
|
37 | # :per_page => 10 | |
| 38 | # end |
|
38 | # end | |
| 39 | # |
|
39 | # | |
| 40 | # View (table header in list.rhtml): |
|
40 | # View (table header in list.rhtml): | |
| 41 | # |
|
41 | # | |
| 42 | # <thead> |
|
42 | # <thead> | |
| 43 | # <tr> |
|
43 | # <tr> | |
| 44 | # <%= sort_header_tag('id', :title => 'Sort by contact ID') %> |
|
44 | # <%= sort_header_tag('id', :title => 'Sort by contact ID') %> | |
| 45 | # <%= sort_header_tag('last_name', :caption => 'Name') %> |
|
45 | # <%= sort_header_tag('last_name', :caption => 'Name') %> | |
| 46 | # <%= sort_header_tag('phone') %> |
|
46 | # <%= sort_header_tag('phone') %> | |
| 47 | # <%= sort_header_tag('address', :width => 200) %> |
|
47 | # <%= sort_header_tag('address', :width => 200) %> | |
| 48 | # </tr> |
|
48 | # </tr> | |
| 49 | # </thead> |
|
49 | # </thead> | |
| 50 | # |
|
50 | # | |
| 51 | # - Introduces instance variables: @sort_default, @sort_criteria |
|
51 | # - Introduces instance variables: @sort_default, @sort_criteria | |
| 52 | # - Introduces param :sort |
|
52 | # - Introduces param :sort | |
| 53 | # |
|
53 | # | |
| 54 |
|
54 | |||
| 55 | module SortHelper |
|
55 | module SortHelper | |
| 56 | class SortCriteria |
|
56 | class SortCriteria | |
| 57 |
|
57 | |||
| 58 | def initialize |
|
58 | def initialize | |
| 59 | @criteria = [] |
|
59 | @criteria = [] | |
| 60 | end |
|
60 | end | |
| 61 |
|
61 | |||
| 62 | def available_criteria=(criteria) |
|
62 | def available_criteria=(criteria) | |
| 63 | unless criteria.is_a?(Hash) |
|
63 | unless criteria.is_a?(Hash) | |
| 64 | criteria = criteria.inject({}) {|h,k| h[k] = k; h} |
|
64 | criteria = criteria.inject({}) {|h,k| h[k] = k; h} | |
| 65 | end |
|
65 | end | |
| 66 | @available_criteria = criteria |
|
66 | @available_criteria = criteria | |
| 67 | end |
|
67 | end | |
| 68 |
|
68 | |||
| 69 | def from_param(param) |
|
69 | def from_param(param) | |
| 70 | @criteria = param.to_s.split(',').collect {|s| s.split(':')[0..1]} |
|
70 | @criteria = param.to_s.split(',').collect {|s| s.split(':')[0..1]} | |
| 71 | normalize! |
|
71 | normalize! | |
| 72 | end |
|
72 | end | |
| 73 |
|
73 | |||
| 74 | def criteria=(arg) |
|
74 | def criteria=(arg) | |
| 75 | @criteria = arg |
|
75 | @criteria = arg | |
| 76 | normalize! |
|
76 | normalize! | |
| 77 | end |
|
77 | end | |
| 78 |
|
78 | |||
| 79 | def to_param |
|
79 | def to_param | |
| 80 | @criteria.collect {|k,o| k + (o ? '' : ':desc')}.join(',') |
|
80 | @criteria.collect {|k,o| k + (o ? '' : ':desc')}.join(',') | |
| 81 | end |
|
81 | end | |
| 82 |
|
82 | |||
| 83 | # Returns an array of SQL fragments used to sort the list |
|
83 | # Returns an array of SQL fragments used to sort the list | |
| 84 | def to_sql |
|
84 | def to_sql | |
| 85 | sql = @criteria.collect do |k,o| |
|
85 | sql = @criteria.collect do |k,o| | |
| 86 | if s = @available_criteria[k] |
|
86 | if s = @available_criteria[k] | |
| 87 | s = [s] unless s.is_a?(Array) |
|
87 | s = [s] unless s.is_a?(Array) | |
| 88 | (o ? s : s.collect {|c| append_desc(c)}) |
|
88 | (o ? s : s.collect {|c| append_desc(c)}) | |
| 89 | end |
|
89 | end | |
| 90 | end.flatten.compact |
|
90 | end.flatten.compact | |
| 91 | sql.blank? ? nil : sql |
|
91 | sql.blank? ? nil : sql | |
| 92 | end |
|
92 | end | |
| 93 |
|
93 | |||
| 94 | def to_a |
|
94 | def to_a | |
| 95 | @criteria.dup |
|
95 | @criteria.dup | |
| 96 | end |
|
96 | end | |
| 97 |
|
97 | |||
| 98 | def add!(key, asc) |
|
98 | def add!(key, asc) | |
| 99 | @criteria.delete_if {|k,o| k == key} |
|
99 | @criteria.delete_if {|k,o| k == key} | |
| 100 | @criteria = [[key, asc]] + @criteria |
|
100 | @criteria = [[key, asc]] + @criteria | |
| 101 | normalize! |
|
101 | normalize! | |
| 102 | end |
|
102 | end | |
| 103 |
|
103 | |||
| 104 | def add(*args) |
|
104 | def add(*args) | |
| 105 | r = self.class.new.from_param(to_param) |
|
105 | r = self.class.new.from_param(to_param) | |
| 106 | r.add!(*args) |
|
106 | r.add!(*args) | |
| 107 | r |
|
107 | r | |
| 108 | end |
|
108 | end | |
| 109 |
|
109 | |||
| 110 | def first_key |
|
110 | def first_key | |
| 111 | @criteria.first && @criteria.first.first |
|
111 | @criteria.first && @criteria.first.first | |
| 112 | end |
|
112 | end | |
| 113 |
|
113 | |||
| 114 | def first_asc? |
|
114 | def first_asc? | |
| 115 | @criteria.first && @criteria.first.last |
|
115 | @criteria.first && @criteria.first.last | |
| 116 | end |
|
116 | end | |
| 117 |
|
117 | |||
| 118 | def empty? |
|
118 | def empty? | |
| 119 | @criteria.empty? |
|
119 | @criteria.empty? | |
| 120 | end |
|
120 | end | |
| 121 |
|
121 | |||
| 122 | private |
|
122 | private | |
| 123 |
|
123 | |||
| 124 | def normalize! |
|
124 | def normalize! | |
| 125 | @criteria ||= [] |
|
125 | @criteria ||= [] | |
| 126 |
@criteria = @criteria.collect {|s| s = s |
|
126 | @criteria = @criteria.collect {|s| s = Array(s); [s.first, (s.last == false || s.last == 'desc') ? false : true]} | |
| 127 | @criteria = @criteria.select {|k,o| @available_criteria.has_key?(k)} if @available_criteria |
|
127 | @criteria = @criteria.select {|k,o| @available_criteria.has_key?(k)} if @available_criteria | |
| 128 | @criteria.slice!(3) |
|
128 | @criteria.slice!(3) | |
| 129 | self |
|
129 | self | |
| 130 | end |
|
130 | end | |
| 131 |
|
131 | |||
| 132 | # Appends DESC to the sort criterion unless it has a fixed order |
|
132 | # Appends DESC to the sort criterion unless it has a fixed order | |
| 133 | def append_desc(criterion) |
|
133 | def append_desc(criterion) | |
| 134 | if criterion =~ / (asc|desc)$/i |
|
134 | if criterion =~ / (asc|desc)$/i | |
| 135 | criterion |
|
135 | criterion | |
| 136 | else |
|
136 | else | |
| 137 | "#{criterion} DESC" |
|
137 | "#{criterion} DESC" | |
| 138 | end |
|
138 | end | |
| 139 | end |
|
139 | end | |
| 140 | end |
|
140 | end | |
| 141 |
|
141 | |||
| 142 | def sort_name |
|
142 | def sort_name | |
| 143 | controller_name + '_' + action_name + '_sort' |
|
143 | controller_name + '_' + action_name + '_sort' | |
| 144 | end |
|
144 | end | |
| 145 |
|
145 | |||
| 146 | # Initializes the default sort. |
|
146 | # Initializes the default sort. | |
| 147 | # Examples: |
|
147 | # Examples: | |
| 148 | # |
|
148 | # | |
| 149 | # sort_init 'name' |
|
149 | # sort_init 'name' | |
| 150 | # sort_init 'id', 'desc' |
|
150 | # sort_init 'id', 'desc' | |
| 151 | # sort_init ['name', ['id', 'desc']] |
|
151 | # sort_init ['name', ['id', 'desc']] | |
| 152 | # sort_init [['name', 'desc'], ['id', 'desc']] |
|
152 | # sort_init [['name', 'desc'], ['id', 'desc']] | |
| 153 | # |
|
153 | # | |
| 154 | def sort_init(*args) |
|
154 | def sort_init(*args) | |
| 155 | case args.size |
|
155 | case args.size | |
| 156 | when 1 |
|
156 | when 1 | |
| 157 | @sort_default = args.first.is_a?(Array) ? args.first : [[args.first]] |
|
157 | @sort_default = args.first.is_a?(Array) ? args.first : [[args.first]] | |
| 158 | when 2 |
|
158 | when 2 | |
| 159 | @sort_default = [[args.first, args.last]] |
|
159 | @sort_default = [[args.first, args.last]] | |
| 160 | else |
|
160 | else | |
| 161 | raise ArgumentError |
|
161 | raise ArgumentError | |
| 162 | end |
|
162 | end | |
| 163 | end |
|
163 | end | |
| 164 |
|
164 | |||
| 165 | # Updates the sort state. Call this in the controller prior to calling |
|
165 | # Updates the sort state. Call this in the controller prior to calling | |
| 166 | # sort_clause. |
|
166 | # sort_clause. | |
| 167 | # - criteria can be either an array or a hash of allowed keys |
|
167 | # - criteria can be either an array or a hash of allowed keys | |
| 168 | # |
|
168 | # | |
| 169 | def sort_update(criteria, sort_name=nil) |
|
169 | def sort_update(criteria, sort_name=nil) | |
| 170 | sort_name ||= self.sort_name |
|
170 | sort_name ||= self.sort_name | |
| 171 | @sort_criteria = SortCriteria.new |
|
171 | @sort_criteria = SortCriteria.new | |
| 172 | @sort_criteria.available_criteria = criteria |
|
172 | @sort_criteria.available_criteria = criteria | |
| 173 | @sort_criteria.from_param(params[:sort] || session[sort_name]) |
|
173 | @sort_criteria.from_param(params[:sort] || session[sort_name]) | |
| 174 | @sort_criteria.criteria = @sort_default if @sort_criteria.empty? |
|
174 | @sort_criteria.criteria = @sort_default if @sort_criteria.empty? | |
| 175 | session[sort_name] = @sort_criteria.to_param |
|
175 | session[sort_name] = @sort_criteria.to_param | |
| 176 | end |
|
176 | end | |
| 177 |
|
177 | |||
| 178 | # Clears the sort criteria session data |
|
178 | # Clears the sort criteria session data | |
| 179 | # |
|
179 | # | |
| 180 | def sort_clear |
|
180 | def sort_clear | |
| 181 | session[sort_name] = nil |
|
181 | session[sort_name] = nil | |
| 182 | end |
|
182 | end | |
| 183 |
|
183 | |||
| 184 | # Returns an SQL sort clause corresponding to the current sort state. |
|
184 | # Returns an SQL sort clause corresponding to the current sort state. | |
| 185 | # Use this to sort the controller's table items collection. |
|
185 | # Use this to sort the controller's table items collection. | |
| 186 | # |
|
186 | # | |
| 187 | def sort_clause() |
|
187 | def sort_clause() | |
| 188 | @sort_criteria.to_sql |
|
188 | @sort_criteria.to_sql | |
| 189 | end |
|
189 | end | |
| 190 |
|
190 | |||
| 191 | def sort_criteria |
|
191 | def sort_criteria | |
| 192 | @sort_criteria |
|
192 | @sort_criteria | |
| 193 | end |
|
193 | end | |
| 194 |
|
194 | |||
| 195 | # Returns a link which sorts by the named column. |
|
195 | # Returns a link which sorts by the named column. | |
| 196 | # |
|
196 | # | |
| 197 | # - column is the name of an attribute in the sorted record collection. |
|
197 | # - column is the name of an attribute in the sorted record collection. | |
| 198 | # - the optional caption explicitly specifies the displayed link text. |
|
198 | # - the optional caption explicitly specifies the displayed link text. | |
| 199 | # - 2 CSS classes reflect the state of the link: sort and asc or desc |
|
199 | # - 2 CSS classes reflect the state of the link: sort and asc or desc | |
| 200 | # |
|
200 | # | |
| 201 | def sort_link(column, caption, default_order) |
|
201 | def sort_link(column, caption, default_order) | |
| 202 | css, order = nil, default_order |
|
202 | css, order = nil, default_order | |
| 203 |
|
203 | |||
| 204 | if column.to_s == @sort_criteria.first_key |
|
204 | if column.to_s == @sort_criteria.first_key | |
| 205 | if @sort_criteria.first_asc? |
|
205 | if @sort_criteria.first_asc? | |
| 206 | css = 'sort asc' |
|
206 | css = 'sort asc' | |
| 207 | order = 'desc' |
|
207 | order = 'desc' | |
| 208 | else |
|
208 | else | |
| 209 | css = 'sort desc' |
|
209 | css = 'sort desc' | |
| 210 | order = 'asc' |
|
210 | order = 'asc' | |
| 211 | end |
|
211 | end | |
| 212 | end |
|
212 | end | |
| 213 | caption = column.to_s.humanize unless caption |
|
213 | caption = column.to_s.humanize unless caption | |
| 214 |
|
214 | |||
| 215 | sort_options = { :sort => @sort_criteria.add(column.to_s, order).to_param } |
|
215 | sort_options = { :sort => @sort_criteria.add(column.to_s, order).to_param } | |
| 216 | url_options = params.merge(sort_options) |
|
216 | url_options = params.merge(sort_options) | |
| 217 |
|
217 | |||
| 218 | # Add project_id to url_options |
|
218 | # Add project_id to url_options | |
| 219 | url_options = url_options.merge(:project_id => params[:project_id]) if params.has_key?(:project_id) |
|
219 | url_options = url_options.merge(:project_id => params[:project_id]) if params.has_key?(:project_id) | |
| 220 |
|
220 | |||
| 221 | link_to_content_update(h(caption), url_options, :class => css) |
|
221 | link_to_content_update(h(caption), url_options, :class => css) | |
| 222 | end |
|
222 | end | |
| 223 |
|
223 | |||
| 224 | # Returns a table header <th> tag with a sort link for the named column |
|
224 | # Returns a table header <th> tag with a sort link for the named column | |
| 225 | # attribute. |
|
225 | # attribute. | |
| 226 | # |
|
226 | # | |
| 227 | # Options: |
|
227 | # Options: | |
| 228 | # :caption The displayed link name (defaults to titleized column name). |
|
228 | # :caption The displayed link name (defaults to titleized column name). | |
| 229 | # :title The tag's 'title' attribute (defaults to 'Sort by :caption'). |
|
229 | # :title The tag's 'title' attribute (defaults to 'Sort by :caption'). | |
| 230 | # |
|
230 | # | |
| 231 | # Other options hash entries generate additional table header tag attributes. |
|
231 | # Other options hash entries generate additional table header tag attributes. | |
| 232 | # |
|
232 | # | |
| 233 | # Example: |
|
233 | # Example: | |
| 234 | # |
|
234 | # | |
| 235 | # <%= sort_header_tag('id', :title => 'Sort by contact ID', :width => 40) %> |
|
235 | # <%= sort_header_tag('id', :title => 'Sort by contact ID', :width => 40) %> | |
| 236 | # |
|
236 | # | |
| 237 | def sort_header_tag(column, options = {}) |
|
237 | def sort_header_tag(column, options = {}) | |
| 238 | caption = options.delete(:caption) || column.to_s.humanize |
|
238 | caption = options.delete(:caption) || column.to_s.humanize | |
| 239 | default_order = options.delete(:default_order) || 'asc' |
|
239 | default_order = options.delete(:default_order) || 'asc' | |
| 240 | options[:title] = l(:label_sort_by, "\"#{caption}\"") unless options[:title] |
|
240 | options[:title] = l(:label_sort_by, "\"#{caption}\"") unless options[:title] | |
| 241 | content_tag('th', sort_link(column, caption, default_order), options) |
|
241 | content_tag('th', sort_link(column, caption, default_order), options) | |
| 242 | end |
|
242 | end | |
| 243 |
|
243 | |||
| 244 | # Returns the css classes for the current sort order |
|
244 | # Returns the css classes for the current sort order | |
| 245 | # |
|
245 | # | |
| 246 | # Example: |
|
246 | # Example: | |
| 247 | # |
|
247 | # | |
| 248 | # sort_css_classes |
|
248 | # sort_css_classes | |
| 249 | # # => "sort-by-created-on sort-desc" |
|
249 | # # => "sort-by-created-on sort-desc" | |
| 250 | def sort_css_classes |
|
250 | def sort_css_classes | |
| 251 | if @sort_criteria.first_key |
|
251 | if @sort_criteria.first_key | |
| 252 | "sort-by-#{@sort_criteria.first_key.to_s.dasherize} sort-#{@sort_criteria.first_asc? ? 'asc' : 'desc'}" |
|
252 | "sort-by-#{@sort_criteria.first_key.to_s.dasherize} sort-#{@sort_criteria.first_asc? ? 'asc' : 'desc'}" | |
| 253 | end |
|
253 | end | |
| 254 | end |
|
254 | end | |
| 255 | end |
|
255 | end | |
| 256 |
|
256 | |||
General Comments 0
You need to be logged in to leave comments.
Login now