TableSortable
TableSortable is a Rails complementation of The tableSorter jQuery plugin.
The tableSorter jQuery plugin is an excellent tool for filtering and sorting tables. When dealing with lots of rows, we usually want to split the table into multiple pages. tableSorter has a nifty widget for that, which requires using mottie's fork of tableSorter.
Usually this is a scenario where we don't want to send our entire set of records to the front end, which consequently means that the front end no longer knows the entire set of records to filter and sort through. This requires our server to handle all that stuff, plus the pagination of the results.
That's where TableSortable comes in!
TableSortable will handle all the backend filtering, sorting and pagination for you.
NOTICE: This gem is in very early stages of development, and is not yet fully documented. Any input will be more than welcome.
Installation
Add this line to your application's Gemfile:
gem 'table_sortable'
Then run bundle install
and you're ready to start
You should also probably be using jquery-tablesorter.
For information regarding integration or tableSorter into your Rails project,
please see the jQuery tablesorter plugin for Rails page.
Usage
First, we need to setup our controller.
Let's say we have our users controller. Let's include TableSortable so that we can use its methods.
#controllers/users_controller.rb
class UsersController < ApplicationController
include TableSortable
Next, let's define our columns.
#controllers/users_controller.rb
class UsersController < ApplicationController
include TableSortable
define_colunns :first_name, :last_name, :email, :created_at
That's the basic setup of columns. For more configuration options, please see advanced configuration.
Now we need to make sure our index
action filters, sorts and paginates the records.
We can do that using the filter_and_sort
method.
#controllers/users_controller.rb
def index
@users = filter_and_sort(User.all)
respond_to do |format|
format.html {}
format.json {render layout: false}
end
end
In our view we can use TableSortable's view helpers to render our table.
#views/users/index.html.erb
<div id="usersPager"><%= table_sortable_pager %></div>
<table id="usersTable" data-query="<%= users_path %>">
<thead>
<tr>
<%= table_sortable_headers %>
</tr>
</thead>
</table>
Let's say we have a tableSorter table which poll's the database for data. Here's a simple configuration example for that:
var table = $('#usersTable');
table.tablesorter({
widgets: ['filter', 'pager'],
widgetOptions: {
// show 10 records at a time
pager_size: 10,
// Poll our users_index_path.
// A better practice would be to use the table's
// data-query attribute instead, but more on that later)
pager_ajaxUrl: table.data('query') + '?pagesize={size}&page={page}&{filterList:fcol}&{sortList:scol}',
// Parse the incoming result
pager_ajaxProcessing: function (data) {
if (data && data.hasOwnProperty('rows')) {
// Update the pager output
this.pager_output = data.pager_output;
// return total records, the rows HTML data,
// and the headers information.
return [data.total, $(data.rows), data.headers];
}
}
}
});
For full documentation regarding the usage of tableSorter please go here for the very popular fork by mottie, or here for the original version of the plugin.
Now, the results fetched from the server would be filtered, sorter and paginated by TableSortable.
Of course there are many more configuration options that make TableSortable flexible and adaptable. For those, please see advanced configuration
Advanced Configuration
Coming soon...
View Helpers
Coming soon...
Development
After checking out the repo, run bin/setup
to install dependencies. Then, run rake test
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/odedd/table_sortable. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
License
The gem is available as open source under the terms of the MIT License.
Code of Conduct
Everyone interacting in the TableSortable project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.