Fork me on Github

Datatable - A javascript plugin...

...for smarter HTML table, by @Holt59.

Code on Github Download (.zip)

Getting Started

Dependencies

Since version 2, this plugin is standalone, thus there are no dependencies.

Info! This page uses Bootstrap, so you may not have the exact same rendering for your table.

Installation

Download the archive containing the plugin, or clone it using:

git clone https://github.com/Holt59/datatable.git

Using the plugin

You need to include the following files in order to use the plugin:

<!-- CSS files (include only one of the two files!) -->
<!-- If you are not using bootstrap: -->
<link rel="stylesheet" type="text/css" href="css/datatable.min.css" media="screen">
<!-- If you are using bootstrap: -->
<link rel="stylesheet" type="text/css" href="css/datatable-bootstrap.min.css" media="screen">
                        
<!-- JS files -->
<script type="text/javascript" src="js/datatable.min.js"></script>
                        
<!-- Add the following if you want to use the jQuery wrapper (you still need datatable.min.js): -->
<script type="text/javascript" src="js/jquery.min.js"></script>
<script type="text/javascript" src="js/datatable.jquery.min.js"></script>

Your first datatable

Below is a basic example on what you could get using this plugin (there are tons of extra options documented below):

Firstname Lastname
Linus Torvalds Computer Science
Brian Kernighan Computer Science
Blaise Pascal Mathematics
Larry Page Computer Science
Richard Hamming Mathematics
Grace Hopper Computer Science
Pierre Bezier Mathematics
Shigeru Miyamoto Computer Science
Leslie Lamport Computer Science
Rasmus Lerdorf Computer Science
Xavier Leroy Computer Science
Albert Einstein Physics
Bill Gates Computer Science
Leonard De Vinci Mathematics
Pierre De Fermat Mathematics
René Descartes Mathematics
Alan Turing Computer Science
Ada Lovelace Computer Science
Isaac Newton Physics
Carl Friedrich Gauss Mathematics
John Von Neumann Computer Science
Claude Shannon Mathematics
Tim Berners-Lee Computer Science
Richard Stallman Computer Science
Dennis Ritchie Computer Science
Bjarne Stroustrup Computer Science
Steve Jobs Computer Science
Steve Wozniak Computer Science
Mario Molina Chemistry
var datatable = new DataTable(document.querySelector('#first-datatable-output table'), {
    pageSize: 5,
    sort: [true, true, false],
    filters: [true, false, 'select'],
    filterText: 'Type to filter... ',
    pagingDivSelector: "#paging-first-datatable"
});
$('#first-datatable-output table').datatable({
    pageSize: 5,
    sort: [true, true, false],
    filters: [true, false, 'select'],
    filterText: 'Type to filter... ',
    pagingDivSelector: "#paging-first-datatable"
});

Ugh? If you feel upset because your favorite scientist do not show up in the above table, feel free to add it by creating a pull request!

Available Options

data

The data option specifies which data should be rendered in the datatable based on its type.

From the HTML table

If the option data is not defined or set to false, the data will be retrieved from the current content of the HTML table (see your first datatable example above).

From an array of array

If data is an array (data instanceof Array), it will be used to fill the table, considering each cell of the array as an entry for the datatable:

var datatable = new DataTable(document.querySelector('#my-table'), {
    data: [
        ['Albert', 'Einstein'],
        ['Linus', 'Torvalds'],
        ['Ada', 'Lovelace']
    ]
});
Firstname Lastname

Warning! Do not forget to add the <tbody></tbody> tag inside your table before running datatable.

From an array of object

You may want to use Object as cell instead of Array, it may be useful to specify sort, identify or filters options:

var datatable = new DataTable(document.querySelector('#my-table'), {
    data: [
        {firstname: 'Albert', lastname: 'Einstein'},
        {firstname: 'Linus',  lastname: 'Torvalds'},
        {firstname: 'Ada',    lastname: 'Lovelace'}
    ]
});
Firstname Lastname

AJAX Data

It is possible to load data using AJAX with datatable, to do so, you need to pass a javascript object as the data option (see below for more explanation):

{
    data: {
        url: "http://site.com/get", // The service URL
        type: "post" | "get",       // The type of request (post or get)
        size: null | int,           // The total amount of data to load, 
                                    // may also be specified as the data-size attribute
        allInOne: false,            // Set to true to load all your data in one AJAX call
        refresh: false | int        // Set to a positive value to refresh the data 
                                    // every X milliseconds
    }
}

Server side

The server must returns data in JSON format: One JSON array containing either JSON array or object as cells:

[["Albert", "Einstein"], ["Isaac", "Newton"]]
// Or...
[{"firstname": "Albert", "lastname": "Einstein"}, {"firstname": "Isaac", "lastname": "Newton"}]

Below is a simple PHP example:

// Please do not use the following in production, this is not safe code!
$start = $_GET['start'];
$limit = $_GET['limit'];

$entries = array();
foreach ($db->query("SELECT * FROM my_table LIMIT $start, $limit") as $row) {
    $entries[] = $row;
}

echo json_encode($entries);

Warning! The plugin may ask for more data than what is currently available (e.g. for the last block), so your server code must be able to handle such request (by returning smaller or empty arrays).

AJAX options

By default (allInOne = false), the plugin will load data block by block using the following type of URL:

http://site.com/get?offset=0&limit=50

Where http://site.com/get is the URL specified in the data option and offset and limit define the range of data that should be returned.

Below are the available possible values for the options size and allInOne:

size allInOne
int false Prefered! Data will be retrieved asynchronously (multiple simultaneous AJAX calls).
int true Data will be retrieved in one AJAX call (do not use if you want to load a large amount of entries).
null false | true Data will be retrieved (asynchronously) by doing one AJAX call at a time (slower than the first one).

Info! If refresh != false, the whole table will be refreshed every X milliseconds using the third way specified above (as if size was null and allInOne was false). You may initialy load data the way you want even if the refresh mode is fixed.

Other Options

Below is a summary of all the available options.

Option Default value
data
tableClass "datatable" The class to be added to the HTML table element.
pagingDivSelector ".paging" The jQuery selector for paging divs.
pagingDivClass "pagination pagination-centered" The HTML class which will be added to the paging div.
pagingListClass "" The HTML class which will be added to the <ul> tag inside the paging div.
counterDivSelector '.counter' The jQuery selector for counter divs.
counterText See below.
loadingDivSelector '.loading' The jQuery selector for the ajax loading div.
sort false See the sort part below for more information.
sortKey undefined The default sort key (if sort enable).
sortDir 'asc' The default sort direction ('asc' or 'desc').
nbColumns -1 The number of columns. If not specified will be find according to the number of <th> tags in the head of the table.
pageSize 20 The number of elements that will be shown on each page.
identify false The key to use for check if 2 element are equals. Can also be a function.
pagingNumberOfPages 9 The number of pages that will be shown on the pagination list.
filters See the filter part below for more information.
filterText 'Search... ' The placeholder for the input filter (text and regexp).
filterEmptySelect '' The default empty text for select filter.
filterSelectOptions false If enable, select options will be filtered according to other filters.
filterInputClass '' The HTML class for search input.
filterSelectClass '' The HTML class for search select.
onChange function (old, new) {} A callback call before page is changed.
beforeRefresh function () {} A callback call before each refresh.
afterRefresh function () {} A callback call after each refresh.
lineFormat See below.
firstPage &lt;&lt; First page link text (set to false to do not show the link).
prevPage &lt; Previous page link text (set to false to do not show the link).
nextPage &gt; Next page link text (set to false to do not show the link).
lastPage &gt;&gt; Last page link text (set to false to do not show the link).

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:

falseNo filter for the specified column.
trueText input filter (see «Firstname» column on the example above).
function (data, text) { }Custom <input> filter, the first parameter is the value to test and the second one is the current input value (upper case).
'regexp'Regexp input filter.
'select'Select input: The options are find according to the current data set. This value should never be used with ajax loading.
{0: "Option 0", 1: "Option 1"}Select filter options.

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:

Method name Parameters Info
refresh Refresh the datatable output.
destroy Remove the datatable.
option Name, Value Set a option value (the data options can not be set this way).
page Page number If a argument is specified, load the specified page, otherwize return current page number.
reset-filters Reset all filters.
select null / ID / function Retrieve :
  • All the elements if no argument is specified
  • A filtered set of elements if a function is specified
  • The first the first element found with the specified ID otherwise
insert Element / [E1, E2, ...] Add the specified element(s) to the data array.
update ID, Element Update the first element found with the specified ID with the new specified data.
delete ID / function Remove:
  • All the element matching the specified function if a function is specified
  • The first element found with the specified ID otherwise

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);