- Sorting, filtering, and pagination are inter-related
Why aren’t we all using client-side sorting? That’s easy to implement! Oh,
wait, that’s only for the records that were returned to the screen. And if
you’ve sorted or filtered, it’s OK if clicking for the second page of results
resets your end user’s intentions, right? Nope.
- Pagination is already a public problem in the Rails space
This project will look to integrate with other plugins in this space rather
than offering an alternative implementation.
- Finders in the model are the place for complex queries
This project’s philosophy is that’s where complex queries lead to the overall
highest quality of testing.
- Easy things should be easy…
In many cases, a filter will just be operating on a couple of important fields
on a model. In these cases, the filter itself could be made capable of
generating ActiveRecord-ready conditions that can be passed directly to a
finder for direct use.
- Difficult things should be possible
Sometimes, things get pretty hairy in those finders. For times when the
filter’s AR-ready conditions cannot be reliable, the filter should still
provide an expressive options hash which the finder code can inspect before
ultimately issuing a query. This options hash should include all relevant
information for sorting and pagination as well, to keep the method signatures
as simple as possible.
data_table is being used in production for some of the basic use cases.
I encourage use of data_table and am capable of active support.
There is a full test suite, but I’m sure rcov will say it needs plenty of
help.
Right now, only AJAX mode is well supported. I plan on supporting “standard
mode” (a.k.a. simple form submission) in the immediate future. Eventually, I
would like front end to be skinnable.
Define a filter in your controller, like so:
data_table(:cars) do |table|
table.filter_spec do |f|
f.element(:color) do |e|
e.default "All"
e.option "Blue", 'blue'
e.option "Green", 'green'
end
end
end
You can get an array of filter conditions ready to pass along to ActiveRecord
(from conditions_for). You can get an options hash that contains
all the information a more complex query might need to reflect the user’s
sorting, filtering, and pagination selections (from options_for).
You’ll probably have to do a little inspection of pagination parameters to get
the query that you want.
You can also use multiple data_tables per page, without having to worry about
all the different parameters flying around.
filter_form(:cars)
This fellow recognizes what, if any, request parameters have any bearing on
the user’s sorting/filtering/pagination desires, combines that with your
instructions about whether to use AJAX or non-AJAX modes, what remote
callbacks to use, what external parameters need to be respected, etc. and
generates a form that will seamlessly work with the controller to aid in query
formation.
sort_header(:cars)
This fellow knows which sorting scheme has been selected, knows of preferred
sort orders for other sorts that aren’t being used at the moment, and
communicates with the filter so that a user has a seamless experience when
going back and forth between sorting and filtering in AJAX or non-AJAX modes.
pagination_for(@cars, :cars)
This will call a will_paginate view helper that uses a special
DataTable::LinkRenderer which can handle Ajax-ified requests to
fetch different pages of your current dataset. It also passes all options
through to will_paginate, and you can just as easily use your own LinkRenderer
with this use case.
The following links should give you more information about current initiatives
for each functionality area.