Monday 9th November, 2015

NPM and Bower

Package and dependency management is an important aspect of many web-applications, particularly as their complexity continues to grow and many third party libraries are required. With the release of DataTables 1.10.10, and the latest revisions of its companion extensions, DataTables now fully embraces package management as a core part of the project.

DataTables, its extensions and the styling options now feature well defined CommonJS and AMD loaders enabling their publication on NPM and Bower - search for datatables.net. This also opens options to use other tools such as Browserify and WebJars.

History

First a quick note for anyone thinking - "but I already use CommonJS / AMD loaders with DataTables": DataTables and its extensions have had CommonJS and AMD loaders for the last three years. This release simply updates the implementation used to be consistent between DataTables and all of its extensions, and to include also the styling frameworks (Bootstrap, Foundation, jQuery UI and DataTables own styling) for the first time.

Distribution packages

DataTables and its extensions are available on GitHub, with each extension in its own repository. These repositories contain the source code (e.g. SCSS, Javascript that needs to be assembled, etc), but not compiled files (e.g. no raw CSS or minified Javascript). They also contain the styling information for the style libraries that DataTables supports - currently Bootstrap, Foundation, jQuery UI and its own base style.

The information in these repositories don't immediately lend themselves to easy inclusion in a project: you'd need to set up your own compile tool-chain and include only the required files, ignoring the styling options you don't want.

To resolve this, new distribution packages have been created which contain the compiled files and only the files needed for that specific package. Each core library (DataTables, AutoFill, Buttons, etc) has its own distribution package and packages for each of the styling options. Consider for example DataTables and AutoFill - we have the following packages available:

The result is that you must include the library package and a styling package.

The package names always start with datatables.net. The styling package names are always postfixed with:

  • -dt - DataTables own default styling
  • -bs - Bootstrap
  • -zf - Foundation
  • -jqui - jQuery UI

The styling packages have their dependencies correctly configured to include the core library, so you only need to install the styling package you want and the package manger will do the rest for you.

Require

Both CommonJS and AMD define their own require() function that is used to include libraries. This is a quick overview of how you might use them with the DataTables distribution packages.

CommonJS

When using CommonJS the DataTables packages all export a factory function that can be executed with two optional arguments:

  1. The window object to use (this is require as jQuery in a headless CommonJS environment can require a window with a document attached). If no parameter is given, or it is falsy, window will be used.
  2. The jQuery object that DataTables should be attached to. If no parameter is given, the package will do its own require('jquery') to include jQuery.

For example - no arguments:

var $       = require( 'jquery' );
var dt      = require( 'datatables.net-dt' )();
var buttons = require( 'datatables.net-buttons-dt' )();

And with the window and jQuery arguments supplied:

var $       = require( 'jquery' );
var dt      = require( 'datatables.net-dt' )( window, $ );
var buttons = require( 'datatables.net-buttons-dt' )( window, $ );

As noted above, the styling libraries will automatically resolve their own core library dependencies - i.e. in the above example the packages datatables.net and datatables.net-buttons are automatically resolved.

A full list of the packages available on NPM and install instructions are available on the DataTables NPM download page.

AMD

The AMD loader used by DataTables will export the library that the module describes. For example DataTables core file (datatables.net) will export $.fn.dataTable, while Buttons (datatables.net-buttons) will export $.fn.dataTable.Buttons. The styling packages will export their host library.

For example, we might have:

require.config( {
    paths: {
        'datatables.net': 'https://cdn.datatables.net/1.10.10/js/jquery.dataTables.min',
        'datatables.net-buttons': 'https://cdn.datatables.net/buttons/1.1.0/js/dataTables.buttons.min'
    }
} );

require( ['jquery', 'datatables.net', 'datatables.net-buttons'], function ($, dt, buttons) {
    $('#myTable').DataTable();
} );

This example demonstrates only the Javascript aspect of loading DataTables with RequireJS. Obviously you will likely wish to style the table as well - RequireJS does not support CSS loading. Some plug-ins are available, however, for Javascript and styling combined you may find it easier to use CommonJS combined with Browserify or the DataTables download builder.

Concatenate your files

While HTTP/2 will resolve the issue of latency when loading multiple files, until the new protocol has wide-spread adoption, remember to concatenate your files! This is particularly important in an AMD environment such as RequireJS where each individual file being requested from the server could case serious performance issues.

The DataTables download builder can be used to create single files that includes the software you require.

Enjoy!

The addition of package manager support in the DataTables project completes a set of work that was designed to make it easier to get started and develop with DataTables. The download builder started this off, and the new CommonJS and AMD support provides compatibility with many package managers.

If you have any feedback on this work, please feel free to open a new thread in the the forums.