Client / server data interchange - upgrading from 1.4

Editor 1.5 introduces the ability to create and edit multiple rows with a single Ajax call. While this ability greatly increases the flexibility and utility of Editor, it has required that the client-server data interchange format that Editor uses has had to be updated.

This document details what has changed and why, also explaining how you can revert to the 1.4- behaviour at the expense of the multi-row editing abilities of 1.5.

What has changed?

The Ajax data interchange format that Editor uses to tell the server what editing action should be taken and also for the server to give return information to Editor about the update has been changed in 1.5 to support multi-row creation and editing. The format used for deletion of rows has also been modified to operate in a similar manner as the creation and editing format.

The new format is fully documented in the Editor manual. For reference the original 1.4- format is also documented.

Why the change?

Quite simply the original data interchange format that Editor used was designed for single row creation or editing only. With the advent of the multi-row editing feature of 1.5, the original protocol was no longer suitable.

What do I need to do?

If you are using the raw data that is exchanged between the client and server at all, then you have one of two choices:

Update your code to operate with the new data format
Use the legacyAjax option to revert Editor to the 1.4- data format. Note that this is done at the expense of multi-row editing since the original data format does provide support for editing multiple rows - an error will be thrown if multi-row editing is performed with this option enabled.

Updating code

You code will need to be updated in the following locations (if you use them):

preSubmit
postSubmit
ajax - when used as a function
ajax.data - when used as a function
The server-side code if you are not using the PHP or .NET libraries that are available as part of the Editor package.
Any server-side code that reads the raw submitted data

Use the legacy format

The change to the data interchange format can potentially be quite disruptive and the decision to make this change has not been taken lightly. However, the original format simply was not suitable for multi-row editing and thus had to be changed.

If you would like to upgrade to Editor 1.5, but not use the multi-row editing feature and restore the original data format, enable the legacyAjax option -e.g.:

new $.fn.dataTable.Editor( {
    ajax:       '/api/url',
    legacyAjax: true,
    ...
} );

If you have multiple Editor instances on a page and you wish to set this parameter by default use:

$.fn.dataTable.Editor.defaults.legacyAjax = true;

Where can I read more?

This change is obviously an important topic for Editor, and if it impacts your work you will no doubt which to read more information about the changes. You can do so in the manual:

If you have any questions about the change, please ask in the forums.