From a264ca66e9853c94e87b374a69642cb37c4f08ea Mon Sep 17 00:00:00 2001
From: Allan Jardine <allan.jardine@sprymedia.co.uk>
Date: Tue, 6 Dec 2011 14:48:49 +0000
Subject: [PATCH] New: fnCreatedCell option for columns - this function is a
 compliment to fnRender, but in this case it is called when the cell is
 available (unlike fnRender). This allows DOM manipulation of the cell (or
 possibly the row as the parentNode if you so wished), such as adding a cell
 based on the cell data, or any other DOM manipulation.

---
 media/js/jquery.dataTables.js         | 68 +++++++++++++++++++--------
 media/src/core/core.columns.js        |  1 +
 media/src/core/core.data.js           | 49 +++++++++++--------
 media/src/core/core.draw.js           |  7 +++
 media/src/model/model.column.js       | 11 +++++
 media/src/model/model.init.columns.js | 28 +++++++++++
 6 files changed, 126 insertions(+), 38 deletions(-)

diff --git a/media/js/jquery.dataTables.js b/media/js/jquery.dataTables.js
index c800e4d9..f9a2d114 100644
--- a/media/js/jquery.dataTables.js
+++ b/media/js/jquery.dataTables.js
@@ -152,6 +152,7 @@
 				_fnMap( oCol, oOptions, "sWidth", "sWidthOrig" );
 				_fnMap( oCol, oOptions, "sClass" );
 				_fnMap( oCol, oOptions, "fnRender" );
+				_fnMap( oCol, oOptions, "fnCreatedCell" );
 				_fnMap( oCol, oOptions, "bUseRendered" );
 				_fnMap( oCol, oOptions, "mDataProp" );
 				_fnMap( oCol, oOptions, "asSorting" );
@@ -462,7 +463,8 @@
 		{
 			var iLoop, i, iLen, j, jLen, jInner,
 			 	nTds, nTrs, nTd, aLocalData, iThisIndex,
-				iRow, iRows, iColumn, iColumns, sNodeName;
+				iRow, iRows, iColumn, iColumns, sNodeName,
+				oCol, oData;
 			
 			/*
 			 * Process by row first
@@ -529,17 +531,19 @@
 			/* Now process by column */
 			for ( iColumn=0, iColumns=oSettings.aoColumns.length ; iColumn<iColumns ; iColumn++ )
 			{
+				oCol = oSettings.aoColumns[iColumn];
+		
 				/* Get the title of the column - unless there is a user set one */
-				if ( oSettings.aoColumns[iColumn].sTitle === null )
+				if ( oCol.sTitle === null )
 				{
-					oSettings.aoColumns[iColumn].sTitle = oSettings.aoColumns[iColumn].nTh.innerHTML;
+					oCol.sTitle = oCol.nTh.innerHTML;
 				}
 				
 				var
-					bAutoType = oSettings.aoColumns[iColumn]._bAutoType,
-					bRender = typeof oSettings.aoColumns[iColumn].fnRender == 'function',
-					bClass = oSettings.aoColumns[iColumn].sClass !== null,
-					bVisible = oSettings.aoColumns[iColumn].bVisible,
+					bAutoType = oCol._bAutoType,
+					bRender = typeof oCol.fnRender == 'function',
+					bClass = oCol.sClass !== null,
+					bVisible = oCol.bVisible,
 					nCell, sThisType, sRendered, sValType;
 				
 				/* A single loop to rule them all (and be more efficient) */
@@ -547,24 +551,25 @@
 				{
 					for ( iRow=0, iRows=oSettings.aoData.length ; iRow<iRows ; iRow++ )
 					{
+						oData = oSettings.aoData[iRow];
 						nCell = nTds[ (iRow*iColumns) + iColumn ];
 						
 						/* Type detection */
-						if ( bAutoType && oSettings.aoColumns[iColumn].sType != 'string' )
+						if ( bAutoType && oCol.sType != 'string' )
 						{
 							sValType = _fnGetCellData( oSettings, iRow, iColumn, 'type' );
 							if ( sValType !== '' )
 							{
 								sThisType = _fnDetectType( sValType );
-								if ( oSettings.aoColumns[iColumn].sType === null )
+								if ( oCol.sType === null )
 								{
-									oSettings.aoColumns[iColumn].sType = sThisType;
+									oCol.sType = sThisType;
 								}
-								else if ( oSettings.aoColumns[iColumn].sType != sThisType && 
-								          oSettings.aoColumns[iColumn].sType != "html" )
+								else if ( oCol.sType != sThisType && 
+								          oCol.sType != "html" )
 								{
 									/* String is always the 'fallback' option */
-									oSettings.aoColumns[iColumn].sType = 'string';
+									oCol.sType = 'string';
 								}
 							}
 						}
@@ -572,14 +577,14 @@
 						/* Rendering */
 						if ( bRender )
 						{
-							sRendered = oSettings.aoColumns[iColumn].fnRender( {
+							sRendered = oCol.fnRender( {
 									"iDataRow": iRow,
 									"iDataColumn": iColumn,
-									"aData": oSettings.aoData[iRow]._aData,
+									"aData": oData._aData,
 									"oSettings": oSettings
 								} );
 							nCell.innerHTML = sRendered;
-							if ( oSettings.aoColumns[iColumn].bUseRendered )
+							if ( oCol.bUseRendered )
 							{
 								/* Use the rendered data for filtering/sorting */
 								_fnSetCellData( oSettings, iRow, iColumn, sRendered );
@@ -589,18 +594,25 @@
 						/* Classes */
 						if ( bClass )
 						{
-							nCell.className += ' '+oSettings.aoColumns[iColumn].sClass;
+							nCell.className += ' '+oCol.sClass;
 						}
 						
 						/* Column visability */
 						if ( !bVisible )
 						{
-							oSettings.aoData[iRow]._anHidden[iColumn] = nCell;
+							oData._anHidden[iColumn] = nCell;
 							nCell.parentNode.removeChild( nCell );
 						}
 						else
 						{
-							oSettings.aoData[iRow]._anHidden[iColumn] = null;
+							oData._anHidden[iColumn] = null;
+						}
+		
+						if ( oCol.fnCreatedCell )
+						{
+							oCol.fnCreatedCell.call( oSettings.oInstance,
+								nCell, _fnGetCellData( oSettings, iRow, iColumn, 'display' ), oData._aData, iRow
+							);
 						}
 					}
 				}
@@ -971,6 +983,13 @@
 					{
 						oData._anHidden[i] = nTd;
 					}
+		
+					if ( oCol.fnCreatedCell )
+					{
+						oCol.fnCreatedCell.call( oSettings.oInstance,
+								nTd, _fnGetCellData( oSettings, iRow, i, 'display' ), oData._aData, iRow
+						);
+					}
 				}
 			}
 		}
@@ -7067,6 +7086,17 @@
 		 */
 		"_bAutoType": true,
 		
+		/**
+		 * 
+		 *  @type function
+		 *  @param {element} nTd The TD node that has been created
+		 *  @param {*} sData The Data for the cell
+		 *  @param {array|object} oData The data for the whole row
+		 *  @param {int} iRow The row index for the aoData data store
+		 *  @default null
+		 */
+		"fnCreatedCell": null,
+		
 		/**
 		 * Function to get data from a cell in a column. You should <b>never</b>
 		 * access data directly through _aData internally in DataTables - always use
diff --git a/media/src/core/core.columns.js b/media/src/core/core.columns.js
index 8829568c..5f1c3413 100644
--- a/media/src/core/core.columns.js
+++ b/media/src/core/core.columns.js
@@ -91,6 +91,7 @@ function _fnColumnOptions( oSettings, iCol, oOptions )
 		_fnMap( oCol, oOptions, "sWidth", "sWidthOrig" );
 		_fnMap( oCol, oOptions, "sClass" );
 		_fnMap( oCol, oOptions, "fnRender" );
+		_fnMap( oCol, oOptions, "fnCreatedCell" );
 		_fnMap( oCol, oOptions, "bUseRendered" );
 		_fnMap( oCol, oOptions, "mDataProp" );
 		_fnMap( oCol, oOptions, "asSorting" );
diff --git a/media/src/core/core.data.js b/media/src/core/core.data.js
index 7e6f4394..ee816483 100644
--- a/media/src/core/core.data.js
+++ b/media/src/core/core.data.js
@@ -85,7 +85,8 @@ function _fnGatherData( oSettings )
 {
 	var iLoop, i, iLen, j, jLen, jInner,
 	 	nTds, nTrs, nTd, aLocalData, iThisIndex,
-		iRow, iRows, iColumn, iColumns, sNodeName;
+		iRow, iRows, iColumn, iColumns, sNodeName,
+		oCol, oData;
 	
 	/*
 	 * Process by row first
@@ -152,17 +153,19 @@ function _fnGatherData( oSettings )
 	/* Now process by column */
 	for ( iColumn=0, iColumns=oSettings.aoColumns.length ; iColumn<iColumns ; iColumn++ )
 	{
+		oCol = oSettings.aoColumns[iColumn];
+
 		/* Get the title of the column - unless there is a user set one */
-		if ( oSettings.aoColumns[iColumn].sTitle === null )
+		if ( oCol.sTitle === null )
 		{
-			oSettings.aoColumns[iColumn].sTitle = oSettings.aoColumns[iColumn].nTh.innerHTML;
+			oCol.sTitle = oCol.nTh.innerHTML;
 		}
 		
 		var
-			bAutoType = oSettings.aoColumns[iColumn]._bAutoType,
-			bRender = typeof oSettings.aoColumns[iColumn].fnRender == 'function',
-			bClass = oSettings.aoColumns[iColumn].sClass !== null,
-			bVisible = oSettings.aoColumns[iColumn].bVisible,
+			bAutoType = oCol._bAutoType,
+			bRender = typeof oCol.fnRender == 'function',
+			bClass = oCol.sClass !== null,
+			bVisible = oCol.bVisible,
 			nCell, sThisType, sRendered, sValType;
 		
 		/* A single loop to rule them all (and be more efficient) */
@@ -170,24 +173,25 @@ function _fnGatherData( oSettings )
 		{
 			for ( iRow=0, iRows=oSettings.aoData.length ; iRow<iRows ; iRow++ )
 			{
+				oData = oSettings.aoData[iRow];
 				nCell = nTds[ (iRow*iColumns) + iColumn ];
 				
 				/* Type detection */
-				if ( bAutoType && oSettings.aoColumns[iColumn].sType != 'string' )
+				if ( bAutoType && oCol.sType != 'string' )
 				{
 					sValType = _fnGetCellData( oSettings, iRow, iColumn, 'type' );
 					if ( sValType !== '' )
 					{
 						sThisType = _fnDetectType( sValType );
-						if ( oSettings.aoColumns[iColumn].sType === null )
+						if ( oCol.sType === null )
 						{
-							oSettings.aoColumns[iColumn].sType = sThisType;
+							oCol.sType = sThisType;
 						}
-						else if ( oSettings.aoColumns[iColumn].sType != sThisType && 
-						          oSettings.aoColumns[iColumn].sType != "html" )
+						else if ( oCol.sType != sThisType && 
+						          oCol.sType != "html" )
 						{
 							/* String is always the 'fallback' option */
-							oSettings.aoColumns[iColumn].sType = 'string';
+							oCol.sType = 'string';
 						}
 					}
 				}
@@ -195,14 +199,14 @@ function _fnGatherData( oSettings )
 				/* Rendering */
 				if ( bRender )
 				{
-					sRendered = oSettings.aoColumns[iColumn].fnRender( {
+					sRendered = oCol.fnRender( {
 							"iDataRow": iRow,
 							"iDataColumn": iColumn,
-							"aData": oSettings.aoData[iRow]._aData,
+							"aData": oData._aData,
 							"oSettings": oSettings
 						} );
 					nCell.innerHTML = sRendered;
-					if ( oSettings.aoColumns[iColumn].bUseRendered )
+					if ( oCol.bUseRendered )
 					{
 						/* Use the rendered data for filtering/sorting */
 						_fnSetCellData( oSettings, iRow, iColumn, sRendered );
@@ -212,18 +216,25 @@ function _fnGatherData( oSettings )
 				/* Classes */
 				if ( bClass )
 				{
-					nCell.className += ' '+oSettings.aoColumns[iColumn].sClass;
+					nCell.className += ' '+oCol.sClass;
 				}
 				
 				/* Column visability */
 				if ( !bVisible )
 				{
-					oSettings.aoData[iRow]._anHidden[iColumn] = nCell;
+					oData._anHidden[iColumn] = nCell;
 					nCell.parentNode.removeChild( nCell );
 				}
 				else
 				{
-					oSettings.aoData[iRow]._anHidden[iColumn] = null;
+					oData._anHidden[iColumn] = null;
+				}
+
+				if ( oCol.fnCreatedCell )
+				{
+					oCol.fnCreatedCell.call( oSettings.oInstance,
+						nCell, _fnGetCellData( oSettings, iRow, iColumn, 'display' ), oData._aData, iRow
+					);
 				}
 			}
 		}
diff --git a/media/src/core/core.draw.js b/media/src/core/core.draw.js
index 28025a22..df3f96ea 100644
--- a/media/src/core/core.draw.js
+++ b/media/src/core/core.draw.js
@@ -64,6 +64,13 @@ function _fnCreateTr ( oSettings, iRow )
 			{
 				oData._anHidden[i] = nTd;
 			}
+
+			if ( oCol.fnCreatedCell )
+			{
+				oCol.fnCreatedCell.call( oSettings.oInstance,
+						nTd, _fnGetCellData( oSettings, iRow, i, 'display' ), oData._aData, iRow
+				);
+			}
 		}
 	}
 }
diff --git a/media/src/model/model.column.js b/media/src/model/model.column.js
index 9183e94f..f9751288 100644
--- a/media/src/model/model.column.js
+++ b/media/src/model/model.column.js
@@ -82,6 +82,17 @@ DataTable.models.oColumn = {
 	 */
 	"_bAutoType": true,
 	
+	/**
+	 * 
+	 *  @type function
+	 *  @param {element} nTd The TD node that has been created
+	 *  @param {*} sData The Data for the cell
+	 *  @param {array|object} oData The data for the whole row
+	 *  @param {int} iRow The row index for the aoData data store
+	 *  @default null
+	 */
+	"fnCreatedCell": null,
+	
 	/**
 	 * Function to get data from a cell in a column. You should <b>never</b>
 	 * access data directly through _aData internally in DataTables - always use
diff --git a/media/src/model/model.init.columns.js b/media/src/model/model.init.columns.js
index 1b40b81a..7dc87263 100644
--- a/media/src/model/model.init.columns.js
+++ b/media/src/model/model.init.columns.js
@@ -210,6 +210,34 @@ DataTable.models.oInitColumns = {
 	 *    } );
 	 */
 	"bVisible": true,
+	
+	
+	/**
+	 * Developer definable function that is called whenever a cell is created (Ajax source,
+	 * etc) or processed for input (DOM source). This can be used as a compliment to fnRender
+	 * allowing you to modify the DOM element (add background colour for example) when the
+	 * element is available (since it is not when fnRender is called).
+	 *  @type function
+	 *  @param {element} nTd The TD node that has been created
+	 *  @param {*} sData The Data for the cell
+	 *  @param {array|object} oData The data for the whole row
+	 *  @param {int} iRow The row index for the aoData data store
+	 * 
+	 *  @example
+	 *    $(document).ready(function() {
+	 *      $('#example').dataTable( {
+	 *        "aoColumnDefs": [ {
+	 *          "aTargets": [3],
+	 *          "fnCreatedCell": function (nTd, sData, oData, i) {
+	 *            if ( sData == "1.7" ) {
+	 *              $(nTd).css('color', 'blue')
+	 *            }
+	 *          }
+	 *        } ]
+	 *      });
+	 *    } );
+	 */
+	"fnCreatedCell": null,
 
 
 	/**