Debugger update

Back in 2012 I introduced the first version of the DataTables debugger. Today I'm happy to present an updated version that introduces a number of new features as well as an increased focus on privacy.

The DataTables debugger can be used either as a bookmarklet or by simply copying and pasting a few lines of code from the debugger site into your browser's console and running it. When loaded the debugger will now offer a display with four options for actions to take:

1. Table summary information: This can be useful to see an overview of the tables on your page, their data sources and processing modes.
2. Version information: Display information about the versions of the DataTables software being used on your page and compare that to the latest versions that are available (indicating if upgrades are available).
3. Running common tests: We've found that a number of users encounter some of the same issues when using DataTables. These aren't always easy or appropriate to test for in DataTables, so the DataTables debugger steps into this gap and will inform you of any errors of configuration issues that have been found and how to handle them.
4. Upload data: As before, you have the option of uploading information about the table to the debug server. However, while this happened automatically before, you now need to explicitly click the upload button to make this happen. We've also changed how the debug information can be accessed so only employees of SpryMedia can see the debug trace.

Using the debugger

Full details on how to run the debugger on your page can be found on the debugger site. However, all you need to do is open your browser's console and copy / paste the following Javascript and then press return:

var n = document.createElement('script');
n.setAttribute('language', 'JavaScript');
n.setAttribute('src', 'https://debug.datatables.net/debug.js');
document.body.appendChild(n);

Open source

The client-side component of the debugger is now open source and we encourage you to take a look at the source if you are interested - particularly in adding any new tests that might be useful. The code is TypeScript and can be compiled to Javascript by simply typing gulp. Ensure that you run npm install first to load any dependencies.

Pull requests are welcome - code is formatted using Prettier with tabs.

Tests

One of the most interesting aspect of the new debugger is its ability to run tests locally on the client, ensuring the integrity of the DataTables on the page. We plan to add new tests whenever appropriate based on support requests from the forum. The goal here is to catch misconfiguration errors that can be programmatically checked for, without the need to increase the code size of DataTables core and its extensions.

If you are interested in contributing any new tests, add your test as a new file in the js/tests directory. You should import the ../lib file which includes common library functions for tests, including the method to create a new test.

A test should return an array of objects that contain table, level and msg properties detailing any errors that have been detected (TypeScript will show errors if the test function doesn't conform with what is required!). The structure of a typical test might look like:

import * as lib from '../lib';

lib.createTest('Test name', function($) {
    let out = [];

    if (!$.fn.dataTable) {
        return out;
    }

    $.fn.dataTable.tables({ api: true }).iterator('table', function(settings, i) {
        ...
    });

    return out;
});

You must also add your new file to the list in js/tests/index.ts to ensure that it is included in the debugger. Then run gulp to build the new debugger and run it in your browser with (updating the path as required of course!):

var n = document.createElement('script');
n.setAttribute('language', 'JavaScript');
n.setAttribute('src', '/path/to/debug/index.js?rand=' + new Date().getTime());
document.body.appendChild(n);

Support requests

Our goal with the debugger is to help you to help us with any support requests. When requesting help we need information about how you are using DataTables and its extensions - the debugger can typically give us that information (for non-styling related questions). As such, we will be increasingly asking for debug traces where no test case is possible (a test case is still far preferable!).

Enjoy!