Available options

You may want to customize the some parameters of your datatable. The following table summarize the options that can be passed to the constructor (second argument):

data

If you don't specify the data option, the plugin will load the data from the current HTML table, considering each row as an element (See the example above).

If you specify a javascript array (of array or of element), it will be used as the data:

$('#MyTable').datatable({
    data: [
       ['Albert', 'Einstein', 'Computer Science'],
       ['Isaac', 'Newton', 'Physics']
    ]
}) ;

$('#MyTable').datatable({
    data: [
       {firstname: 'Albert', lastname: 'Einstein', field: 'Computer Science'},
       {firstname: 'Isaac', lastname: 'Newton', field: 'Physics'}
    ]
}) ;

Depending on the type of element (array or object), you have to be carefull when you use the filter and the sort option which use the key.

Ajax data

If you don't want to put the data on the HTML page (because of the amount of data, for example), you can specify a ajax URL that will be used by the plugin to load asynchronously the data.

To do that, you first have to create a web service that will take 2 arguments (get or post, see below), which are:

• offset: The first line to retrieve
• limit: The number of lines to retrieve

The service should return a json array containing the data.

For example, if the plugin send a request with offset=10 & limit=2 to your server, it should return something like that:

[{firstname: 'Albert', lastname: 'Einstein', field: 'Computer Science'}, {firstname: 'Isaac', lastname: 'Newton', field: 'Physics'}]

To use the service, you have to pass specific data option to the plugin:

$('#MyTable').datatable({
    data: {
        url: "http://my-web-site/datas/get", // The service URL
        type: "post", // The type of request (post or get)
 /* The total amount of data, this parameter can be given as a data-size attribute on the table. If not specified, the data will be load asynchronously block by block until the server return an empty array (slower mode). */
        size: 157,
 /* The number of milliseconds between each refresh of ajax data (using asynchronous mode). If you do not want to enable this feature, just set this option to false. */
        refresh: 5000
    }
}) ;

counterText

You can customize the counter text, see the default function below for example:

function (currentPage, totalPage, firstRow, lastRow, totalRow) {
    return 'Page '   currentPage   ' on '   totalPage   '. '
          Starting at '   firstRow   ', ending at ' 
          lastRow   ' over '   totalRow   ' entries.' ;
}

sort

The plugin allow you to sort data in different way, specifying which column can be sort, or which key to use.

Sorting data using specific function

If you specify a function as the sorting option, it will be used to sort data, but you won't be able to change the sorting direction (asc or desc). The function should take 2 arguments and return -1, 0, or 1 if the first argument is resp. lower, equal or greater than the second.

Currently, it is only possible to specify one function for the whole table (not a function for each column).

Specifying which column can be sort

You have 4 ways to specify the columns, depending on the sort option:

• false - No sortable columns
• true - The sortable columns will be find according to data-sort attribute of <th> tags.
• '*' - All the column will be sortable.
• [true, false, function (l, r) { }, true] - Specific sort for each column
  • function (l, r) { } (return values must be -1, 0 or 1 if l is lower, equal or greater than r), the column is sortable, and the order is computed using the specified function (for this column).
  • false - the column is not sortable.
  • true - shortcut for the following function: function (l, r) { return l < r ? -1 : (l > r ? 1 : 0) ; }, which is a standard sort function.

When the plugin sort the data, it will used a key to find which field in each element it should compare. You can specify the sorting key of each column in the data-sort attribute of <th> tag. If you don't specify key but you enable sort, the key will be number (first column will be sort according to first value in each element, second column according to second value, etc.).

You can specify a default sort by specifying sortKey and sortDir options.

filters

You can add filters on some columns if you want. The filter are text input or select (multiple or not).

To add filters, you should specify the filters option which is an array. Each element of the array correspond to a column can take different values:

In the select form, the comparison is done according to option value, not option text.

Another form exist to create select filter, which is specified as a plain javascript object:

{
    /* The jQuery element to use (if you want to use a custom select element), if not specified, a new select
    will be created. */
    element: $('#my-select') | null,
    /* The list of options. Notice that {0: "Option 0"} will output <option value=0>Option 0</option>, so the value used to filter is 0, not "Option 0". 
    HINT: If you don't want to specify the values manually, you can set this values: "auto" which will retrieve values from the table. */
    values: {0: "Option 0", 1: "Option 1"} | "auto", 
    /* The select default selected options, can be either a value or an array (for multiple select). If not specified, no value will be selected (for simple select), or all the values (for multiple select). */
    default: 0,
    /* Specify if an empty entry should be added. Default value is true. This parameter as no effect on multiple select. */
    empty: true | "Pick to filter... ",
    /* True for multiple select, false for simple. Default value is false. */
    multiple: false,
    /* Will not create a column for this filter. Useful if you want to filter data on a field which is not displayed in the table. */
    noColumn: false,
    /* A custom filter function to specify if you don't want the value to be filtered according to the options key. */
    fn: function (data, selected) {
        /* Note that selected is always an array of string. */
        if (selected.length === 1) { // Only one option selected
            if (selected[0] === "1") { // Values are always strings
                return data < 10 ;
            }
            else {
                return data >= 10 ;
            }
        }
        /* Note that when using multiple select, selected will contain selected keys.
        When the empty value is picked, the selected array will contain all available keys. */
        return true ;
    }
}

Warning: The difference between the two 'select' filters is done according to the 'values' key. If one of your options uses 'values' as a key, you have to use the latest form.

You can customize the default text in the input filter (i.e. the placeholder) by specifying filterText option (See the example). If you specify a string for the 'empty' option, it will be displayed when no options are selected (ex: 'Pick to filter... ').

It is possible to directly specify a jQuery element (like $('#my-input')) as an element of the filters option, this element will not be moved inside the table (use it if you want your filter to add a filter outside the table).

Note: It is possible to create a filter which is not linked to a specific field, such filter is called a "lambda" filter. To create a lambda filter, you need to use a javascript object for the filter option and specify a fieldname starting with a _.

$('#myTable').datatable({
    filters: {
        firstname: true, // A normal text filter
        _1: function (data, text) { // A lambda filter, which will be placed in the second column
            // Here data is an array or object depending on your data
            return (data.firstname   data.lastname).indexOf(text) > -1 ; // Search in both first and last names
        },
        _2: { // Another lambda filter, this time this is a select
            values: ['Option 1', 'Option 2'],
            fn: function (data, selected) { // You need to specify the 'fn' attribute in this case
                // Here data is an array or object depending on your data
                if (selected.length === 1) {
                    return data.field == selected[0] ;
                }
                return true ;
            }
        }
    }
});

lineFormat

You can customize the way line are displayed, the function should return a jQuery line (see default function below for example):

function (id, data) { 
    var res = $('<tr></tr>') ;
    for (var key in data) { 
        res.append('<td>'   data[key]   '</td>') ; 
    }
    return res ;
}

Hint: You can use this function to store data into your row or to display hidden columns:

function (id, data) { 
    var res = $('<tr></tr>') ;
    res.data('data', data) ; // Store the data
    res.attr('data-id', id) ; // Store the id
    for (var key in data) {
        var td = $('<td>'   data[key]   '</td>') ;
        if (key === 'field') {
            td.hide() ; // Don't display the field column
        }
        res.append(td) ; 
    }
    return res ;
}

Datatable methods

Here is a list of the method available from a DataTable object:

Available commands are:

Some options required an ID, how element are compared is specified by identify option. If identify is a string, then element are compared using this key. If identify is a function, 2 elements are equals if identify returns true. Examples:

/* EXAMPLE 1 */

/* Two elements E1 and E2 are equals if E1.id === E2.id. */
var datatable = new DataTable(document.getElementById('MyTable'), {
    identify: 'id'
});

/* Delete the first element E found such as E.id === 4. */
datatable.deleteRow(4) ;

/* EXAMPLE 2 */

var datatable = new DataTable(document.getElementById('MyTable'), {
    identify: function (id, E) { 
        return id.toUpperCase() === E.fullname.toUpperCase() ; 
    }
}) ;
/* Update ISAAC NEWTON. The update function will update any field found in the second parameter. */
datatable.updateRow('ISAAC NEWTON', {field: "Mathematics"}) ;

/* EXAMPLE 3 */

function myFilter (data) {
    return data.field == "Mathematics" ;
}

var datatable = new DataTable(document.getElementById('MyTable'));

/* Retrieve all mathematicians. */
var savedData = datatable.all(myFilter);
/* Delete all mathematicians. */
datatable.deleteAll(myFilter);
/* Insert all the mathematicians. */
datatable.addRows(savedData);