Monday 24th July, 2017

Deep linking into DataTables

A question that comes up relatively frequently in the forums is "how do I deep link into a DataTable?" This is usually asked in the context of SEO where you want to ensure that all of the data in the table is indexable, but it can also be appropriate in applications where you want to show a table with a specific search term pre-set.

Typically the answer to such a question is to use the initialisation parameters to set whatever option is required from the search string, but it is such a common thing to want to do, it is sensible that we generalise it. To that end, here I present a short script that can be used to extract parameters from a search string and use them to populate a DataTable.

Let's see it in action first - follow the links below to observe the behaviour on the demonstration table:

NamePositionOfficeAgeStart dateSalary
NamePositionOfficeAgeStart dateSalary
Tiger NixonSystem ArchitectEdinburgh612011/04/25$320,800
Garrett WintersAccountantTokyo632011/07/25$170,750
Ashton CoxJunior Technical AuthorSan Francisco662009/01/12$86,000
Cedric KellySenior Javascript DeveloperEdinburgh222012/03/29$433,060
Airi SatouAccountantTokyo332008/11/28$162,700
Brielle WilliamsonIntegration SpecialistNew York612012/12/02$372,000
Herrod ChandlerSales AssistantSan Francisco592012/08/06$137,500
Rhona DavidsonIntegration SpecialistTokyo552010/10/14$327,900
Colleen HurstJavascript DeveloperSan Francisco392009/09/15$205,500
Sonya FrostSoftware EngineerEdinburgh232008/12/13$103,600
Jena GainesOffice ManagerLondon302008/12/19$90,560
Quinn FlynnSupport LeadEdinburgh222013/03/03$342,000
Charde MarshallRegional DirectorSan Francisco362008/10/16$470,600
Haley KennedySenior Marketing DesignerLondon432012/12/18$313,500
Tatyana FitzpatrickRegional DirectorLondon192010/03/17$385,750
Michael SilvaMarketing DesignerLondon662012/11/27$198,500
Paul ByrdChief Financial Officer (CFO)New York642010/06/09$725,000
Gloria LittleSystems AdministratorNew York592009/04/10$237,500
Bradley GreerSoftware EngineerLondon412012/10/13$132,000
Dai RiosPersonnel LeadEdinburgh352012/09/26$217,500
Jenette CaldwellDevelopment LeadNew York302011/09/03$345,000
Yuri BerryChief Marketing Officer (CMO)New York402009/06/25$675,000
Caesar VancePre-Sales SupportNew York212011/12/12$106,450
Doris WilderSales AssistantSidney232010/09/20$85,600
Angelica RamosChief Executive Officer (CEO)London472009/10/09$1,200,000
Gavin JoyceDeveloperEdinburgh422010/12/22$92,575
Jennifer ChangRegional DirectorSingapore282010/11/14$357,650
Brenden WagnerSoftware EngineerSan Francisco282011/06/07$206,850
Fiona GreenChief Operating Officer (COO)San Francisco482010/03/11$850,000
Shou ItouRegional MarketingTokyo202011/08/14$163,000
Michelle HouseIntegration SpecialistSidney372011/06/02$95,400
Suki BurksDeveloperLondon532009/10/22$114,500
Prescott BartlettTechnical AuthorLondon272011/05/07$145,000
Gavin CortezTeam LeaderSan Francisco222008/10/26$235,500
Martena MccrayPost-Sales supportEdinburgh462011/03/09$324,050
Unity ButlerMarketing DesignerSan Francisco472009/12/09$85,675
Howard HatfieldOffice ManagerSan Francisco512008/12/16$164,500
Hope FuentesSecretarySan Francisco412010/02/12$109,850
Vivian HarrellFinancial ControllerSan Francisco622009/02/14$452,500
Timothy MooneyOffice ManagerLondon372008/12/11$136,200
Jackson BradshawDirectorNew York652008/09/26$645,750
Olivia LiangSupport EngineerSingapore642011/02/03$234,500
Bruno NashSoftware EngineerLondon382011/05/03$163,500
Sakura YamamotoSupport EngineerTokyo372009/08/19$139,575
Thor WaltonDeveloperNew York612013/08/11$98,540
Finn CamachoSupport EngineerSan Francisco472009/07/07$87,500
Serge BaldwinData CoordinatorSingapore642012/04/09$138,575
Zenaida FrankSoftware EngineerNew York632010/01/04$125,250
Zorita SerranoSoftware EngineerSan Francisco562012/06/01$115,000
Jennifer AcostaJunior Javascript DeveloperEdinburgh432013/02/01$75,650
Cara StevensSales AssistantNew York462011/12/06$145,600
Hermione ButlerRegional DirectorLondon472011/03/21$356,250
Lael GreerSystems AdministratorLondon212009/02/27$103,500
Jonas AlexanderDeveloperSan Francisco302010/07/14$86,500
Shad DeckerRegional DirectorEdinburgh512008/11/13$183,000
Michael BruceJavascript DeveloperSingapore292011/06/27$183,000
Donna SniderCustomer SupportNew York272011/01/25$112,000

The code for this example is simply:

$('#myTable').DataTable( $.fn.dataTable.ext.deepLink( [
    'search.search', 'order', 'displayStart'
] ) );

You also need to include the deep linking script on your page:

JS

Usage

The key element of using this script on your own pages is the $.fn.dataTable.ext.deepLink function. This takes a single argument: an array of the options that you wish to allow the search parameter to specify, and it will return an object that contains these initialisation options which can be passed straight to the DataTable, as is the case above.

A white-list approach is used to limit which options can be used for security. For example, it is unlikely you would wish to allow a user to modify the ajax, serverSide or scrollY parameters. If a parameter is given which isn't in the white-list, it will be ignored. Having said that, if you are using your application in an environment where you do wish any and all parameters to be used, you can specify all as the only argument to the function, which will allow all parameters.

A simple example: allow the search.search parameter to be set from the search string:

$('#myTable').DataTable( $.fn.dataTable.ext.deepLink( [
    'search.search'
] );

Extending defaults

Since the deepLink() function simply returns an object, you can provide defaults which can optionally be overridden by the search string, or vice-versa have an optional parameter that will override any parameter from the search string. This can be done using the jQuery.extend() function with the returned object:

var searchOptions = $.fn.dataTable.ext.deepLink( [
    'order'
];
var defaultOptions = {
    order: [[ 2, 'desc' ]]
};

$('#myTable').DataTable(
    $.extend( defaultOptions, searchOptions );
);

How does it work?

Now that we know how to use it, if you are interested in how it works, read on. Its actually very simple! Let's first step back to my standard response in the forum to say that the search string should be used to set the parameter value. If we assume that the entire search string is to be used to search the table (e.g. /table?mySearchTerm) we might use:

$('#myTable').DataTable( {
    search: {
        search: location.search.replace(/^\?/, '')
    }
} );

The key now is to break the search string into key value pairs. Slightly surprisingly there isn't an API for this in browsers, but its trivial to do with String.prototype.split and decodeURIComponent():

$.fn.dataTable.ext.deepLink = function(whitelist) {
    var search = location.search.replace(/^\?/, '').split('&');
    var out = {};

    for (var i = 0, ien = search.length; i < ien; i++) {
        var pair = search[i].split('=');
        var key = decodeURIComponent(pair[0]);
        var value = decodeURIComponent(pair[1]);

        ...
    }

    return out;
};


### Casting values

The query string can only directly hold string values (it is a string itself after all), unless we use a data schema such as JSON. JSON isn't pretty to look at in a URL, so we want to avoid that here. The type always being a string is an issue in this case as certain DataTables parameters expect other types - for example `-init displayStart` must be a `Number` and not a `String` while `-init paging` is a Boolean. As such we need to [cast](https://en.wikipedia.org/wiki/Type_conversion) the string values into their typed counterparts:

```js
if (value === 'true') {
    value = true;
}
else if (value === 'false') {
    value = false;
}
else if (!value.match(/[^\d]/)) {
    value = value * 1;
}
else if (value.indexOf('{') === 0 || value.indexOf('[') === 0) {
    // Try to JSON parse for arrays and obejcts
    try {
        value = $.parseJSON( value );
    }
    catch(e){}
}

The downside to this is that it wouldn't be possible to set search.search to true since it would be cast to the boolean value by the above code. I feel this is a relatively unlikely situation to run into, but if you do, the above piece of code would need to be modified to suit your needs.

Writing nested values

You might have noticed in the above examples that search.search is used a lot, since that is one of parameters that I expect to be used most commonly with this script. However, the Javascript object version of it is actually { search: { search: ... } } - i.e. a nested object. To convert from the string notation, we can use a function which DataTables has built-in to build nested objects based on a dot delimited string: $.fn.dataTable.ext.internal._fnSetObjectDataFn (this is used for columns.data). This function isn't a documented API, but the next major version will see it promoted to be so (albeit with a more accessible name) as it is exceptionally useful for plug-ins and add-on scripts!

var setBuilder = $.fn.dataTable.ext.internal._fnSetObjectDataFn;

if (whitelist === 'all' || $.inArray(key, whitelist) !== -1) {
    var setter = setBuilder(key);
    setter(out, value);
}

Source and Git

The full documented source for this script can be found on GitHub. If you have any ideas for how it can be enhanced, pull requests are welcome!