From 48863221835a1869a2fe18cadd17164f5cdcbc84 Mon Sep 17 00:00:00 2001 From: Allan Jardine Date: Fri, 29 Jun 2012 19:37:22 +0100 Subject: [PATCH] New: mRender option for columns - this is effectively a simpiler version of mDataProp for reading data only (while mDataProp also sets data), and much more comprhensive than fnRender (as such fnRender is now offically deprecated). See the documentation comments in model.defaults.columns.js for further information on how to use mRender. --- media/js/jquery.dataTables.js | 109 ++++++++++++++++++++-- media/src/core/core.columns.js | 13 ++- media/src/core/core.data.js | 10 +- media/src/model/model.column.js | 10 ++ media/src/model/model.defaults.columns.js | 76 ++++++++++++++- 5 files changed, 204 insertions(+), 14 deletions(-) diff --git a/media/js/jquery.dataTables.js b/media/js/jquery.dataTables.js index 74d46677..6a969cc5 100644 --- a/media/js/jquery.dataTables.js +++ b/media/js/jquery.dataTables.js @@ -145,7 +145,18 @@ } /* Cache the data get and set functions for speed */ - oCol.fnGetData = _fnGetObjectDataFn( oCol.mDataProp ); + var mRender = oCol.mRender ? _fnGetObjectDataFn( oCol.mRender ) : null; + var mData = _fnGetObjectDataFn( oCol.mDataProp ); + + oCol.fnGetData = function (oData, sSpecific) { + var innerData = mData( oData, sSpecific ); + + if ( oCol.mRender && (sSpecific && sSpecific !== '') ) + { + return mRender( innerData, sSpecific, oData ); + } + return innerData; + }; oCol.fnSetData = _fnSetObjectDataFn( oCol.mDataProp ); /* Feature sorting overrides column specific when off */ @@ -806,8 +817,8 @@ } else if ( typeof mSource === 'function' ) { - return function (data, type) { - return mSource( data, type ); + return function (data, type, extra) { + return mSource( data, type, extra ); }; } else if ( typeof mSource === 'string' && (mSource.indexOf('.') !== -1 || mSource.indexOf('[') !== -1) ) @@ -831,7 +842,11 @@ if ( arrayNotation ) { a[i] = a[i].replace(__reArray, ''); - data = data[ a[i] ]; + + // Condition allows simply [] to be passed in + if ( a[i] !== "" ) { + data = data[ a[i] ]; + } out = []; // Get the remainder of the nested object to get @@ -7634,6 +7649,16 @@ */ "mDataProp": null, + /** + * Partner property to mDataProp which is used (only when defined) to get + * the data - i.e. it is basically the same as mDataProp, but without the + * 'set' option, and also the data fed to it is the result from mDataProp. + * This is the rendering method to match the data method of mDataProp. + * @type function|int|string|null + * @default null + */ + "mRender": null, + /** * Unique header TH/TD element for this column - this is what the sorting * listener is attached to (if sorting is enabled.) @@ -9830,12 +9855,12 @@ * (before rendering) for sorting and filtering (the default is to used the * rendered data that the user can see). This may be useful for dates etc. * - * *NOTE* It is it is advisable now to use mDataProp as a function and make - * use of the 'type' that it gives, allowing (potentially) different data to - * be used for sorting, filtering, display and type detection. + * *NOTE* This property is now deprecated, and it is suggested that you use + * mDataProp and / or mRender to render data for the DataTable. * @type boolean * @default true * @dtopt Columns + * @deprecated * * @example * // Using aoColumnDefs @@ -10099,6 +10124,76 @@ "mDataProp": null, + + /** + * This property is the rendering partner to mDataProp and it is suggested that + * when you want to manipulate data for display (including filtering, sorting etc) + * but not altering the underlying data for the table, use this property. mDataProp + * can actually do everything this property can and more, but this parameter is + * easier to use since there is no 'set' option. Like mDataProp is can be given + * in a number of different ways to effect its behaviour, with the addition of + * supporting array syntax for easy outputting of arrays (including arrays of + * objects): + * + * @type string|int|function|null + * @default null Use mDataProp + * @dtopt Columns + * + * @example + * // Create a comma separated list from an array of objects + * $(document).ready(function() { + * var oTable = $('#example').dataTable( { + * "sAjaxSource": "sources/deep.txt", + * "aoColumns": [ + * { "mDataProp": "engine" }, + * { "mDataProp": "browser" }, + * { + * "mDataProp": "platform", + * "mRender": "[, ].name" + * } + * ] + * } ); + * } ); + * + * @example + * // Use as a function to create a link from the data source + * $(document).ready(function() { + * var oTable = $('#example').dataTable( { + * "aoColumnDefs": [ + * { + * "aTargets": [ 0 ], + * "mDataProp": "download_link", + * "mRender": function ( data, type, full ) { + * return 'Download'; + * } + * ] + * } ); + * } ); + */ + "mRender": null, + + /** * Change the cell type created for the column - either TD cells or TH cells. This * can be useful as TH cells have semantic meaning in the table body, allowing them diff --git a/media/src/core/core.columns.js b/media/src/core/core.columns.js index aef8abe8..ff139fa5 100644 --- a/media/src/core/core.columns.js +++ b/media/src/core/core.columns.js @@ -85,7 +85,18 @@ function _fnColumnOptions( oSettings, iCol, oOptions ) } /* Cache the data get and set functions for speed */ - oCol.fnGetData = _fnGetObjectDataFn( oCol.mDataProp ); + var mRender = oCol.mRender ? _fnGetObjectDataFn( oCol.mRender ) : null; + var mData = _fnGetObjectDataFn( oCol.mDataProp ); + + oCol.fnGetData = function (oData, sSpecific) { + var innerData = mData( oData, sSpecific ); + + if ( oCol.mRender && (sSpecific && sSpecific !== '') ) + { + return mRender( innerData, sSpecific, oData ); + } + return innerData; + }; oCol.fnSetData = _fnSetObjectDataFn( oCol.mDataProp ); /* Feature sorting overrides column specific when off */ diff --git a/media/src/core/core.data.js b/media/src/core/core.data.js index 51c458c8..514fe6a0 100644 --- a/media/src/core/core.data.js +++ b/media/src/core/core.data.js @@ -381,8 +381,8 @@ function _fnGetObjectDataFn( mSource ) } else if ( typeof mSource === 'function' ) { - return function (data, type) { - return mSource( data, type ); + return function (data, type, extra) { + return mSource( data, type, extra ); }; } else if ( typeof mSource === 'string' && (mSource.indexOf('.') !== -1 || mSource.indexOf('[') !== -1) ) @@ -406,7 +406,11 @@ function _fnGetObjectDataFn( mSource ) if ( arrayNotation ) { a[i] = a[i].replace(__reArray, ''); - data = data[ a[i] ]; + + // Condition allows simply [] to be passed in + if ( a[i] !== "" ) { + data = data[ a[i] ]; + } out = []; // Get the remainder of the nested object to get diff --git a/media/src/model/model.column.js b/media/src/model/model.column.js index 0f440cf8..aa3b18e4 100644 --- a/media/src/model/model.column.js +++ b/media/src/model/model.column.js @@ -142,6 +142,16 @@ DataTable.models.oColumn = { */ "mDataProp": null, + /** + * Partner property to mDataProp which is used (only when defined) to get + * the data - i.e. it is basically the same as mDataProp, but without the + * 'set' option, and also the data fed to it is the result from mDataProp. + * This is the rendering method to match the data method of mDataProp. + * @type function|int|string|null + * @default null + */ + "mRender": null, + /** * Unique header TH/TD element for this column - this is what the sorting * listener is attached to (if sorting is enabled.) diff --git a/media/src/model/model.defaults.columns.js b/media/src/model/model.defaults.columns.js index 4828e02a..64fa9de8 100644 --- a/media/src/model/model.defaults.columns.js +++ b/media/src/model/model.defaults.columns.js @@ -146,12 +146,12 @@ DataTable.defaults.columns = { * (before rendering) for sorting and filtering (the default is to used the * rendered data that the user can see). This may be useful for dates etc. * - * *NOTE* It is it is advisable now to use mDataProp as a function and make - * use of the 'type' that it gives, allowing (potentially) different data to - * be used for sorting, filtering, display and type detection. + * *NOTE* This property is now deprecated, and it is suggested that you use + * mDataProp and / or mRender to render data for the DataTable. * @type boolean * @default true * @dtopt Columns + * @deprecated * * @example * // Using aoColumnDefs @@ -415,6 +415,76 @@ DataTable.defaults.columns = { "mDataProp": null, + + /** + * This property is the rendering partner to mDataProp and it is suggested that + * when you want to manipulate data for display (including filtering, sorting etc) + * but not altering the underlying data for the table, use this property. mDataProp + * can actually do everything this property can and more, but this parameter is + * easier to use since there is no 'set' option. Like mDataProp is can be given + * in a number of different ways to effect its behaviour, with the addition of + * supporting array syntax for easy outputting of arrays (including arrays of + * objects): + * + * @type string|int|function|null + * @default null Use mDataProp + * @dtopt Columns + * + * @example + * // Create a comma separated list from an array of objects + * $(document).ready(function() { + * var oTable = $('#example').dataTable( { + * "sAjaxSource": "sources/deep.txt", + * "aoColumns": [ + * { "mDataProp": "engine" }, + * { "mDataProp": "browser" }, + * { + * "mDataProp": "platform", + * "mRender": "[, ].name" + * } + * ] + * } ); + * } ); + * + * @example + * // Use as a function to create a link from the data source + * $(document).ready(function() { + * var oTable = $('#example').dataTable( { + * "aoColumnDefs": [ + * { + * "aTargets": [ 0 ], + * "mDataProp": "download_link", + * "mRender": function ( data, type, full ) { + * return 'Download'; + * } + * ] + * } ); + * } ); + */ + "mRender": null, + + /** * Change the cell type created for the column - either TD cells or TH cells. This * can be useful as TH cells have semantic meaning in the table body, allowing them