Feature plug-in development

DataTables' core abilities add a lot of flexibility to a plain HTML table, but there is a lot of room left for extensions to provide enhancements that might be specific to your use case or to add functionality that is not available in DataTables. For this, DataTables provides a number of APIs that can be used to create feature plug-ins. This page discusses the standard code patterns used to create them

Before we go into detail about how feature plug-ins are developed and attached to DataTables, let us consider the type of function that a plug-in might be developed for:

• Table control buttons (for example TableTools and ColVis)
• Row selection options (also TableTools)
• Filtering inputs
• Row enhancement options

Note that some of these require DOM elements to be shown in or around the table, and some are simply behaviour on top of DataTables, such as mouse click handling for row selection - this is important in the dom discussion that follows.

Plug-in initialisation

There are three standard methods in which a feature plug-in can be initialised by a developer for use with their own DataTables (note that not all feature plug-ins must provide all options - they might not all be suitable):

• Creation using the new Javascript keyword from an object attached to $.fn.dataTable or $.fn.DataTable.
• dom feature letter
• DataTables initialisation event

new initialisation

For most DataTables plug-ins, new instances of a Javascript "class" can be created using the new operator operator to provide instance separation. Simply create a new instance of a plug-in for each table. The plug-in code should be attached to the $.fn.dataTable and $.fn.DataTable objects so the developer using the plug-in can access the object, while also not polluting the global name space.

For example consider:

$.fn.dataTable.Filtering = function ( table, options ) {
  // ... plug-in logic
};

$.fn.DataTable.Filtering = $.fn.dataTable.Filtering;

Note that a capital is used for the first character of the plug-in parameter name, which by convention shows that a new instance can be created using the new keyword. This method is available for use with all DataTables extensions and recommended for new feature plug-ins.

Additionally, by convention, the first parameter is a DataTables instance object, table selector, jQuery object or DataTables setting option. The new $.fn.dataTable.Api( table ); method of accessing the DataTables API will provide an API instance from all of these alternatives. The second parameter used for the plug-in constructor is typically an object which can be configured by the developer with the configuration options for your plug-in.

Therefore the initialisation might look like:

var table = $('#myTable').DataTable();
var filter = new $.fn.dataTable.Filtering( table );

dom feature letter initialisation

As an alternative to creating a new instance of a class, you can provide a helper method to create it through the feature letter system of the dom DataTables configuration option. This also has the advantage of being able to place DOM elements around the table, in the same way that the built-in filtering input, pagination control, length input and table information elements can be controlled and moved around the table. This is particularly useful if you are creating a plug-in that requires additional DOM information to be inserted into the document (e.g. a button) since it provides the developer with the flexibility to decide where your control should be placed in the document.

It is important to understand how the dom option works in DataTables. Each letter in the value given to dom is assigned to a specific feature. DataTables provides an API to assign your plug-in its own letter. By convention, plug-ins are assigned a capital letter. Lower-case letters are reserved for built-in features. When encountered, the plug-in letter calls your plug-in function during the DataTable initialisation.

To add a new feature for DataTables using dom you need to register some basic information with the DataTables core (the callback function and the assigned letter), through the use of the $.fn.dataTable.ext.feature array. Each array element is an object which has the following parameters:

• fnInit: function which is called when the table is initialised
  • Input parameters:
  • 1. DataTables settings object
  • Return parameters: Node (optional) - the element which contains your feature. Note that the return may also be undefined if your plug-in does not require to inject any DOM elements into the document.
• cFeature: The character that will be used to represent your plug-in in the dom option string.

Consider the following example which assigns the letter 'F' to the function $.fn.dataTable.Filtering:

$.fn.dataTable.ext.feature.push( {
    fnInit: function ( settings ) {
        var filter = new $.fn.dataTable.Filtering( settings );
        return filter.node(); // input element
    },
    cFeature: 'F'
} );

The developer uses your "Filtering" plug-in to create a DataTable by assigning 'F' to the dom option string as follows:

$('#myTable').DataTable( {
    dom: 'lFrtip'
} );

DataTables initialisation event

This option provides the ability to have your code run on every DataTables creation through use of the init event. Consider for example:

$(document).on( 'init.dt.dtr', function (e, settings, json) {
    new $.fn.dataTable.Filtering( settings );
} );

Publish your plug-ins

If you create a feature plug-in for DataTables, please let us know! Others may benefit from your plug-in and I (and the community as a whole) will be very grateful for your contribution.