Wednesday 22nd October, 2014

Search result highlighting

DataTables' built in search features provide the ability for the end user to very quickly search the data that is contained in a table, filtering the results down into just the relevant results for what they are looking for. However, the user still needs to scan the results in order to locate the specific data they search for. Often this will not be an arduous process for the user, but in complex tables it might take them a few seconds - seconds that we can spare them by highlighting the search term in the result set!

Bartek Szopka has written a jQuery plug-in for highlighting text in any given jQuery collection of nodes which is perfect for our highlighting needs. This blog post details how the highlighting plug-in can be integrated very easily with DataTables, and ultimately creating a reusable feature plug-in for DataTables that can be used on any table very easily.

An example table using this feature plug-in is shown below - an initial search term has been entered to immediately show the results, and as you alter the search term, the highlighting will automatically update.

Name	Position	Office	Age	Start date	Salary
Tiger Nixon	System Architect	Edinburgh	61	2011-04-25	$320,800
Garrett Winters	Accountant	Tokyo	63	2011-07-25	$170,750
Ashton Cox	Junior Technical Author	San Francisco	66	2009-01-12	$86,000
Cedric Kelly	Senior Javascript Developer	Edinburgh	22	2012-03-29	$433,060
Airi Satou	Accountant	Tokyo	33	2008-11-28	$162,700
Brielle Williamson	Integration Specialist	New York	61	2012-12-02	$372,000
Herrod Chandler	Sales Assistant	San Francisco	59	2012-08-06	$137,500
Rhona Davidson	Integration Specialist	Tokyo	55	2010-10-14	$327,900
Colleen Hurst	Javascript Developer	San Francisco	39	2009-09-15	$205,500
Sonya Frost	Software Engineer	Edinburgh	23	2008-12-13	$103,600
Jena Gaines	Office Manager	London	30	2008-12-19	$90,560
Quinn Flynn	Support Lead	Edinburgh	22	2013-03-03	$342,000
Charde Marshall	Regional Director	San Francisco	36	2008-10-16	$470,600
Haley Kennedy	Senior Marketing Designer	London	43	2012-12-18	$313,500
Tatyana Fitzpatrick	Regional Director	London	19	2010-03-17	$385,750
Michael Silva	Marketing Designer	London	66	2012-11-27	$198,500
Paul Byrd	Chief Financial Officer (CFO)	New York	64	2010-06-09	$725,000
Gloria Little	Systems Administrator	New York	59	2009-04-10	$237,500
Bradley Greer	Software Engineer	London	41	2012-10-13	$132,000
Dai Rios	Personnel Lead	Edinburgh	35	2012-09-26	$217,500
Jenette Caldwell	Development Lead	New York	30	2011-09-03	$345,000
Yuri Berry	Chief Marketing Officer (CMO)	New York	40	2009-06-25	$675,000
Caesar Vance	Pre-Sales Support	New York	21	2011-12-12	$106,450
Doris Wilder	Sales Assistant	Sydney	23	2010-09-20	$85,600
Angelica Ramos	Chief Executive Officer (CEO)	London	47	2009-10-09	$1,200,000
Gavin Joyce	Developer	Edinburgh	42	2010-12-22	$92,575
Jennifer Chang	Regional Director	Singapore	28	2010-11-14	$357,650
Brenden Wagner	Software Engineer	San Francisco	28	2011-06-07	$206,850
Fiona Green	Chief Operating Officer (COO)	San Francisco	48	2010-03-11	$850,000
Shou Itou	Regional Marketing	Tokyo	20	2011-08-14	$163,000
Michelle House	Integration Specialist	Sydney	37	2011-06-02	$95,400
Suki Burks	Developer	London	53	2009-10-22	$114,500
Prescott Bartlett	Technical Author	London	27	2011-05-07	$145,000
Gavin Cortez	Team Leader	San Francisco	22	2008-10-26	$235,500
Martena Mccray	Post-Sales support	Edinburgh	46	2011-03-09	$324,050
Unity Butler	Marketing Designer	San Francisco	47	2009-12-09	$85,675
Howard Hatfield	Office Manager	San Francisco	51	2008-12-16	$164,500
Hope Fuentes	Secretary	San Francisco	41	2010-02-12	$109,850
Vivian Harrell	Financial Controller	San Francisco	62	2009-02-14	$452,500
Timothy Mooney	Office Manager	London	37	2008-12-11	$136,200
Jackson Bradshaw	Director	New York	65	2008-09-26	$645,750
Olivia Liang	Support Engineer	Singapore	64	2011-02-03	$234,500
Bruno Nash	Software Engineer	London	38	2011-05-03	$163,500
Sakura Yamamoto	Support Engineer	Tokyo	37	2009-08-19	$139,575
Thor Walton	Developer	New York	61	2013-08-11	$98,540
Finn Camacho	Support Engineer	San Francisco	47	2009-07-07	$87,500
Serge Baldwin	Data Coordinator	Singapore	64	2012-04-09	$138,575
Zenaida Frank	Software Engineer	New York	63	2010-01-04	$125,250
Zorita Serrano	Software Engineer	San Francisco	56	2012-06-01	$115,000
Jennifer Acosta	Junior Javascript Developer	Edinburgh	43	2013-02-01	$75,650
Cara Stevens	Sales Assistant	New York	46	2011-12-06	$145,600
Hermione Butler	Regional Director	London	47	2011-03-21	$356,250
Lael Greer	Systems Administrator	London	21	2009-02-27	$103,500
Jonas Alexander	Developer	San Francisco	30	2010-07-14	$86,500
Shad Decker	Regional Director	Edinburgh	51	2008-11-13	$183,000
Michael Bruce	Javascript Developer	Singapore	29	2011-06-27	$183,000
Donna Snider	Customer Support	New York	27	2011-01-25	$112,000
Name	Position	Office	Age	Start date	Salary

Simple integration

The jQuery Highlight plug-in's basic operation is very simple - there are two methods:

$().highlight() - Highlight a search term
$().unhighlight() - Remove existing highlights

Only a couple of DataTables API methods and a single event are required to create an almost complete integration:

draw - When the table is redrawn this event will trigger and we can perform the highlighting required
search() - Get the search term
table().body() - Got the table's tbody element.

Using this we can construct:

$(document).ready( function () {
    var table = $('#myTable').DataTable();

    table.on( 'draw', function () {
        var body = $( table.table().body() );

        body.unhighlight();
        body.highlight( table.search() );   
    } );
} );

In the above code:

Line 2: Create a DataTable
Line 4: Listen for the draw event
Line 5: Get a reference to the table tbody node, since only nodes in this element should be highlighted.
Line 7: Remove any existing highlighting from a previous search
Line 8: Use search() to get the search term and highlight it.

For completeness a listener for the column-visibility event should also be added as column visibility toggling does not need to trigger a draw and we would want the highlighting to be applied to any column that is made visible.

Finally, the DataTables "No records found" message shouldn't be highlighted if the user enters a search term such as "records" and no rows are found! This can be done using the rows() method with the selector-modifier set to include only filtered rows in the result set:

body.unhighlight();

if ( table.rows( { filter: 'applied' } ).data().length ) {
    body.highlight( table.search() );
}

Feature plug-in

While it would be perfectly possibly to stop at this point, us software engineers hate needing to copy and paste code to reuse a feature (and rightly so, since it makes for a maintenance nightmare in future!), so now let's wrap the above code into a reusable feature plug-in for DataTables.

For this another DataTables event can be used: the init event which is triggered whenever a new DataTable is created. This event bubbles up through the DOM so a listener on the document will see every newly created DataTable in the document - i.e.:

$(document).on( 'init.dt', function (e, settings, json) {
    ...
} );

The next step is to check if the table should have row highlighting enabled on it, and if so, run the highlighting code developed above.

There are three methods by which this plug-in can be activated:

Adding the class searchHighlight to the HTML table
Setting the searchHighlight parameter in the DataTables initialisation to be true
Setting the searchHighlight parameter to be true in the DataTables defaults (thus causing all tables to have this feature) - i.e. $.fn.dataTable.defaults.searchHighlight = true.

Extending the init code from above to achieve this:

$(document).on( 'init.dt.dth', function (e, settings, json) {
    var table = new $.fn.dataTable.Api( settings );
    var body = $( table.table().body() );

    if (
        $( table.table().node() ).hasClass( 'searchHighlight' ) || // table has class
        settings.oInit.searchHighlight                          || // option specified
        $.fn.dataTable.defaults.searchHighlight                    // default set
    ) {
       ...
    }
} );

Line 1: Listen for the initialisation of a DataTable
Line 2: Get an DataTables API instance from the DataTable.Settings object passed into the event
Line 3: Get the table's body tag since we will be using it
Line 6: Check if the table has the class searchHighlight
Line 7: Check if the initialisation options had searchHighlight (a public API for this will be forthcoming)
Line 8: Check if the defaults have searchHighlight set
Line 10: Run the highlight code from above

Initialisation

In its simplest form, to activate highlighting of search terms in a table, now all we need to do is specify the searchHighlight term when initialising the table:

$(document).ready( function () {
    $('#example').DataTable( {
        searchHighlight: true
    } );
} );

The other options for giving a default or using a class name, as defined above, will also work nicely.

Released code

The code for the feature plug-in developed here is available on the DataTables CDN for immediate use:

CSS

Recall also that this plug-in depends upon the jQUery Highlight plug-in:

It is also hosted in the DataTables plug-ins repository on GitHub. Forks, pull requests, etc are all very welcome!