Feedback request for API improvements

allan

Hello all,

I've been thinking about what I would like to do for DataTables 1.8 recently, and one of the key features I'd like to improve about DataTables are its API methods. As always with APIs any changes need to be considered carefully in order to ensure that the upgrade doesn't completely break existing applications. As such, I would like to request some feedback from you all. I do not wish to make changes such as renaming functions or moving parameters around (a major break in the API I would call 2.0), but what I do propose is:

- Making the API functions apply to all table elements in any array of DataTables objects (effectively removing iApiIndex). So for example if you use oTable = $('.datatable').dataTable(); which matches 3 tables and then oTable.fnFilter('hello'), that would filter all three tables. What I propose in order to allow single initialisation and individual table API control is two fold - 1. the object retrieval that is currently present (meaning you could actually do single initialisation and multiple API control), and 2. add a new API function called 's' (for selector, possibly fnSelector would be better...). This way you could do something like oTable.s(':first').fnFilter('hello').

- Anywhere a node can be passed in (for example in fnAddData), you should be able to pass in either a jQuery object (with whatever selector has been used and the resulting nodes) or an array of nodes.

- Harmonisation of redraw options - I'm considering dropping the automatic call to redraw the table on all functions (for example fnFilter would need to be followed by a call to fnDraw), or including it in all functions. Function aliases could potentially be used for this.

Any thoughts or suggestions on this are most welcome!

Regards,
Allan

GregP

I'd like to see some sort of way to use a try/catch for fetching data. An activity to perform on error. On success is easy; the table gets drawn and then you have the fnDrawCallback. But error is trickier. You get an alert message, but unless you want to dig into the core of the plugin, there's no other way to handle retrieval error.

My application, for whatever reason, will occasionally alert JSON parse errors, and it would be nice to be able to act on those errors beyond an alert (or in my case, ignoring the alert and just waiting for the next poll).

allan

Hi Greg,

Thanks for the input! What you can do if you want a custom error handler is use the fnServerData function to replace the default Ajax call with whatever call and parameters you want to make. It's possible to expose the whole $.ajax API, but it seems that fnServerData is more flexible in what it allows.

Regards,
Allan

vicaya

1. Be able to override the default fnServerData function in a plugin. This will make my virtual rendering plugin much easier to use. In that you can just use $('#foo').dataTable().virtualRender({data: oneMillionRowArray});

2. Expose more internal utility (sorting/filtering) functions so that plugin writers doesn't have to reinvent/copy/paste the wheels.

3. While I'm with the Hungarian notation naming convention for internal implementations. Many developers I recommended dataTables to commented on how jarring the naming convention is, as it's inconsistent with the rest of jquery and js community in general. IMHO, hungarian notation leaks implementation detail and is not appropriate for API names in dynamic language where you can provide easily provide polymorphic types for any data, so when you evolve APIs you don't have to introduce new names, say from aaData to oaData or whatever and just use "data" that can support multiple data types and throws errors on unsupported types. A compatibility plugin can be provided to deal with any API changes, just like jquery.compat*.js plugins.

allan

1. It is actually possible to override fnServerData with a plug-in at the moment - you just need to replace oSettings.fnServerData with your custom function. Not quite how your 'virtualRender' initialisation is above (unless it was an API plug-in, which is possible as well...), but similar depending on how it is implemented.

2. All internal functions are exposed through the oApi object, so they can be accessed by plug-in developers. They aren't documents on this site, because they are internal functions, but they are available if needed.

3. I understand the concern about Hungarian notation - there is a small discussion about why I use it here: http://datatables.net/development/#notation . I'll not be stepping away from it in the 1.x series of DataTables since it would completely change the entire API, but I will consider it for a 2.x release. Personally I find it useful to know that 'bProcessing' (for example) needs a boolean, rather than just 'processing' which could be a string or anything else.

Regards,
Allan