dataTable() vs. DataTable() - why is there a difference and how do I make them work together?

Question

The vast majority of the documentation for this plugin indicates that you initialize it with

$('#example').dataTable();

However http://www.datatables.net/examples/api/multi_filter_select.html initializes using

$('#example').DataTable();

The resultant objects differ quite a lot, and the example URL above doesn't work when I initialize with a lower-case 'D', however pretty much everything else requires the lower-case 'D' initialization.

Can someone please explain to me why there's a difference, and how to make the two play nice together? Essentially I need the multi-filter-select functionality, but also need to tack on some other calls / plugins, which don't seem to like the upper-case 'D' initialization.

Answer 1

Basically, the two constructurs return different objects.

---

dataTable constructor

var table = $(<selector>).dataTable()

dataTable is the oldschool dataTables constructur, which returns a jQuery object. This jQuery object is enriched with a set of API methods in hungarian notation format, such as fnFilter, fnDeleteRow and so on. See a complete list of API methods here. Examples :

table.fnDeleteRow(0); 
table.fnAddData(['E', 'F']);

dataTable is supported by all 1.9.x / 1.10.x versions.

---

DataTable constructor

var table = $(<selector>).DataTable()

The DataTable constructor was introduced in 1.10.x, and returns a huge API object with full read/write access to pages, rows, cells and more, see manual. Example equivalences :

table.row(0).remove();
table.row.add(['E', 'F']).draw();

---

Combining dataTable and DataTable

If you maintain old code, or for some reason need to use the oldschool dataTable constructor, but still needs to use the new API, the jQuery object is extended (from 1.10.0) with a .api() method that returns the new API. Example equivalences :

var table = $('#example').dataTable();
table.api().row(0).remove();
table.api().row.add(['E', 'F']).draw();

The old API like table.fnDeleteRow(0) still works. So to your concern :

Essentially I need the multi-filter-select functionality, but also need to tack on some other calls / plugins, which don't seem to like the upper-case 'D' initialization.

As you see, you can do both! Initialize dataTables the old way, and use .api() when you need access to the new API.

---

Why is so many official examples using dataTable()?

Well, you do not need to use the DataTable constructor. If you dont use the new API, there is no reason for using the DataTable constructur. The oldschool dataTable constructor is not deprecated. DataTables is mostly one mans work. It is a huge task to maintain and develop and obviously very time consuming to maintain a huge website with forum, manuals, tons of examples and so on. This is only a guess, but I assume Allan Jardine by now only have changed dataTable to DataTable where it is actually needed, simply bacause he cant do it all in one step.