wice_grid 3.0.4 → 3.2.0.pre1
Sign up to get free protection for your applications and to get access to all the features.
- data/CHANGELOG +24 -2
- data/README.rdoc +282 -316
- data/RELEASE_NOTES_3.2.pre1.rdoc +82 -0
- data/Rakefile +4 -2
- data/SAVED_QUERIES_HOWTO.rdoc +18 -31
- data/VERSION +1 -1
- data/lib/generators/wice_grid/add_migration_for_serialized_queries_generator.rb +22 -0
- data/lib/generators/wice_grid/install_generator.rb +20 -0
- data/lib/generators/wice_grid/templates/create_wice_grid_serialized_queries.rb +13 -0
- data/lib/generators/wice_grid/templates/wice_grid.css.scss +139 -0
- data/lib/generators/wice_grid/templates/wice_grid.yml +113 -19
- data/lib/generators/wice_grid/templates/wice_grid_config.rb +17 -41
- data/lib/grid_output_buffer.rb +3 -2
- data/lib/grid_renderer.rb +63 -102
- data/lib/helpers/js_calendar_helpers.rb +27 -157
- data/lib/helpers/wice_grid_misc_view_helpers.rb +1 -66
- data/lib/helpers/wice_grid_serialized_queries_view_helpers.rb +41 -32
- data/lib/helpers/wice_grid_view_helpers.rb +138 -274
- data/lib/table_column_matrix.rb +11 -11
- data/lib/view_columns.rb +41 -350
- data/lib/view_columns/action_view_column.rb +45 -0
- data/lib/view_columns/column_processor_index.rb +16 -0
- data/lib/view_columns/view_column_boolean.rb +23 -0
- data/lib/view_columns/view_column_custom_dropdown.rb +81 -0
- data/lib/view_columns/view_column_date.rb +17 -0
- data/lib/view_columns/view_column_datetime.rb +85 -0
- data/lib/view_columns/view_column_float.rb +7 -0
- data/lib/view_columns/view_column_integer.rb +38 -0
- data/lib/view_columns/view_column_string.rb +63 -0
- data/lib/wice_grid.rb +23 -26
- data/lib/wice_grid_controller.rb +14 -15
- data/lib/wice_grid_misc.rb +3 -3
- data/lib/wice_grid_serialized_queries_controller.rb +15 -18
- data/lib/wice_grid_spreadsheet.rb +2 -2
- data/lib/will_paginate_paginator.rb +31 -0
- data/test/readme.txt +1 -0
- data/{lib/generators/wice_grid/templates/icons → vendor/assets/images/icons/grid}/arrow_down.gif +0 -0
- data/{lib/generators/wice_grid/templates/icons → vendor/assets/images/icons/grid}/arrow_up.gif +0 -0
- data/{lib/generators/wice_grid/templates/icons → vendor/assets/images/icons/grid}/calendar_view_month.png +0 -0
- data/vendor/assets/images/icons/grid/collapse.gif +0 -0
- data/{lib/generators/wice_grid/templates/icons → vendor/assets/images/icons/grid}/delete.png +0 -0
- data/vendor/assets/images/icons/grid/expand.gif +0 -0
- data/{lib/generators/wice_grid/templates/icons → vendor/assets/images/icons/grid}/page_white_excel.png +0 -0
- data/{lib/generators/wice_grid/templates/icons → vendor/assets/images/icons/grid}/page_white_find.png +0 -0
- data/{lib/generators/wice_grid/templates/icons → vendor/assets/images/icons/grid}/table.png +0 -0
- data/{lib/generators/wice_grid/templates/icons → vendor/assets/images/icons/grid}/table_refresh.png +0 -0
- data/{lib/generators/wice_grid/templates/icons → vendor/assets/images/icons/grid}/tick_all.png +0 -0
- data/{lib/generators/wice_grid/templates/icons → vendor/assets/images/icons/grid}/untick_all.png +0 -0
- data/vendor/assets/javascripts/wice_grid.js +3 -0
- data/vendor/assets/javascripts/wice_grid_init.js.coffee +247 -0
- data/vendor/assets/javascripts/wice_grid_processor.js.coffee +128 -0
- data/vendor/assets/javascripts/wice_grid_saved_queries_init.js.coffee +103 -0
- data/wice_grid.gemspec +44 -50
- metadata +68 -94
- data/lib/generators/wice_grid/templates/calendarview.css +0 -107
- data/lib/generators/wice_grid/templates/calendarview.js +0 -1168
- data/lib/generators/wice_grid/templates/icons/expand.png +0 -0
- data/lib/generators/wice_grid/templates/wice_grid.css +0 -173
- data/lib/generators/wice_grid/templates/wice_grid_jquery.js +0 -162
- data/lib/generators/wice_grid/templates/wice_grid_prototype.js +0 -154
- data/lib/generators/wice_grid/wice_grid_assets_jquery_generator.rb +0 -32
- data/lib/generators/wice_grid/wice_grid_assets_prototype_generator.rb +0 -34
- data/lib/js_adaptors/jquery_adaptor.rb +0 -157
- data/lib/js_adaptors/js_adaptor.rb +0 -12
- data/lib/js_adaptors/prototype_adaptor.rb +0 -179
- data/lib/tasks/wice_grid_tasks.rake +0 -28
- data/lib/views/create.rjs +0 -13
- data/lib/views/create_jq.rjs +0 -31
- data/lib/views/delete.rjs +0 -12
- data/lib/views/delete_jq.rjs +0 -26
- data/test/.gitignore +0 -2
- data/test/database.yml +0 -21
- data/test/schema.rb +0 -33
- data/test/test_helper.rb +0 -89
- data/test/views/projects_and_people_grid.html.erb +0 -12
- data/test/views/projects_and_people_grid_invalid.html.erb +0 -12
- data/test/views/simple_projects_grid.html.erb +0 -9
- data/test/wice_grid_core_ext_test.rb +0 -183
- data/test/wice_grid_functional_test.rb +0 -68
- data/test/wice_grid_misc_test.rb +0 -41
- data/test/wice_grid_test.rb +0 -42
- data/test/wice_grid_view_helper_test.rb +0 -12
data/CHANGELOG
CHANGED
@@ -1,9 +1,31 @@
|
|
1
|
+
to do:
|
2
|
+
|
3
|
+
1) get rid of this :href => "javascript: toggle_multi_select
|
4
|
+
at view_columns
|
5
|
+
|
6
|
+
+++++++
|
7
|
+
+++++++
|
8
|
+
3.2.0pre1
|
9
|
+
|
10
|
+
|
11
|
+
3.0.4
|
12
|
+
|
13
|
+
bugxixes
|
14
|
+
|
15
|
+
3.0.3
|
16
|
+
|
17
|
+
bugxixes
|
18
|
+
|
19
|
+
3.0.2
|
20
|
+
|
21
|
+
bugxixes
|
22
|
+
|
1
23
|
3.0.1
|
2
24
|
|
3
25
|
Fixed the "Cannot modify SafeBuffer in place" problem and thus Rails 3.0.8 and 3.0.9
|
4
26
|
Support for ActiveRecord::Relation
|
5
27
|
|
6
|
-
3.0.0
|
28
|
+
3.0.0
|
7
29
|
|
8
30
|
Rails 3 support
|
9
31
|
|
@@ -354,7 +376,7 @@ Creates a new branch for version 2.3
|
|
354
376
|
=== 21/10/2008
|
355
377
|
|
356
378
|
A bugfix related to custom filters influencing other columns with filters
|
357
|
-
A more informative error message if the grid can't find the underlying database column for a view column (incorrect :column_name and :
|
379
|
+
A more informative error message if the grid can't find the underlying database column for a view column (incorrect :column_name and :model)
|
358
380
|
|
359
381
|
=== 8/10/2008
|
360
382
|
|
data/README.rdoc
CHANGED
@@ -1,28 +1,30 @@
|
|
1
1
|
= WiceGrid
|
2
2
|
|
3
|
-
Version:: 3.0.
|
3
|
+
Version:: 3.2.0.pre1
|
4
4
|
Author:: Yuri Leikind
|
5
|
-
|
5
|
+
Sources:: https://github.com/leikind/wice_grid/
|
6
6
|
Examples online:: http://grid.leikind.org
|
7
|
-
News:: http://leikind.org/wicegrid
|
7
|
+
News:: http://leikind.org/pages/wicegrid/
|
8
8
|
Email:: "Yuri Leikind" <yuri.leikind at gmail dot com>
|
9
9
|
|
10
|
-
== Attention!
|
11
|
-
There are two major branches of WiceGrid.
|
12
10
|
|
13
|
-
|
14
|
-
|
11
|
+
FOR RAILS 3.0.X AND 3.1.X USE VERSION 3.0.4.
|
12
|
+
FOR RAILS 2 USE VERSION 0.6 (https://github.com/leikind/wice_grid/tree/master).
|
13
|
+
|
15
14
|
|
16
|
-
For Rails 2 WiceGrid only works as a Rails plugin. See WiceGrid version 0.6 (https://github.com/leikind/wice_grid/tree/master).
|
17
15
|
|
18
16
|
== Intro
|
19
17
|
|
20
18
|
WiceGrid is a Rails grid plugin.
|
21
19
|
|
22
|
-
One of the goals of this plugin was to allow the programmer to define the contents of the cell by himself,
|
20
|
+
One of the goals of this plugin was to allow the programmer to define the contents of the cell by himself,
|
21
|
+
just like one does when rendering a collection via a simple table (and this is what differentiates WiceGrid
|
22
|
+
from various scaffolding solutions), but automate implementation of filters, ordering, paginations,
|
23
|
+
CSV export, and so on. Ruby blocks provide an elegant means for this.
|
23
24
|
|
24
25
|
|
25
|
-
WiceGrid builds the call to the ActiveRecord layer for you and creates a table view with the results
|
26
|
+
WiceGrid builds the call to the ActiveRecord layer for you and creates a table view with the results
|
27
|
+
of the call including:
|
26
28
|
|
27
29
|
* paging
|
28
30
|
* sortable columns
|
@@ -30,98 +32,78 @@ WiceGrid builds the call to the ActiveRecord layer for you and creates a table v
|
|
30
32
|
* CSV export
|
31
33
|
* saving queries
|
32
34
|
|
33
|
-
All working nicely together. Filters are added automatically according to the type of the underlying DB column.
|
35
|
+
All working nicely together. Filters are added automatically according to the type of the underlying DB column.
|
36
|
+
Filtering by more than one column at the same time is possible.
|
37
|
+
More than one such grid can appear on a page, and manipulations with one grid do not have any impact on the other.
|
34
38
|
|
35
|
-
WiceGrid does not take a collection as an input, it works directly with ActiveRecord
|
39
|
+
WiceGrid does not take a collection as an input, it works directly with ActiveRecord.
|
36
40
|
|
37
|
-
WiceGrid does not use AJAX calls to reload itself, instead simple GET requests are used for this,
|
41
|
+
WiceGrid does not use AJAX calls to reload itself, instead simple GET requests are used for this,
|
42
|
+
nevertheless, all other page parameters are respected and preserved.
|
43
|
+
WiceGrid views do not contain forms so you can include it in your own forms.
|
38
44
|
|
39
45
|
There are two major branches of WiceGrid.
|
40
46
|
|
41
|
-
The current branch (https://github.com/leikind/wice_grid/tree/rails3) starts with version 3.0, works with Rails 3, and can only be used as a gem.
|
42
|
-
|
43
|
-
For Rails 2 WiceGrid only works as a Rails plugin. See WiceGrid version 0.6 (https://github.com/leikind/wice_grid/).
|
44
|
-
|
45
47
|
WiceGrid is known to work with MySQL and Postgres.
|
46
48
|
|
47
|
-
WiceGrid works with Prototype and jQuery
|
48
|
-
|
49
49
|
=== Examples
|
50
50
|
|
51
|
-
This tutorial is accompanied by a sample application with WiceGrid examples which you
|
51
|
+
This tutorial is accompanied by a sample application with WiceGrid examples which you
|
52
|
+
can browse online ( http://grid.leikind.org ),
|
53
|
+
or just view the code ( https://github.com/leikind/wice_grid_testbed ).
|
52
54
|
|
53
55
|
|
54
56
|
== Requirements
|
55
57
|
|
56
|
-
Rails version 3.
|
57
|
-
|
58
|
-
|
59
|
-
|
60
|
-
<tt>Prototype[http://www.prototypejs.org]</tt> version 1.5.1 or newer, or <tt>jQuery[http://jquery.com/]</tt>.
|
58
|
+
Rails version 3.2.x or newer, jQuery, jQuery Datepicker.
|
59
|
+
For Rails 3.0.x and 3.1.x versions use version 3.0.4.
|
60
|
+
For Rails 2 use version 0.6 (https://github.com/leikind/wice_grid/tree/master).
|
61
61
|
|
62
62
|
== How-To
|
63
63
|
|
64
|
-
=== Installation
|
65
64
|
|
66
|
-
|
65
|
+
=== Support for javascript frameworks
|
67
66
|
|
68
|
-
|
67
|
+
WiceGrid started as a plugin using the Prototype javascript framework.
|
68
|
+
Support for jQuery was added for version 0.6.
|
69
|
+
Beginning from version 3.2 only jQuery is supported.
|
69
70
|
|
70
|
-
and run the <tt>bundle</tt> command.
|
71
71
|
|
72
|
-
|
72
|
+
=== Installation
|
73
73
|
|
74
|
-
|
74
|
+
Add the following to your Gemfile:
|
75
75
|
|
76
|
-
|
76
|
+
gem "wice_grid", '3.2.0.pre1'
|
77
77
|
|
78
|
-
|
78
|
+
and run the <tt>bundle</tt> command.
|
79
79
|
|
80
|
-
|
80
|
+
Run the generator:
|
81
81
|
|
82
|
-
|
82
|
+
rails g wice_grid:install
|
83
83
|
|
84
|
-
|
85
|
-
|
86
|
-
|
84
|
+
This adds the config file <tt>wice_grid_config.rb</tt> to <tt>config/initializers/</tt>, the locale file
|
85
|
+
<tt>wice_grid.yml</tt> to <tt>config/locales/</tt>, and the styles file
|
86
|
+
<tt>wice_grid.css.scss</tt> to <tt>app/assets/stylesheets/</tt>.
|
87
87
|
|
88
|
-
|
89
|
-
configuration file <tt>wice_grid_config.rb</tt> defines for which JS framework code should be generated.
|
90
|
-
Generators +wice_grid_assets_prototype+ and +wice_grid_assets_jquery+ create a version of <tt>wice_grid_config.rb</tt>
|
91
|
-
with the corresponding value of <tt>Wice::Defaults::JS_FRAMEWORK</tt>.
|
88
|
+
Require WiceGrid javascript in your js index file:
|
92
89
|
|
90
|
+
//= require wice_grid
|
93
91
|
|
94
|
-
|
95
|
-
|
92
|
+
Make sure that jQuery is required, and if the application uses Date and DateTime filters, jQuery Datepicker has
|
93
|
+
to be required as well. Here is an example of application.js with everything WiceGrid needs:
|
96
94
|
|
97
|
-
|
98
|
-
|
99
|
-
|
100
|
-
|
95
|
+
//= require jquery
|
96
|
+
//= require jquery_ujs
|
97
|
+
//= require jquery-ui
|
98
|
+
//= require wice_grid
|
99
|
+
//= require jquery.ui.datepicker
|
100
|
+
//= require_tree .
|
101
101
|
|
102
|
-
It is always possible to fall back to simple dropdown lists that the standard date/datetime Rails helpers use.
|
103
102
|
|
104
|
-
JQUERY DATEPICKER IS ONLY USED FOR DATE FILTERS AT THE MOMENT. DATETIME FILTERS FALL BACK TO THE DEFAULT
|
105
|
-
RAILS DATE/DATETIME HELPERS.
|
106
103
|
|
107
104
|
|
108
105
|
=== Basics
|
109
106
|
|
110
|
-
The Prototype version of WiceGrid requires <tt>prototype.js</tt> and <tt>effects.js</tt> in order to function.
|
111
|
-
The jQuery version of WiceGrid requires <tt>jquery.js</tt>, the Datepicker widget from jQuery UI, and the Highlight and Fade effects for the saved queries functionality.
|
112
|
-
|
113
|
-
Thus, make sure you require all necessary JS assets in your layout template.
|
114
|
-
|
115
|
-
To include WiceGrid javascript and stylesheet files to the page use helper +include_wice_grid_assets+ :
|
116
|
-
|
117
|
-
<%= include_wice_grid_assets %>
|
118
|
-
|
119
|
-
The default behavior of +include_wice_grid_assets+ is a bit magical in the sense that it
|
120
|
-
produces no output if the page contains no grids, so don't panic if you see no WiceGrid includes.
|
121
|
-
If you prefer to always have WiceGrid stylesheet and javascript, use
|
122
|
-
|
123
|
-
<%= include_wice_grid_assets :load_on_demand => false %>
|
124
|
-
|
125
107
|
The simplest example of a WiceGrid for one simple DB table called ApplicationAccount is the following:
|
126
108
|
|
127
109
|
Controller:
|
@@ -158,31 +140,27 @@ View:
|
|
158
140
|
end -%>
|
159
141
|
|
160
142
|
Code <tt>g.column do |task| ... end</tt>
|
161
|
-
defines everything related to a column in the resulting view table including column names, sorting,
|
143
|
+
defines everything related to a column in the resulting view table including column names, sorting,
|
144
|
+
filtering, the content of the column cells, etc.
|
162
145
|
The return value of the block is the table cell content.
|
163
146
|
|
164
|
-
|
165
|
-
the number of all extracted records exceeds the default number of rows per page.
|
166
|
-
|
167
|
-
|
168
|
-
|
169
|
-
Column names are defined with parameter <tt>:column_name</tt>:
|
147
|
+
Column names are defined with parameter <tt>:name</tt>:
|
170
148
|
|
171
149
|
<%= grid(@tasks_grid) do |g|
|
172
150
|
|
173
|
-
g.column :
|
151
|
+
g.column :name => 'ID' do |task|
|
174
152
|
task.id
|
175
153
|
end
|
176
154
|
|
177
|
-
g.column :
|
155
|
+
g.column :name => 'Title' do |task|
|
178
156
|
task.title
|
179
157
|
end
|
180
158
|
|
181
|
-
g.column :
|
159
|
+
g.column :name => 'Description' do |task|
|
182
160
|
task.description
|
183
161
|
end
|
184
162
|
|
185
|
-
g.column :
|
163
|
+
g.column :name => 'Archived' do |task|
|
186
164
|
task.archived? ? 'Yes' : 'No'
|
187
165
|
end
|
188
166
|
|
@@ -191,24 +169,24 @@ Column names are defined with parameter <tt>:column_name</tt>:
|
|
191
169
|
end
|
192
170
|
end -%>
|
193
171
|
|
194
|
-
To add filtering and ordering, declare to which column in the underlying database
|
195
|
-
parameter <tt>:
|
172
|
+
To add filtering and ordering, declare to which column in the underlying database
|
173
|
+
table(s) the view column corresponds using parameter <tt>:attribute</tt> :
|
196
174
|
|
197
175
|
<%= grid(@tasks_grid) do |g|
|
198
176
|
|
199
|
-
g.column :
|
177
|
+
g.column :name => 'ID', :attribute => 'id' do |task|
|
200
178
|
task.id
|
201
179
|
end
|
202
180
|
|
203
|
-
g.column :
|
181
|
+
g.column :name => 'Title', :attribute => 'title' do |task|
|
204
182
|
task.title
|
205
183
|
end
|
206
184
|
|
207
|
-
g.column :
|
185
|
+
g.column :name => 'Description', :attribute => 'description' do |task|
|
208
186
|
task.description
|
209
187
|
end
|
210
188
|
|
211
|
-
g.column :
|
189
|
+
g.column :name => 'Archived', :attribute => 'archived' do |task|
|
212
190
|
task.archived? ? 'Yes' : 'No'
|
213
191
|
end
|
214
192
|
|
@@ -220,32 +198,38 @@ parameter <tt>:attribute_name</tt> :
|
|
220
198
|
This will add sorting links and filters for columns +Username+ and +Active+.
|
221
199
|
The plugin automatically creates filters according to the type
|
222
200
|
of the database column. In the above example a text field will be created for column Title (title is a string),
|
223
|
-
for column +Archived+ a dropdown filter will be created with options 'Yes', 'No', and '--',
|
201
|
+
for column +Archived+ a dropdown filter will be created with options 'Yes', 'No', and '--',
|
202
|
+
and for the integer ID two short text fields are
|
224
203
|
added which can contain the numeric range (more than, less than).
|
225
204
|
|
226
|
-
It is important to remember that <tt>:
|
205
|
+
It is important to remember that <tt>:attribute</tt> is the name of the database column,
|
206
|
+
not a model attribute.
|
207
|
+
Of course, all database columns have corresponding model attributes,
|
208
|
+
but not all model attributes map to columns in the same table with the same name.
|
227
209
|
|
228
210
|
Read more about available filters in the documentation
|
229
|
-
for the column method.
|
211
|
+
for the column method.
|
212
|
+
|
213
|
+
Read the section about custom dropdown filters for more advanced filters.
|
230
214
|
|
231
215
|
|
232
216
|
For columns like
|
233
217
|
|
234
|
-
g.column :
|
218
|
+
g.column :name => 'Title', :attribute => 'title' do |task|
|
235
219
|
task.title
|
236
220
|
end
|
237
221
|
|
238
|
-
where the block contains just a call to the same attribute declared by :
|
222
|
+
where the block contains just a call to the same attribute declared by :attribute, the block can be omitted:
|
239
223
|
|
240
224
|
<%= grid(@tasks_grid) do |g|
|
241
225
|
|
242
|
-
g.column :
|
226
|
+
g.column :name => 'ID', :attribute => 'id'
|
243
227
|
|
244
|
-
g.column :
|
228
|
+
g.column :name => 'Title', :attribute => 'title'
|
245
229
|
|
246
|
-
g.column :
|
230
|
+
g.column :name => 'Description', :attribute => 'description'
|
247
231
|
|
248
|
-
g.column :
|
232
|
+
g.column :name => 'Archived', :attribute => 'archived' do |task|
|
249
233
|
task.archived? ? 'Yes' : 'No'
|
250
234
|
end
|
251
235
|
|
@@ -255,28 +239,31 @@ where the block contains just a call to the same attribute declared by :attribut
|
|
255
239
|
end -%>
|
256
240
|
|
257
241
|
|
258
|
-
In this case +
|
242
|
+
In this case +name+ will be used as the method name to send to the ActiveRecord instance.
|
259
243
|
|
260
|
-
If only
|
244
|
+
If only ordering is needed, and no filter, we can turn off filters using <tt>:filter</tt> :
|
261
245
|
|
262
|
-
g.column :
|
246
|
+
g.column :name => 'ID', :attribute => 'id', :filter => false
|
263
247
|
|
264
|
-
If no ordering links are needed, use <tt>:
|
248
|
+
If no ordering links are needed, use <tt>:ordering => false</tt>:
|
265
249
|
|
266
|
-
g.column :
|
250
|
+
g.column :name => 'Added', :attribute => 'created_at', :ordering => false
|
267
251
|
|
268
|
-
It is important to understand that it is up to the developer to make sure that the value
|
252
|
+
It is important to understand that it is up to the developer to make sure that the value
|
253
|
+
returned by a column block (the content of a cell) corresponds to the underlying database
|
254
|
+
column specified by <tt>:attribute</tt> (and <tt>:model</tt> discussed below).
|
269
255
|
|
270
256
|
|
271
257
|
=== Rendering filter panel
|
272
258
|
|
273
259
|
The filter panel can be shown and hidden clicking the icon with binoculars.
|
274
260
|
|
275
|
-
The way the filter panel is shown after the page is loaded is controlled via parameter
|
261
|
+
The way the filter panel is shown after the page is loaded is controlled via parameter
|
262
|
+
<tt>:show_filters</tt> of the <tt>grid</tt> helper.
|
276
263
|
Possible values are:
|
277
264
|
|
278
265
|
* <tt>:when_filtered</tt> - the filter is shown when the current table is the result of filtering
|
279
|
-
* <tt>:always</tt> - show the filter
|
266
|
+
* <tt>:always</tt> - always show the filter
|
280
267
|
* <tt>:no</tt> - never show the filter
|
281
268
|
|
282
269
|
Example:
|
@@ -294,7 +281,9 @@ the configuration file.
|
|
294
281
|
|
295
282
|
=== Initial Ordering
|
296
283
|
|
297
|
-
Initializing the grid we can also define the column by which the record will be ordered
|
284
|
+
Initializing the grid we can also define the column by which the record will be ordered
|
285
|
+
<em>on the first rendering of the grid</em>, when the user has not set their ordering
|
286
|
+
setting by clicking the column label, and the order direction:
|
298
287
|
|
299
288
|
@tasks_grid = initialize_grid(Task,
|
300
289
|
:order => 'tasks.title',
|
@@ -309,7 +298,8 @@ The number of rows per page is set with <tt>:per_page</tt>:
|
|
309
298
|
|
310
299
|
=== Conditions
|
311
300
|
|
312
|
-
The +initialize_grid+ method supports a <tt>:conditions</tt> parameter which is passed
|
301
|
+
The +initialize_grid+ method supports a <tt>:conditions</tt> parameter which is passed
|
302
|
+
on to the underlying ActiveRecord, so it can be in any format processable by ActiveRecord:
|
313
303
|
|
314
304
|
@tasks_grid = initialize_grid(Task,
|
315
305
|
:conditions => ["archived = false and estimated_time > ?", 100]
|
@@ -357,26 +347,31 @@ WiceGrid also supports ActiveRecord's <tt>:joins</tt> and <tt>:include</tt>.
|
|
357
347
|
:order => 'products.name',
|
358
348
|
:per_page => 20)
|
359
349
|
|
360
|
-
Note that if we want to order initially by a column from a joined table we have to specify the
|
350
|
+
Note that if we want to order initially by a column from a joined table we have to specify the
|
351
|
+
table and the column name with the sql dot notation, that is, <tt>products.name</tt>
|
361
352
|
|
362
|
-
To show columns of joined tables in the view table, the ActiveRecord model class name has
|
353
|
+
To show columns of joined tables in the view table, the ActiveRecord model class name has
|
354
|
+
to be specified, that corresponds to the joined table:
|
363
355
|
|
364
356
|
<%= grid(@products_grid) do |g|
|
365
|
-
g.column :
|
357
|
+
g.column :name => 'Product Name', :attribute => 'name' do |product| # primary table
|
366
358
|
link_to(product.name, product_path(product))
|
367
359
|
end
|
368
360
|
|
369
|
-
g.column :
|
361
|
+
g.column :name => 'Category', :attribute => 'name', :model => Category |product| # joined table
|
370
362
|
product.category.name
|
371
363
|
end
|
372
364
|
%>
|
373
365
|
|
374
|
-
Please note that the blockless definition of the column only works with columns from the main table
|
366
|
+
Please note that the blockless definition of the column only works with columns from the main table
|
367
|
+
and it won't work with columns with <tt>:model</tt>
|
375
368
|
|
376
369
|
=== Joined associations referring to the same table
|
377
370
|
|
378
|
-
In case there are two joined associations both referring to the same table,
|
379
|
-
|
371
|
+
In case there are two joined associations both referring to the same table,
|
372
|
+
ActiveRecord constructs a query where
|
373
|
+
the second join provides an alias for the joined table. To enable WiceGrid to order and
|
374
|
+
filter by columns belonging to different associations
|
380
375
|
but originating from the same table, set <tt>:table_alias</tt> to this alias:
|
381
376
|
|
382
377
|
Model:
|
@@ -395,13 +390,13 @@ View:
|
|
395
390
|
|
396
391
|
<%= grid(@projects_grid, :show_filters => :always) do |g|
|
397
392
|
|
398
|
-
g.column :
|
393
|
+
g.column :name => 'Project Name', :attribute => 'name'
|
399
394
|
|
400
|
-
g.column :
|
395
|
+
g.column :name => 'Customer company', :model => 'Company', :attribute => 'name' do |task|
|
401
396
|
task.customer.name if task.customer
|
402
397
|
end
|
403
398
|
|
404
|
-
g.column :
|
399
|
+
g.column :name => 'Supplier company', :model => 'Company', :attribute => 'name', :table_alias => ' suppliers_projects' do |task|
|
405
400
|
task.supplier.name if task.supplier
|
406
401
|
end
|
407
402
|
|
@@ -410,10 +405,12 @@ View:
|
|
410
405
|
|
411
406
|
=== More than one grid on a page
|
412
407
|
|
413
|
-
It is possible to use more that one grid on a page, each with its own state.
|
408
|
+
It is possible to use more that one grid on a page, each with its own state.
|
409
|
+
To do so, you must specify the name of the grid in +initialize_grid+ using
|
414
410
|
parameter <tt>:name</tt>
|
415
411
|
|
416
|
-
The name serves as the base name for HTTP parameters, DOM IDs, etc, so it
|
412
|
+
The name serves as the base name for HTTP parameters, DOM IDs, etc, so it
|
413
|
+
is important that all grids on a page have different names. The default
|
417
414
|
name is 'grid'.
|
418
415
|
|
419
416
|
The name can only contain alphanumeric characters.
|
@@ -424,7 +421,7 @@ The name can only contain alphanumeric characters.
|
|
424
421
|
|
425
422
|
=== Custom Ordering
|
426
423
|
|
427
|
-
It is possible to change the way results are ordered injecting a
|
424
|
+
It is possible to change the way results are ordered injecting a chunk of SQL code, for example, use
|
428
425
|
<tt>ORDER BY INET_ATON(ip_address)</tt> instead of <tt>ORDER BY ip_address</tt>.
|
429
426
|
|
430
427
|
To do so, provide parameter <tt>:custom_order</tt> in the initialization of the grid with a hash where keys are fully qualified names
|
@@ -456,7 +453,8 @@ Values can also be Proc objects. The parameter supplied to such a Proc object is
|
|
456
453
|
|
457
454
|
=== Custom dropdown filters
|
458
455
|
|
459
|
-
It is possible to construct custom dropdown filters.
|
456
|
+
It is possible to construct custom dropdown filters.
|
457
|
+
Depending on the value of <tt>column</tt> parameter<tt>:custom_filter</tt> different
|
460
458
|
modes are available:
|
461
459
|
|
462
460
|
|
@@ -464,47 +462,53 @@ modes are available:
|
|
464
462
|
|
465
463
|
An array of two-element arrays or a hash are semantically identical ways of creating a custom filter.
|
466
464
|
|
467
|
-
Every first item of the two-element array is used for the label of the select option while the second
|
465
|
+
Every first item of the two-element array is used for the label of the select option while the second
|
466
|
+
element is the value of the select option. In case of a hash the keys become the labels
|
467
|
+
of the generated dropdown list, while the values will be values of options of the dropdown list:
|
468
468
|
|
469
|
-
g.column :
|
469
|
+
g.column :name => 'Status', :attribute => 'status',
|
470
470
|
:custom_filter => {'Development' => 'development', 'Testing' => 'testing', 'Production' => 'production'}
|
471
471
|
|
472
|
-
g.column :
|
472
|
+
g.column :name => 'Status', :attribute => 'status',
|
473
473
|
:custom_filter => [['Development', 'development'], ['Testing', 'testing'], ['Production', 'production']]
|
474
474
|
|
475
|
-
It is also possible to submit a array of strings or numbers, in this case every item will be used
|
475
|
+
It is also possible to submit a array of strings or numbers, in this case every item will be used
|
476
|
+
both as the value of the select option and as its label:
|
476
477
|
|
477
|
-
g.column :
|
478
|
+
g.column :name => 'Status', :attribute => 'status',
|
478
479
|
:custom_filter => ['development', 'testing', 'production']
|
479
480
|
|
480
481
|
|
481
482
|
==== :auto
|
482
483
|
|
483
|
-
<tt>:auto</tt> - a powerful option which populates the dropdown list with all unique values of
|
484
|
-
|
484
|
+
<tt>:auto</tt> - a powerful option which populates the dropdown list with all unique values of
|
485
|
+
the column specified by
|
486
|
+
<tt>:attribute</tt> and <tt>:model</tt>.
|
485
487
|
|
486
|
-
g.column :
|
488
|
+
g.column :name => 'Status', :attribute => 'status',
|
487
489
|
:custom_filter => ['development', 'testing', 'production']
|
488
490
|
|
489
|
-
Note that in the above example all names of all possible categories will appear even if they
|
490
|
-
|
491
|
+
Note that in the above example all names of all possible categories will appear even if they
|
492
|
+
don't appear in the current resultset.
|
493
|
+
To only show those which do appear in the resutset,
|
494
|
+
use an array of symbol messages (see section 'An array of symbols').
|
491
495
|
|
492
496
|
|
493
497
|
==== Custom filters and associations (joined tables)
|
494
498
|
|
495
|
-
In most cases custom fields are
|
499
|
+
In most cases custom fields are needed for one-to-many and many-to-many associations.
|
496
500
|
|
497
|
-
To correctly build a filter condition foreign keys have to be
|
501
|
+
To correctly build a filter condition foreign keys have to be used, not the actual values rendered in the column.
|
498
502
|
|
499
503
|
For example, if there is a column:
|
500
504
|
|
501
|
-
g.column :
|
505
|
+
g.column :name => 'Project Name', :attribute => 'name', :model => 'Project' do |task|
|
502
506
|
task.project.name if task.project
|
503
507
|
end
|
504
508
|
|
505
509
|
adding <tt>:custom_filter</tt> like this:
|
506
510
|
|
507
|
-
g.column :
|
511
|
+
g.column :name => 'Project Name', :attribute => 'name', :model => 'Project',
|
508
512
|
:custom_filter => Project.find(:all).map{|pr| [pr.name, pr.name]} do |task|
|
509
513
|
task.project.name if task.project
|
510
514
|
end
|
@@ -516,13 +520,13 @@ To use filter with foreign keys, we have to change the declaration of the column
|
|
516
520
|
<tt>tasks.project_id</tt>, and build the dropdown with foreign keys as values:
|
517
521
|
|
518
522
|
|
519
|
-
g.column :
|
523
|
+
g.column :name => 'Project Name', :attribute => 'tasks.project_id',
|
520
524
|
:custom_filter => Project.find(:all).map{|pr| [pr.id, pr.name]} do |task|
|
521
525
|
task.project.name if task.project
|
522
526
|
end
|
523
527
|
|
524
|
-
However, this will break the ordering of the column - the column will be ordered by the integer foreign key.
|
525
|
-
we can override the ordering using <tt>:custom_order</tt>:
|
528
|
+
However, this will break the ordering of the column - the column will be ordered by the integer foreign key.
|
529
|
+
To fix this, we can override the ordering using <tt>:custom_order</tt>:
|
526
530
|
|
527
531
|
@tasks_grid = initialize_grid(Task,
|
528
532
|
:include => :project,
|
@@ -535,17 +539,19 @@ we can override the ordering using <tt>:custom_order</tt>:
|
|
535
539
|
==== Any other symbol (method name) or an array of symbols (method names)
|
536
540
|
|
537
541
|
|
538
|
-
For one symbol (different from <tt>:auto</tt>) the dropdown list is populated by all
|
542
|
+
For one symbol (different from <tt>:auto</tt>) the dropdown list is populated by all
|
543
|
+
unique values returned by the method with this name
|
539
544
|
sent to <em>all</em> ActiveRecord objects throughout all pages.
|
540
545
|
|
541
|
-
The conditions set up by the user are ignored, that is, the records used are all those found on
|
546
|
+
The conditions set up by the user are ignored, that is, the records used are all those found on
|
547
|
+
all pages without any filters active.
|
542
548
|
|
543
549
|
For an array of symbols, the first method name is sent to the ActiveRecord
|
544
550
|
object if it responds to this method, the second method name is sent to the
|
545
551
|
returned value unless it is +nil+, and so on. In other words, a single symbol mode is the
|
546
552
|
same as an array of symbols where the array contains just one element.
|
547
553
|
|
548
|
-
g.column :
|
554
|
+
g.column :name => 'Version', :attribute => 'expected_version_id', :custom_filter => [:expected_version, :to_option] do |task|
|
549
555
|
task.expected_version.name if task.expected_version
|
550
556
|
end
|
551
557
|
|
@@ -556,11 +562,14 @@ There are two important differences from <tt>:auto</tt>:
|
|
556
562
|
2. Filtering by any option of such a custom filter will bring a non-empty list, unlike with <tt>:auto</tt>.
|
557
563
|
|
558
564
|
|
559
|
-
This mode has one major drawback - this mode requires an additional query
|
560
|
-
|
565
|
+
This mode has one major drawback - this mode requires an additional query
|
566
|
+
without +offset+ and +limit+ clauses to instantiate _all_
|
567
|
+
ActiveRecord objects, and performance-wise it brings all the advantages of pagination to nothing.
|
568
|
+
Thus, memory- and performance-wise this can be really bad for some queries and tables and should be used with care.
|
561
569
|
|
562
570
|
|
563
|
-
If the final method returns a atomic value like a string or an integer,
|
571
|
+
If the final method returns a atomic value like a string or an integer,
|
572
|
+
it is used for both the value and the label of the select option element:
|
564
573
|
|
565
574
|
<option value="returned value">returned value</option>
|
566
575
|
|
@@ -580,7 +589,8 @@ would do the trick:
|
|
580
589
|
|
581
590
|
<option value="id">name</option>
|
582
591
|
|
583
|
-
Alternatively, a hash with the single key-value pair can be used, where the key will be used for the label,
|
592
|
+
Alternatively, a hash with the single key-value pair can be used, where the key will be used for the label,
|
593
|
+
and the key - for the value:
|
584
594
|
|
585
595
|
def to_option
|
586
596
|
{name => id}
|
@@ -589,7 +599,8 @@ Alternatively, a hash with the single key-value pair can be used, where the key
|
|
589
599
|
|
590
600
|
==== Special treatment of values 'null' and 'not null'
|
591
601
|
|
592
|
-
Values 'null' and 'not null' in a generated custom filter are treated specially,
|
602
|
+
Values 'null' and 'not null' in a generated custom filter are treated specially,
|
603
|
+
as SQL +null+ statement and not as strings.
|
593
604
|
Value 'null' is transformed into SQL condition <tt>IS NULL</tt>, and 'not null' into <tt>IS NOT NULL</tt>
|
594
605
|
|
595
606
|
Thus, if in a filter defined by
|
@@ -601,11 +612,11 @@ values '1', '2' and 'No' are selected (in a multi-select mode), this will resul
|
|
601
612
|
|
602
613
|
==== Multiple selection
|
603
614
|
|
604
|
-
By default it is possible for any dropdown list to switch between single and multiple selection modes.
|
605
|
-
single selection use <tt>:allow_multiple_selection</tt>:
|
615
|
+
By default it is possible for any dropdown list to switch between single and multiple selection modes.
|
616
|
+
To only allow single selection use <tt>:allow_multiple_selection</tt>:
|
606
617
|
|
607
618
|
|
608
|
-
g.column :
|
619
|
+
g.column :name => 'Expected in version', :attribute => 'expected_version_id',
|
609
620
|
:custom_filter => [:expected_version, :to_option], :allow_multiple_selection => false do |task|
|
610
621
|
...
|
611
622
|
end
|
@@ -613,20 +624,21 @@ single selection use <tt>:allow_multiple_selection</tt>:
|
|
613
624
|
|
614
625
|
=== Defaults
|
615
626
|
|
616
|
-
Default values like can be changed in <tt>config/initializers/wice_grid_config.rb</tt
|
627
|
+
Default values like can be changed in <tt>config/initializers/wice_grid_config.rb</tt>.
|
617
628
|
|
629
|
+
=== Submit/Reset buttons
|
630
|
+
Instead of using default Submit and Reset icons you can use external HTML elements to trigger
|
631
|
+
these actions. Add a button or any other clickable HTML element with class
|
632
|
+
+wg-external-submit-button+ or +wg-external-reset-button+, and attribute +data-grid-name+
|
633
|
+
whose value is the name of the grid:
|
618
634
|
|
635
|
+
<button class="wg-external-submit-button" data-grid-name="grid">Submit</button>
|
636
|
+
<button class="wg-external-reset-button" data-grid-name="grid">Reset</button>
|
619
637
|
|
620
|
-
|
621
|
-
|
622
|
-
View helper +reset_grid_javascript+ returns javascript which resets the grid, clearing the state of filters.
|
623
|
-
This allows to create your own Submit and Reset buttons anywhere on the page with the help of +button_to_function+:
|
638
|
+
To hide the default icons use <tt>:hide_submit_button => true</tt> and
|
639
|
+
<tt>:hide_reset_button => true</tt> in the +grid+ helper.
|
624
640
|
|
625
|
-
<%= button_to_function "Submit", submit_grid_javascript(@grid) %>
|
626
|
-
<%= button_to_function "Reset", reset_grid_javascript(@grid) %>
|
627
641
|
|
628
|
-
To complement this feature there are two parameters in the +grid+ helper <tt>:hide_submit_button</tt> and <tt>:hide_reset_button</tt> which
|
629
|
-
hide default buttons in the grid if set to true.
|
630
642
|
|
631
643
|
|
632
644
|
=== Auto-reloading filters
|
@@ -640,18 +652,18 @@ Use option <tt>:auto_reload</tt> in the column definiton:
|
|
640
652
|
<%= grid(@tasks_grid, :show_filters => :always, :hide_submit_button => true) do |g|
|
641
653
|
|
642
654
|
# String
|
643
|
-
g.column :
|
655
|
+
g.column :name => 'Title', :attribute => 'title', :auto_reload => true
|
644
656
|
|
645
657
|
# Boolean
|
646
|
-
g.column :
|
658
|
+
g.column :name => 'Archived', :attribute => 'archived', :auto_reload => true
|
647
659
|
|
648
660
|
# Custom (dropdown)
|
649
|
-
g.column :
|
661
|
+
g.column :name => 'Status', :attribute => 'status_id', :custom_filter => Status.to_dropdown, :auto_reload => true do |task|
|
650
662
|
task.status.name if task.status
|
651
663
|
end
|
652
664
|
|
653
665
|
# Datetime
|
654
|
-
g.column :
|
666
|
+
g.column :name => 'Added', :attribute => 'created_at', :auto_reload => true, :helper_style => :calendar do |task|
|
655
667
|
task.created_at.to_s(:short)
|
656
668
|
end
|
657
669
|
|
@@ -661,38 +673,34 @@ To make this behavior default change constant +AUTO_RELOAD+ in the configuratio
|
|
661
673
|
|
662
674
|
=== Styling the grid
|
663
675
|
|
664
|
-
==== Predefined css classes used by the grid
|
665
|
-
|
666
|
-
+td+ tags are assigned two styles automatically - +sorted+ if the column is the one by which the grid is ordered,
|
667
|
-
and +active_filter+ if the column's filter is on.
|
668
|
-
|
669
|
-
Odd and even +tr+ tags are assigned styles +odd+ and +even+, correspondingly.
|
670
|
-
|
671
|
-
For other classes see <tt>wice_grid.css</tt>. Feel free to customize it according to your needs.
|
672
676
|
|
673
677
|
==== Adding classes and styles
|
674
678
|
|
675
|
-
The +grid+ helper accepts parameter <tt>:
|
679
|
+
The +grid+ helper accepts parameter <tt>:html</tt> which is a hash of HTML
|
676
680
|
attributes for the table tag.
|
677
681
|
|
678
|
-
Another +grid+ parameter is <tt>
|
682
|
+
Another +grid+ parameter is <tt>header_tr_html</tt> which is a hash of HTML attributes to
|
683
|
+
be added to the first +tr+ tag (or two first +tr+'s if the filter row is present).
|
679
684
|
|
680
|
-
<tt>:
|
685
|
+
<tt>:html</tt> is a parameter for the +column+ method setting HTML attributes of +td+ tags for a certain column.
|
681
686
|
|
682
687
|
==== Adding classes and styles dynamically
|
683
688
|
|
684
|
-
WiceGrid offers ways to dynamically add classes and styles to +TR+ and +TD+
|
689
|
+
WiceGrid offers ways to dynamically add classes and styles to +TR+ and +TD+
|
690
|
+
based on the current ActiveRecord instance.
|
685
691
|
|
686
692
|
|
687
693
|
For <tt><TD></tt>, let the +column+ return an array where the first item is the usual
|
688
|
-
string output whole the second is a hash of HTML attributes to be added for the
|
694
|
+
string output whole the second is a hash of HTML attributes to be added for the
|
695
|
+
<tt><td></tt> tag of the current cell:
|
689
696
|
|
690
697
|
g.column do |portal_application|
|
691
698
|
css_class = portal_application.public? ? 'public' : 'private'
|
692
699
|
[portal_application.name, {:class => css_class}]
|
693
700
|
end
|
694
701
|
|
695
|
-
For adding classes/styles to <tt><TR></tt> use special clause +row_attributes+ ,
|
702
|
+
For adding classes/styles to <tt><TR></tt> use special clause +row_attributes+ ,
|
703
|
+
similar to +column+, only returning a hash:
|
696
704
|
|
697
705
|
<%= grid(@versions_grid) do |g|
|
698
706
|
g.row_attributes do |version|
|
@@ -709,15 +717,14 @@ Naturally, there can be only one +row_attributes+ definition for a WiceGrid inst
|
|
709
717
|
|
710
718
|
Various classes do not overwrite each other, instead, they are concatenated.
|
711
719
|
|
712
|
-
WiceGrid icons are in directory <tt>public/images/icons/grid/</tt>.
|
713
|
-
|
714
720
|
|
715
721
|
=== Adding rows to the grid
|
716
722
|
|
717
|
-
It is possible to add your own handcrafted HTML after and/or before each grid row.
|
723
|
+
It is possible to add your own handcrafted HTML after and/or before each grid row.
|
724
|
+
This works similar to +row_attributes+, by adding blocks +after_row+, +before_row+, and +last_row+:
|
718
725
|
|
719
726
|
<%= grid(@tasks_grid) do |g|
|
720
|
-
g.before_row do |task|
|
727
|
+
g.before_row do |task, number_of_columns|
|
721
728
|
if task.active?
|
722
729
|
"<tr><td colspan=\"10\">Custom line for #{t.name}</td></tr>" # this would add a row
|
723
730
|
# before every active task row
|
@@ -726,7 +733,7 @@ It is possible to add your own handcrafted HTML after and/or before each grid ro
|
|
726
733
|
end
|
727
734
|
end
|
728
735
|
|
729
|
-
g.last_row do
|
736
|
+
g.last_row do |number_of_columns| # This row will always be added to the bottom of the grid
|
730
737
|
content_tag(:tr,
|
731
738
|
content_tag(:td,
|
732
739
|
'Last row',
|
@@ -737,15 +744,20 @@ It is possible to add your own handcrafted HTML after and/or before each grid ro
|
|
737
744
|
.......
|
738
745
|
end %>
|
739
746
|
|
740
|
-
It is up for the developer to return the correct HTML code, or
|
747
|
+
It is up for the developer to return the correct HTML code, or
|
748
|
+
return +nil+ if no row is needed for this record.
|
749
|
+
Naturally, there is only one +before_row+ definition and one +after_row+
|
750
|
+
definition for a WiceGrid instance.
|
741
751
|
|
742
|
-
|
752
|
+
The second variable injected into to <tt>before_row</tt> and <tt>after_row</tt> block, and the first parameter injected
|
753
|
+
into the <tt>last_row</tt> is the number of columns in the current grid.
|
743
754
|
|
744
755
|
=== Rendering a grid without records
|
745
756
|
|
746
|
-
If the grid does not contain any records to show, it is possible show some alternative view instead of
|
747
|
-
sets up the filters in such a way that the selection of
|
748
|
-
|
757
|
+
If the grid does not contain any records to show, it is possible show some alternative view instead of
|
758
|
+
an empty grid. Bear in mind that if the user sets up the filters in such a way that the selection of
|
759
|
+
records is empty, this will still render the grid and it will be possible to reset the grid clicking
|
760
|
+
on the Reset button. Thus, this only works if the initial number of records is 0.
|
749
761
|
|
750
762
|
<%= grid(@grid) do |g|
|
751
763
|
|
@@ -767,58 +779,9 @@ Or a partial:
|
|
767
779
|
g.blank_slate :partial => "partial_name"
|
768
780
|
|
769
781
|
|
770
|
-
=== Localization
|
771
|
-
|
772
|
-
Versions of WiceGrid newer than version 0.5 support localization via Rails I18n, however, without breaking
|
773
|
-
compatibility with pre-I18n versions of Rails (2.1.0 and older).
|
774
|
-
|
775
|
-
Running
|
776
|
-
|
777
|
-
./script/generate wice_grid_assets
|
778
|
-
|
779
|
-
will copy file <tt>wice_grid.yml</tt> to <tt>config/locales</tt>.
|
780
|
-
|
781
|
-
The current locale is taken from <tt>I18n.locale</tt>. The locale also propagates to the javascript calendar
|
782
|
-
widget (see <tt>Calendar.messagebundle</tt> in <tt>calendarview.js</tt> to add languages).
|
783
|
-
|
784
|
-
If the messages are not found, or I18n is missing, WiceGrid will fall back to the hardcoded messages in
|
785
|
-
<tt>config/initializers/wice_grid_config.rb</tt>.
|
786
|
-
|
787
|
-
Currently supported languages are English, Dutch, French, and Russian.
|
788
|
-
|
789
|
-
=== ERB mode
|
790
|
-
|
791
|
-
The view helper can function in two different modes. These are defined by its +erb_mode+ parameter.
|
792
|
-
By default (<tt>:erb_mode => false</tt>) the view helper is a simple helper surrounded by <tt><%=</tt> and <tt>%></tt>, like in all examples
|
793
|
-
above.
|
794
|
-
|
795
|
-
|
796
|
-
The second mode (<tt>:erb_mode => true</tt>) is called <em>ERB mode</em> and it allows to embed any ERB content inside blocks,
|
797
|
-
which is basically the style of the
|
798
|
-
<tt>form_for</tt> helper, only <tt>form_for</tt> takes one block, while inside the <tt>grid</tt> block there are other method calls taking
|
799
|
-
blocks as parameters:
|
800
|
-
|
801
|
-
<% grid(@countries_grid, :erb_mode => true) do |g| %>
|
802
|
-
|
803
|
-
<% g.column :column_name => 'Name', :attribute_name => 'name' do |country| %>
|
804
|
-
<b>Name: <%= link_to(country.name, country_path(country)) %></b>
|
805
|
-
<% end %>
|
806
|
-
|
807
|
-
<% g.column :column_name => 'Numeric Code', :attribute_name => 'numeric_code' do |country| %>
|
808
|
-
<i>Numeric Code: <%= country.numeric_code %></i>
|
809
|
-
<% end %>
|
810
|
-
|
811
|
-
<% end -%>
|
812
|
-
|
813
|
-
This mode can be usable if you like to have much HTML code inside cells.
|
814
|
-
|
815
|
-
Please remember that in this mode the helper opens with <tt><%</tt> instead of <tt><%=</tt>, similar to <tt>form_for</tt>.
|
816
|
-
|
817
|
-
The default value for <tt>:show_filters</tt> can be changed in <tt>config/initializers/wice_grid_config.rb</tt>.
|
818
|
-
|
819
782
|
=== Action Column
|
820
783
|
|
821
|
-
It is
|
784
|
+
It is possible to add a column with checkboxes for each record. This is useful for actions with multiple records,
|
822
785
|
for example, deleting selected records. Please note that +action_column+ only creates the checkboxes and the
|
823
786
|
'Select All' and 'Deselect All' buttons, and the form itself as well as processing the parameters should be
|
824
787
|
taken care of by the application code.
|
@@ -836,19 +799,22 @@ taken care of by the application code.
|
|
836
799
|
By default the name of the HTTP parameter follows pattern <tt>"#{grid_name}[#{param_name}][]"</tt>, thus
|
837
800
|
<tt>params[grid_name][param_name]</tt> will contain an array of object IDs.
|
838
801
|
|
839
|
-
|
802
|
+
WiceGrid is form-friendly: submitting grid in a form retains the state of the form.
|
803
|
+
|
840
804
|
|
841
805
|
|
842
806
|
=== Integration of the grid with other forms on page
|
843
807
|
|
844
|
-
Imagine that the user should be able to change the behavior of the grid using some other control
|
808
|
+
Imagine that the user should be able to change the behavior of the grid using some other control
|
809
|
+
on the page, and not a grid filter.
|
845
810
|
|
846
811
|
For example, on a page showing tasks,
|
847
812
|
change between 'Show active tasks' to 'Show archived tasks' using a dropdown box.
|
848
813
|
WiceGrid allows to keep the status of the grid with all the filtering and sorting
|
849
|
-
using helper +dump_filter_parameters_as_hidden_fields+ which takes a grid object and dumps
|
850
|
-
|
851
|
-
|
814
|
+
using helper +dump_filter_parameters_as_hidden_fields+ which takes a grid object and dumps
|
815
|
+
all current sorting and filtering parameters as
|
816
|
+
hidden fields. Just include <tt>dump_filter_parameters_as_hidden_fields(@grid)</tt> inside your form,
|
817
|
+
and the newly rendered grid will keep ordering and filtering.
|
852
818
|
|
853
819
|
<% form_tag('', :method => :get) do %>
|
854
820
|
<%= dump_filter_parameters_as_hidden_fields(@tasks_grid) %>
|
@@ -860,48 +826,30 @@ keep ordering and filtering.
|
|
860
826
|
|
861
827
|
=== Javascript Calendar for Date and DateTime Filters.
|
862
828
|
|
863
|
-
|
864
|
-
|
865
|
-
|
866
|
-
|
867
|
-
|
868
|
-
|
869
|
-
In the Prototype mode the plugin uses a forked[http://github.com/leikind/calendarview] version of Calendarview[http://github.com/jsmecham/calendarview]. It is bundled with the plugin and the generator task
|
870
|
-
+wice_grid_assets_prototype+ will install al necessary assets.
|
871
|
-
|
872
|
-
The jQuery version uses jQuery datepicker[http://jqueryui.com/demos/datepicker/]. Because this is part
|
873
|
-
of the standard jQuery codebase, it is not bundled together with the plugin, and it is the responsibility
|
874
|
-
of the programmer to include all necessary assets including localization files if the application is
|
875
|
-
multilingual.
|
876
|
-
|
877
|
-
It is always possible to fall back to simple dropdown lists that the standard date/datetime Rails helpers use.
|
878
|
-
|
879
|
-
JQUERY DATEPICKER IS ONLY USED FOR DATE FILTERS AT THE MOMENT. DATETIME FILTERS FALL BACK TO THE DEFAULT
|
880
|
-
RAILS DATE/DATETIME HELPERS.
|
829
|
+
WiceGrid uses jQuery datepicker[http://jqueryui.com/demos/datepicker/] for Date and DateTime filters
|
830
|
+
by default.
|
831
|
+
Because this is part of the standard jQuery codebase, it is not bundled together with the plugin,
|
832
|
+
and it is the responsibility of the programmer to include all necessary assets including
|
833
|
+
localization files if the application is multilingual.
|
881
834
|
|
882
835
|
|
883
|
-
|
884
|
-
|
836
|
+
jQuery datepicker does not have any time related controls, and when dealing with DateTime filters,
|
837
|
+
the time value is ignored.
|
885
838
|
|
886
|
-
|
839
|
+
Another option is standard Rails helpers. It's possible to change between the two styles of Date/DateTime
|
840
|
+
filters in <tt>config/initializers/wice_grid_config.rb</tt> using constant HELPER_STYLE, or set it on per-column basis:
|
887
841
|
|
888
|
-
g.column :
|
842
|
+
g.column :name => 'Due Date', :attribute => 'due_date', :helper_style => :calendar do |task|
|
889
843
|
task.due_date.to_s(:short) if task.due_date
|
890
844
|
end
|
891
845
|
|
892
|
-
g.column :
|
846
|
+
g.column :name => 'Updated', :attribute => 'updated_at', :helper_style => :standard do |task|
|
893
847
|
task.created_at.to_s(:short)
|
894
848
|
end
|
895
849
|
|
896
|
-
Constants +DATE_FORMAT+ and +DATETIME_FORMAT+ define the format of dates the user will see, as well as the
|
897
|
-
format of the string sent in a HTTP parameter.
|
898
|
-
|
899
|
-
You can change the constants in
|
900
|
-
<tt>config/initializers/wice_grid_config.rb</tt>. Doing so, make sure that lamdbas defined
|
901
|
-
in +DATETIME_PARSER+ and +DATE_PARSER+ return valid DateTime and Date objects. The format
|
902
|
-
by default is <tt>%Y-%m-%d</tt> for the Date and the date part of DateTime, and <tt>Time.zone.parse</tt>
|
903
|
-
and <tt>Date.parse</tt> handle it.
|
904
|
-
Make sure it stays so.
|
850
|
+
Constants +DATE_FORMAT+ and +DATETIME_FORMAT+ in the configuration file define the format of dates the user will see, as well as the
|
851
|
+
format of the string sent in a HTTP parameter. If you change the formats, make sure that lamdbas defined
|
852
|
+
in +DATETIME_PARSER+ and +DATE_PARSER+ return valid DateTime and Date objects.
|
905
853
|
|
906
854
|
jQuery +datepicker+ uses a different format flavor, therefore there is an additional constant
|
907
855
|
+DATE_FORMAT_JQUERY+. While +DATE_FORMAT_JQUERY+ is fed to +datepicker+, +DATE_FORMAT+ is still used
|
@@ -911,19 +859,19 @@ result in an identical date representation.
|
|
911
859
|
|
912
860
|
=== Show All Records
|
913
861
|
|
914
|
-
It is possible to switch to the All Records mode clicking on link "show all" in the bottom right corner.
|
915
|
-
with care. To turn this mode off for all grid instances,
|
916
|
-
<tt>config/initializers/wice_grid_config.rb</tt> to
|
862
|
+
It is possible to switch to the All Records mode clicking on link "show all" in the bottom right corner.
|
863
|
+
This functionality should be used with care. To turn this mode off for all grid instances,
|
864
|
+
change constant +ALLOW_SHOWING_ALL_QUERIES+ in <tt>config/initializers/wice_grid_config.rb</tt> to
|
917
865
|
+false+. To do so for a specific grid, use initializer parameter <tt>:allow_showing_all_records</tt>.
|
918
866
|
|
919
|
-
Configuration constant +START_SHOWING_WARNING_FROM+ sets the threshold number of all records after
|
920
|
-
link results in a javascript confirmation dialog.
|
867
|
+
Configuration constant +START_SHOWING_WARNING_FROM+ sets the threshold number of all records after
|
868
|
+
which clicking on the link results in a javascript confirmation dialog.
|
921
869
|
|
922
870
|
|
923
871
|
=== CSV Export
|
924
872
|
|
925
|
-
It is possible to export the data displayed on a grid to a CSV file. The dumped data is the current resultset
|
926
|
-
current filters and sorting applied, only without the pagination constraint (i.e. all pages).
|
873
|
+
It is possible to export the data displayed on a grid to a CSV file. The dumped data is the current resultset
|
874
|
+
with all the current filters and sorting applied, only without the pagination constraint (i.e. all pages).
|
927
875
|
|
928
876
|
To enable CSV export add parameters +enable_export_to_csv+ and +csv_file_name+ to the initialization of the grid:
|
929
877
|
|
@@ -934,34 +882,37 @@ To enable CSV export add parameters +enable_export_to_csv+ and +csv_file_name+ t
|
|
934
882
|
:csv_file_name => 'projects'
|
935
883
|
)
|
936
884
|
|
937
|
-
+csv_file_name+ is the name of the downloaded file. This parameter is optional, if it is missing, the name of
|
938
|
-
The export icon will appear at the bottom right corner of the grid.
|
885
|
+
+csv_file_name+ is the name of the downloaded file. This parameter is optional, if it is missing, the name of
|
886
|
+
the grid is used instead. The export icon will appear at the bottom right corner of the grid.
|
939
887
|
|
940
|
-
Next, each grid view helper should be placed in a partial of its own, requiring it from the master
|
941
|
-
HTML or ERB code in this partial except for the grid helper.
|
888
|
+
Next, each grid view helper should be placed in a partial of its own, requiring it from the master
|
889
|
+
template for the usual flow. There must be no HTML or ERB code in this partial except for the grid helper.
|
942
890
|
|
943
891
|
By convention the name of such a partial follows the following pattern:
|
944
892
|
|
945
893
|
_GRID_NAME_grid.html.erb
|
946
894
|
|
947
|
-
In other words, a grid named +tasks+ is expected to be found in a template called
|
895
|
+
In other words, a grid named +tasks+ is expected to be found in a template called
|
896
|
+
<tt>_tasks_grid.html.erb</tt> (remember that the default name of grids is '+grid+'.)
|
948
897
|
|
949
|
-
Next, method +export_grid_if_requested+ should be added to the end of each action
|
898
|
+
Next, method +export_grid_if_requested+ should be added to the end of each action
|
899
|
+
containing grids with enabled CSV export.
|
950
900
|
|
951
901
|
+export_grid_if_requested+ intercepts CSV export requests and evaluates the partial with the required grid helper.
|
952
902
|
|
953
|
-
The naming convention for grid partials can be easily overridden by supplying a hash parameter
|
954
|
-
where each key is the name of a grid, and the value is the name of
|
955
|
-
without '_' and extensions):
|
903
|
+
The naming convention for grid partials can be easily overridden by supplying a hash parameter
|
904
|
+
to +export_grid_if_requested+ where each key is the name of a grid, and the value is the name of
|
905
|
+
the template (like it is specified for +render+, i.e. without '_' and extensions):
|
956
906
|
|
957
907
|
|
958
908
|
export_grid_if_requested('g1' => 'tasks_grid', 'g2' => 'projects_grid')
|
959
909
|
|
960
|
-
If the request is not a CSV export request, +export_grid_if_requested+ does nothing and returns
|
961
|
-
the method returns +true+.
|
910
|
+
If the request is not a CSV export request, +export_grid_if_requested+ does nothing and returns
|
911
|
+
+false+, if it is a CSV export request, the method returns +true+.
|
962
912
|
|
963
913
|
|
964
|
-
If the action has no explicit +render+ call, it's OK to just place +export_grid_if_requested+
|
914
|
+
If the action has no explicit +render+ call, it's OK to just place +export_grid_if_requested+
|
915
|
+
as the last line of the action:
|
965
916
|
|
966
917
|
def index
|
967
918
|
|
@@ -1017,37 +968,52 @@ parameters +in_csv+ and +in_html+ to include one of them to html output only, t
|
|
1017
968
|
|
1018
969
|
|
1019
970
|
# html version
|
1020
|
-
g.column :
|
971
|
+
g.column :name => 'Title', :attribute => 'title', :in_csv => false do |task|
|
1021
972
|
link_to('Edit', edit_task_path(task.title))
|
1022
973
|
end
|
1023
974
|
# plain text version
|
1024
|
-
g.column :
|
975
|
+
g.column :name => 'Title', :in_html => false do |task|
|
1025
976
|
task.title
|
1026
977
|
end
|
1027
978
|
|
1028
|
-
The default field separator in generated CSV is a comma, but it's possible to override
|
1029
|
-
string to the <tt>:enable_export_to_csv</tt> parameter:
|
979
|
+
The default field separator in generated CSV is a comma, but it's possible to override it:
|
1030
980
|
|
1031
981
|
@products_grid = initialize_grid(Product,
|
1032
|
-
:enable_export_to_csv =>
|
982
|
+
:enable_export_to_csv => true,
|
983
|
+
:csv_field_separator => ';',
|
1033
984
|
:csv_file_name => 'products')
|
1034
985
|
|
986
|
+
If you need an external CSV export button , add class +wg-external-csv-export-button+
|
987
|
+
to any clickable element on page and set its attribute +data-grid-name+ to the name of
|
988
|
+
the grid:
|
989
|
+
|
990
|
+
<button class="wg-external-csv-export-button" data-grid-name="grid">Export To CSV</button>
|
991
|
+
|
992
|
+
If you need to disable the default export icon in the grid, add
|
993
|
+
<tt>:hide_csv_button => true</tt> to the +grid+ helper.
|
1035
994
|
|
1036
995
|
=== Detached Filters
|
1037
996
|
|
1038
|
-
It is possible to detach filters and place them anywhere on the page.
|
997
|
+
It is possible to detach filters and place them anywhere on the page.
|
998
|
+
To do so, use parameter <tt>:detach_with_id</tt> for a column whose filter needs to
|
999
|
+
be detached, with an arbitrary string or a symbol value which will be used
|
1000
|
+
later to identify the filter. As soon as there is one column with
|
1001
|
+
<tt>:detach_with_id</tt>, the behavior of the +grid+ helper changes - it
|
1002
|
+
becomes an <i>initializer</i> of the grid and doesn't output any HTML code.
|
1003
|
+
To render the grid, use <tt>grid</tt> for the second time without the block.
|
1004
|
+
To render a detached output filter, use helper <tt>grid_filter(grid_object, detached_filter_key)</tt>:
|
1039
1005
|
|
1040
1006
|
<%= grid(@tasks_grid, :show_filters => :always) do |g|
|
1041
1007
|
|
1042
|
-
g.column :
|
1008
|
+
g.column :name => 'Title', :attribute => 'title', :detach_with_id => :title_filter do |task|
|
1043
1009
|
link_to('Edit', edit_task_path(task.title))
|
1044
1010
|
end
|
1045
1011
|
|
1046
|
-
g.column :
|
1012
|
+
g.column :name => 'Archived', :attribute => 'archived', :detach_with_id => :archived_filter do |task|
|
1047
1013
|
task.archived? ? 'Yes' : 'No'
|
1048
1014
|
end
|
1049
1015
|
|
1050
|
-
g.column :
|
1016
|
+
g.column :name => 'Added', :attribute => 'created_at', :detach_with_id => :created_at_filter do |task|
|
1051
1017
|
task.created_at.to_s(:short)
|
1052
1018
|
end
|
1053
1019
|
|
@@ -1065,42 +1031,40 @@ end -%>
|
|
1065
1031
|
<% # Rendering the grid body %>
|
1066
1032
|
<%= grid(@tasks_grid) %>
|
1067
1033
|
|
1068
|
-
It is important that the grid initializer goes first, the order of +grid_filter+ and
|
1034
|
+
It is important that the grid initializer goes first, the order of +grid_filter+ and
|
1035
|
+
the second call to +grid+ is of no importance.
|
1069
1036
|
|
1070
|
-
Using custom submit and reset buttons together with <tt>:hide_submit_button => true</tt>
|
1037
|
+
Using custom submit and reset buttons together with <tt>:hide_submit_button => true</tt>
|
1038
|
+
and <tt>:hide_reset_button => true</tt>
|
1071
1039
|
allows to completely get rid
|
1072
1040
|
of the default filter row and the default icons (see section 'Submit/Reset Buttons').
|
1073
1041
|
|
1074
|
-
For CSV export will continue functioning, just make sure the first call to +grid+
|
1075
|
-
is
|
1042
|
+
For CSV export will continue functioning, just make sure the first call to +grid+
|
1043
|
+
is still in the template of its own and
|
1044
|
+
is inside of <tt><%= %></tt>, because when CSV is requested, the first +grid+ works
|
1045
|
+
in the old fashioned way producing CSV formatted output.
|
1076
1046
|
|
1077
|
-
|
1078
|
-
|
1079
|
-
|
1080
|
-
|
1047
|
+
If a column was declared with <tt>:detach_with_id</tt>, but never output with +grid_filter+,
|
1048
|
+
filtering the grid in development mode will result
|
1049
|
+
in an warning javascript message and the missing filter will be ignored.
|
1050
|
+
There is no such message in production.
|
1081
1051
|
|
1082
1052
|
<tt>grid</tt> parameter <tt>:show_filter</tt> must not be set to <tt>:no</tt> for detached filters to work.
|
1083
1053
|
|
1084
1054
|
==== How Does It Work? (For the interested)
|
1085
1055
|
|
1086
|
-
When there is at least one column with <tt>:detach_with_id</tt>, the generated HTML code is
|
1056
|
+
When there is at least one column with <tt>:detach_with_id</tt>, the generated HTML code is
|
1057
|
+
stored in a buffer, code for detached filters is stored
|
1087
1058
|
in buffers of their own identified by the given IDs, and nothing is returned to the view.
|
1088
1059
|
When the helper is called for the second time, the buffer outputs its content.
|
1089
1060
|
In a similar fashion, the +grid_filter+ helper outputs buffers for filters.
|
1090
1061
|
|
1091
|
-
=== Compatibility with Rails Asset Caching
|
1092
|
-
|
1093
|
-
Helpers +names_of_wice_grid_stylesheets+ and +names_of_wice_grid_javascripts+ return names of stylesheet and javascript files and can be used with
|
1094
|
-
+stylesheet_link_tag+ and +javascript_include_tag+ with <tt>:cache => true</tt>.
|
1095
|
-
Using this trick you have to deal with the parameters correctly, mind that Prototype has to be loaded before WiceGrid javascripts:
|
1096
|
-
|
1097
|
-
<%= stylesheet_link_tag *(['core', 'modalbox'] + names_of_wice_grid_stylesheets + [ {:cache => true}]) %>
|
1098
|
-
<%= javascript_include_tag *([:defaults] + names_of_wice_grid_javascripts + [ 'ui', 'swfobject', {:cache => true}]) %>
|
1099
1062
|
|
1100
1063
|
|
1101
1064
|
=== Access to Records From Outside The Grid
|
1102
1065
|
|
1103
|
-
There are two ways you can access the records outside the grid - using methods of the WiceGrid
|
1066
|
+
There are two ways you can access the records outside the grid - using methods of the WiceGrid
|
1067
|
+
object and using callbacks.
|
1104
1068
|
|
1105
1069
|
==== Accessing Records Via The WiceGrid Object
|
1106
1070
|
|
@@ -1129,8 +1093,10 @@ Method +all_pages_records+ returns a list of objects browsable through all pages
|
|
1129
1093
|
Mind that this helper results in an additional SQL query.
|
1130
1094
|
|
1131
1095
|
|
1132
|
-
Because of the current implementation of WiceGrid these helpers work only after the declaration
|
1133
|
-
|
1096
|
+
Because of the current implementation of WiceGrid these helpers work only after the declaration
|
1097
|
+
of the grid in the view.
|
1098
|
+
This is due to the lazy nature of WiceGrid - the actual call to the database is made during
|
1099
|
+
the execution of
|
1134
1100
|
the +grid+ helper, because to build the correct query columns declarations are required.
|
1135
1101
|
|
1136
1102
|
==== Accessing Records Via Callbacks
|