Fact: People like to click on stuff. A lot. Have you ever played that bubble wrap game where it goes “pop, pop, pop”? That’s a newsy application if I ever saw one — not really. But people do like to be in control.

One of my mantras. Why must journalists designate only one story path from beginning to end? Why not give some initial guidance, and then let the user navigate? We can put the user back in control via interactivity, but often, it requires a lot of time and technical know-how.

If, for example, you have an HTML table, you could just post it on your website.

But, wouldn’t it be so much better if it could be automatically sortable, so the user could determine the order of what they see by an attribute THEY care about? And wouldn’t it be great if they could search for a certain name they wanted to see the record for? And for the heck of it, wouldn’t it be great if that table could be automatically paginated, so I could have 500 records but they wouldn’t go on and on forever on one page? Yeah, it would, and it’s not that hard, thanks to…*drum roll, please* a jQuery plugin called DataTables.

DT (as I call it for short) and I became acquainted while I was over at the Los Angeles Times, and it showed up on most of my pieces. It’s a plugin that has its own syntax (language), but meshes very nicely with Javascript and jQuery. If you haven’t checked out Javascript and jQuery, you should.

I know images of code are hard to copy, and after the rush of NICAR, I’ll put these in as code blocks that you can copy and paste.  But you can get a copyable overall structure from the source on my implementation of this for the LAT’s redevelopment app.  Just go to http://projects.latimes.com/redevelopment, click on the menu item in your browser to “View Source”, and search for “DataTable” to find the right spot.

A basic walkthrough of the implementation is here. If you want to push it further, you should check out the well-done DataTables documentation.

First, get an overview from slides I presented on this at NICAR Lightning Talks 2011 in Raleigh in February 2011.

Five main steps we need to follow.

  1. Create a well-formatted HTML table. You’ll need to declare a separate <thead> and <tbody>, make sure all your tags match, and have an idea of what type of data is in each cell, so you can tell the computer how to sort.  If it’s words, you’re looking at text.  Numbers like “17”? Straight numbers.  Numbers like “1,017”?  Formatted numbers, because that comma is sticking in there.  Checkboxes?  That’s a special case you’ll need to deal with.  Your product should look something like this picture.

  2. Include the proper Javascript files. To enable interactivity on this page, include the three lines below.  Replace the /path/to/js with the appropriate path to where you’re storing these files.  The first one includes jQuery, a library that makes it easier to use Javascript, the backbone of non-Flash Web interactivity.  The second is jQuery UI.  It can do a lot of cool things, but here, DataTables will automatically use it to make our search box look pretty, and automatically select records that the computer thinks the user is searching for.  The third line includes the actual DataTables library, which has the actual code that allows us to *almost automatically* paginate our table and make it searchable and sortable.
  3. Make your HTML table pretty. While you may have already designated CSS for your basic HTML table, there are probably some other adjustments you want to make.  A sample setup that I’ve used is here.  There are special classes that designate the placement of the pagination under the table, the filter where people can type what they’re looking for, info which describes the filter.  Full options are detailed in the DataTables documentations, but this works like any CSS doc — some of the class names are just extra long, since they’re all preceded with”dataTables”.  Adding padding to these various elements is going to be your friend here.



  4. Create a custom sort, if you need it. Remember how way back at the beginning we talked about determining what types of data you have.  If your numbers include some sort of formatting, you should copy the code below into your document.  That’ll allow numbers to sort but ignore commas, or dollar signs or other symbols that make sense to humans but not computers.  If you have a data type that is not text, straight numbers nor formatted numbers (like a checkbox that either is checked or not), use this as a model to write your own.  Basically, you’re telling the computer what to ignore, than having it compare each record with another record.  If one is greater than the other (you tell it what greater means), it’ll get sorted higher.  Several custom sorts are copy/pastable from the DataTables site, so it’s worth checking there if you’re thinking about creating one from scratch.
  5. Customize how DataTables works with your table. Finally, we have to put all the pieces together.  This giant Javascript function goes under document.ready, which means it runs when the page is loaded.  We use jQuery to tell the function what <div> to apply the DataTable to.  Then, we customize that DataTable. There’s tons of options, which you can –again — find in the docs, but here are some I used a bunch.
  • Length change varies the number of records if true.
  • bAutoWidth adjusts column widths if true, which can cause some jumping around.
  • If your lengthchange is false, you need to tell the computer how many rows it should display at once.
  • You can choose between various pagination types, I like one that shows you as many pages available as possible.  There’s one that just shows current page, next and previous, which some might prefer.
  • The sDom parameter allows you to use some shortcuts to refer to parts of the table, and then insert padding around them.
  • oLanguage is where you specify the infotext that describes the filter box, where people type in what they’re looking for.
  • aoColumns allows you to specify widths for each column (if bAutoWidth is false), and what type of sorting the column should use, and if clicking on the table’s header allows you to sort in just one direction (like here), or more than one.  So, putting [“asc”, “desc”] next to asSorting means on first click of the header, info sorts in ascending order, click again and it reverses.  Click again, and it goes back to the first direction.  But if you don’t put “desc” in there, it’s not possible to sort in descending order.

And that’s all folks!  This is just a quick demo of the tip of the iceberg, going into the docs, trying the examples and messing with the code is the best way to learn.  But no database backend, Python or Ruby required.  You probably don’t want to use this on datasets with more than 1,000 records though.  All the records are being intially loaded, and then re-formatted.  Your browser/server will choke if you do that with too much data. And while it’s formatting your data, you may want to hide your table behind a loading div. Then, at the end of the document.ready function, just add a line hiding that div. $(‘#loading’).hide();

Have fun, and feel free to contact me if you have any questions!