Use of jQuery datatable module in Views
A great way to display and manage large lists of items
By: Bruce Bahlmann - Contributing Author (your
feedback
is important to us!)
In rails development, or any other development for that matter, we are often
faced with providing a list of database items for the user to select from
(pick list). These pick lists provide a convenient way for users to quickly
edit or display item details so as to either familiarize themselves with the
data or to make modifications to it. This same listing is often shown as
result of a user adding or deleting an item in the list.
Rails provides a convenient way to generate this list initially -
essentially, the "index.html.erb" view displays a list of items from a
database call similar to the image below.
While this works ok for small lists, as the list gets larger, user
requirements for this view change. For example, they want to sort the
entries, search for a particular entry or for entries that contain some
common entry. At this point, the simple view above becomes grossly
inadequate. As a developer, you are then faced with increasing requirements
on this view, but manipulating this view gets complicated very quickly.
Rather than writing your own custom list view, jQuery has a great tool that
makes this simple. The rest of this posting is all about how you can
implement this module - which is easy once you know how (lets just say the
help docs don't measure up).
You can obtain the most current version of this module from the following
site:
http://www.datatables.net
Alternatively,
you can download the version of this I used just in case this person's site
becomes unavailable.
jquery-DataTables-1.7.6.zipInstalling this jquery module
requires several steps, but to a rails developer (beginner or experienced),
it is easy to miss something so I've tried to keep this simple. Opening up
the zip, you will see the following files:
First, install the following files in these locations (rails locations are in
bold):
public/javascripts
jquery.dataTables.js
public/stylesheets
demo_page.css
demo_table.css
public/images
back_disabled.jpg
back_enabled.jpg
forward_disabled.jpg
forward_enabled.jpg
sort_asc_disabled.png
sort_asc.png
sort_both.png
sort_desc_disabled.png
sort_desc.png
sorting icons.psd
Second, configure your rails application
Configuration happens in two places (application style sheet and the desired
view containing the list you want to use the jQuery mod).
In the application style sheet, rather than hard coding this resource to load
every time, you can make the load only happen when a user accesses a specific
page which requires this resource. To do this you need to use the yield feature
after you load defaults (which contain the jQuery resources). NOTE: Making
changes to the file below does require you to restart the rails server to apply
these settings.
[app/views/layouts/application.html.erb]
<head>
<%= javascript_include_tag :defaults %>
<% if content_for?(:head_include) %>
<%= yield(:head_include) %>
<% end %>
<% if content_for?(:javascript) %>
<script type="text/javascript" charset="utf-8">
<%= yield(:javascript) %>
</script>
<% end %>
</head>
Third, configure the index page (page with table of data that you want to add datatable
capability to)
At that top of this file, add the required dataTable resources and jQuery
configuration (to properly handshake with the application style sheet yield
command described previously. Place these atop the file, just to keep it simple.
Using the "yield" command is a great way to keep the style sheet clean yet
allow individual view pages the capability to display complex content.
[views/posts/index.html.erb]
<% content_for :head_include do %>
<%= stylesheet_link_tag "demo_page" %>
<%= stylesheet_link_tag "demo_table" %>
<%= javascript_include_tag "jquery.dataTables" %>
<% end %>
<% content_for :javascript do %>
$(document).ready(function() {
$('#example').dataTable();
});
<% end %>
Finally, you need to tie the page's table definition in with how dataTable is
expecting to leverage the jQuery functionality. To do this your table has to be
defined in the following way:
[views/posts/index.html.erb]
<table cellpadding="0" cellspacing="0" border="0" class="display"
id="example">
<thead>
<tr><th></th>...</tr>
</thead>
<tbody>
<tr><td></td>...</tr>
</tbody>
</table>
Once you have all that hooked up, displaying the page should produce
something like the following. Notice the nice individual sort features on
each of the columns, ability to limit list to so may entries, as well as a
search (pretty sweet, huh?). The style and various features can be easily
modified (as well as the initial page load state of the tool), so all the convenience is there - beats writing this all from
scratch. There are other options, like obtaining a CSV, showing results as a pdf, etc. These are available as additional features but not covered here.
Please refer to the module's website or help documentation for how to
implement these.
Can Birds-Eye.Net help you or your Company?
Receive your Birds-Eye.Net articles and white
papers hot off
the presses by adding our RSS feed to your reader.
|
|