1
0
mirror of https://github.com/DataTables/DataTables.git synced 2025-02-19 17:54:14 +01:00

New: DataTables events are now all bound to the .dt namespace

- This is a breaking backwards incompatible change - please be aware of
  this!

- DataTables fires custom events such as `draw` etc, but these events
  were in no way identifyable as eminating from DataTables rather than
  some other component, which can cause confusion and difficulty
  resolving bugs.

- As such, all DataTables events are now fired with the `dt` namespace -
  this means if you are currently using events, you must update your
  code to also use the .dt namespace. If you are already using
  namespaces, that's great, you can continue to do so as jQuery allows
  multiple namespaces, but you must still use the .dt namespace.

- This is a breaking change because the old behaviour was incorrect -
  i.e. this was a bug to be fixed, hence why we haven't gone through a
  deprecation cycle. The old events weren't well documented (only in the
  JSDoc generated docs and a few of my forum posts), whereas in 1.10
  they will form a key part of the documentation. As such, now is the
  time to get this right. This will be documented clearly in the upgrade
  notes.

- Discussion on this topic here:
  https://github.com/DataTables/DataTables/issues/245
This commit is contained in:
Allan Jardine 2013-11-18 11:45:41 +00:00
parent ed4afe6178
commit 6dcc69ee54
2 changed files with 45 additions and 35 deletions

View File

@ -1 +1 @@
160619c89f156e4814065d9224f5c11342b27a80
ae0951bf93e1b87ced3c70ddf3a18ed3ae55277d

View File

@ -2217,7 +2217,7 @@
}
oSettings.json = json;
$(instance).trigger('xhr', [oSettings, json]);
_fnCallbackFire( oSettings, null, 'xhr', [oSettings, json] );
fn( json );
},
"dataType": "json",
@ -2581,7 +2581,7 @@
/* Tell the draw function we have been filtering */
oSettings.bFiltered = true;
$(oSettings.oInstance).trigger('filter search', oSettings);
_fnCallbackFire( oSettings, null, 'search', [oSettings] );
}
@ -3013,7 +3013,7 @@
_fnLengthOverflow( settings );
// Fire length change event
$(settings.oInstance).trigger( 'length', [settings, len] );
_fnCallbackFire( settings, null, 'length', [settings, len] );
}
@ -3198,7 +3198,7 @@
var changed = settings._iDisplayStart !== start;
settings._iDisplayStart = start;
$(settings.oInstance).trigger('page', settings);
_fnCallbackFire( settings, null, 'page', [settings] );
if ( redraw ) {
_fnDraw( settings );
@ -3238,7 +3238,7 @@
$(settings.aanFeatures.r).css( 'visibility', show ? 'visible' : 'hidden' );
}
$(settings.oInstance).trigger('processing', [settings, show]);
_fnCallbackFire( settings, null, 'processing', [settings, show] );
}
/**
@ -4695,14 +4695,17 @@
/**
* Fire callback functions and trigger events. Note that the loop over the callback
* array store is done backwards! Further note that you do not want to fire off triggers
* in time sensitive applications (for example cell creation) as its slow.
* @param {object} oSettings dataTables settings object
* @param {string} sStore Name of the array storage for the callbacks in oSettings
* @param {string} sTrigger Name of the jQuery custom event to trigger. If null no trigger
* is fired
* @param {array} aArgs Array of arguments to pass to the callback function / trigger
* Fire callback functions and trigger events. Note that the loop over the
* callback array store is done backwards! Further note that you do not want to
* fire off triggers in time sensitive applications (for example cell creation)
* as its slow.
* @param {object} settings dataTables settings object
* @param {string} callbackArr Name of the array storage for the callbacks in
* oSettings
* @param {string} event Name of the jQuery custom event to trigger. If null no
* trigger is fired
* @param {array} args Array of arguments to pass to the callback function /
* trigger
* @memberof DataTable#oApi
*/
function _fnCallbackFire( settings, callbackArr, event, args )
@ -4716,7 +4719,7 @@
}
if ( event !== null ) {
$(settings.oInstance).trigger(event, args);
$(settings.nTable).trigger( event+'.dt', args );
}
return ret;
@ -6026,8 +6029,7 @@
sortedColumns[ val.col ] = val.dir;
} );
$(oSettings.nTable).trigger('sort', [oSettings, aSort, sortedColumns]);
_fnCallbackFire( oSettings, null, 'sort', [oSettings, aSort, sortedColumns] );
_fnSortingClasses( oSettings );
_fnSortAria( oSettings );
}
@ -8323,9 +8325,16 @@
// jQuery functions to operate on the tables
$.each( [ 'on', 'one', 'off' ], function (i, key) {
_api_register( key+'()', function ( /* ... */ ) {
_api_register( key+'()', function ( /* event, handler */ ) {
var args = Array.prototype.slice.call(arguments);
// Add the `dt` namespace automatically if it isn't already present
if ( args[0].indexOf( '.dt' ) === -1 ) {
args[0] += '.dt';
}
var inst = $( this.tables().nodes() );
inst[key].apply( inst, arguments );
inst[key].apply( inst, args );
return this;
} );
} );
@ -8350,6 +8359,7 @@
} );
// Remove plugin methods
_api_register( 'plugin()', function ( type ) {
var ctx = this.context;
@ -13724,7 +13734,7 @@
* Draw event, fired whenever the table is redrawn on the page, at the same
* point as fnDrawCallback. This may be useful for binding events or
* performing calculations when the table is altered at all.
* @name DataTable#draw
* @name DataTable#draw.dt
* @event
* @param {event} e jQuery event object
* @param {object} o DataTables settings object {@link DataTable.models.oSettings}
@ -13733,7 +13743,7 @@
/**
* Search event, fired when the searching applied to the table (using the
* built-in global search, or column filters) is altered.
* @name DataTable#search
* @name DataTable#search.dt
* @event
* @param {event} e jQuery event object
* @param {object} o DataTables settings object {@link DataTable.models.oSettings}
@ -13741,7 +13751,7 @@
/**
* Page change event, fired when the paging of the table is altered.
* @name DataTable#page
* @name DataTable#page.dt
* @event
* @param {event} e jQuery event object
* @param {object} o DataTables settings object {@link DataTable.models.oSettings}
@ -13749,7 +13759,7 @@
/**
* Order event, fired when the ordering applied to the table is altered.
* @name DataTable#order
* @name DataTable#order.dt
* @event
* @param {event} e jQuery event object
* @param {object} o DataTables settings object {@link DataTable.models.oSettings}
@ -13758,7 +13768,7 @@
/**
* DataTables initialisation complete event, fired when the table is fully
* drawn, including Ajax data loaded, if Ajax data is required.
* @name DataTable#init
* @name DataTable#init.dt
* @event
* @param {event} e jQuery event object
* @param {object} oSettings DataTables settings object
@ -13771,7 +13781,7 @@
* is required. This event allows modification of the state saving object
* prior to actually doing the save, including addition or other state
* properties (for plug-ins) or modification of a DataTables core property.
* @name DataTable#stateSaveParams
* @name DataTable#stateSaveParams.dt
* @event
* @param {event} e jQuery event object
* @param {object} oSettings DataTables settings object
@ -13783,7 +13793,7 @@
* data, but prior to the settings object being modified by the saved state
* - allowing modification of the saved state is required or loading of
* state for a plug-in.
* @name DataTable#stateLoadParams
* @name DataTable#stateLoadParams.dt
* @event
* @param {event} e jQuery event object
* @param {object} oSettings DataTables settings object
@ -13793,7 +13803,7 @@
/**
* State loaded event, fired when state has been loaded from stored data and
* the settings object has been modified by the loaded data.
* @name DataTable#stateLoaded
* @name DataTable#stateLoaded.dt
* @event
* @param {event} e jQuery event object
* @param {object} oSettings DataTables settings object
@ -13805,7 +13815,7 @@
* (be it, order, searcg or anything else). It can be used to indicate to
* the end user that there is something happening, or that something has
* finished.
* @name DataTable#processing
* @name DataTable#processing.dt
* @event
* @param {event} e jQuery event object
* @param {object} oSettings DataTables settings object
@ -13821,7 +13831,7 @@
* Note that this trigger is called in `fnServerData`, if you override
* `fnServerData` and which to use this event, you need to trigger it in you
* success function.
* @name DataTable#xhr
* @name DataTable#xhr.dt
* @event
* @param {event} e jQuery event object
* @param {object} o DataTables settings object {@link DataTable.models.oSettings}
@ -13829,13 +13839,13 @@
*
* @example
* // Use a custom property returned from the server in another DOM element
* $('#table').dataTable().on('xhr', function (e, settings, json) {
* $('#table').dataTable().on('xhr.dt', function (e, settings, json) {
* $('#status').html( json.status );
* } );
*
* @example
* // Pre-process the data returned from the server
* $('#table').dataTable().on('xhr', function (e, settings, json) {
* $('#table').dataTable().on('xhr.dt', function (e, settings, json) {
* for ( var i=0, ien=json.aaData.length ; i<ien ; i++ ) {
* json.aaData[i].sum = json.aaData[i].one + json.aaData[i].two;
* }
@ -13847,7 +13857,7 @@
* Destroy event, fired when the DataTable is destroyed by calling fnDestroy
* or passing the bDestroy:true parameter in the initialisation object. This
* can be used to remove bound events, added DOM nodes, etc.
* @name DataTable#destroy
* @name DataTable#destroy.dt
* @event
* @param {event} e jQuery event object
* @param {object} o DataTables settings object {@link DataTable.models.oSettings}
@ -13856,7 +13866,7 @@
/**
* Page length change event, fired when number of records to show on each
* page (the length) is changed.
* @name DataTable#length
* @name DataTable#length.dt
* @event
* @param {event} e jQuery event object
* @param {object} o DataTables settings object {@link DataTable.models.oSettings}
@ -13865,7 +13875,7 @@
/**
* Column sizing has changed.
* @name DataTable#column-sizing
* @name DataTable#column-sizing.dt
* @event
* @param {event} e jQuery event object
* @param {object} o DataTables settings object {@link DataTable.models.oSettings}
@ -13873,7 +13883,7 @@
/**
* Column visibility has changed.
* @name DataTable#column-visibility
* @name DataTable#column-visibility.dt
* @event
* @param {event} e jQuery event object
* @param {object} o DataTables settings object {@link DataTable.models.oSettings}