src/core/core.columns.js



/**
 * Add a column to the list used for the table with default values
 *  @param {object} oSettings dataTables settings object
 *  @param {node} nTh The th element for this column
 *  @memberof DataTable#oApi
 */
function _fnAddColumn( oSettings, nTh )
{
        var oDefaults = DataTable.defaults.columns;
        var iCol = oSettings.aoColumns.length;
        var oCol = $.extend( {}, DataTable.models.oColumn, oDefaults, {
                "sSortingClass": oSettings.oClasses.sSortable,
                "sSortingClassJUI": oSettings.oClasses.sSortJUI,
                "nTh": nTh ? nTh : document.createElement('th'),
                "sTitle":    oDefaults.sTitle    ? oDefaults.sTitle    : nTh ? nTh.innerHTML : '',
                "aDataSort": oDefaults.aDataSort ? oDefaults.aDataSort : [iCol],
                "mData": oDefaults.mData ? oDefaults.oDefaults : iCol
        } );
        oSettings.aoColumns.push( oCol );
        
        /* Add a column specific filter */
        if ( oSettings.aoPreSearchCols[ iCol ] === undefined || oSettings.aoPreSearchCols[ iCol ] === null )
        {
                oSettings.aoPreSearchCols[ iCol ] = $.extend( {}, DataTable.models.oSearch );
        }
        else
        {
                var oPre = oSettings.aoPreSearchCols[ iCol ];
                
                /* Don't require that the user must specify bRegex, bSmart or bCaseInsensitive */
                if ( oPre.bRegex === undefined )
                {
                        oPre.bRegex = true;
                }
                
                if ( oPre.bSmart === undefined )
                {
                        oPre.bSmart = true;
                }
                
                if ( oPre.bCaseInsensitive === undefined )
                {
                        oPre.bCaseInsensitive = true;
                }
        }
        
        /* Use the column options function to initialise classes etc */
        _fnColumnOptions( oSettings, iCol, null );
}


/**
 * Apply options for a column
 *  @param {object} oSettings dataTables settings object
 *  @param {int} iCol column index to consider
 *  @param {object} oOptions object with sType, bVisible and bSearchable etc
 *  @memberof DataTable#oApi
 */
function _fnColumnOptions( oSettings, iCol, oOptions )
{
        var oCol = oSettings.aoColumns[ iCol ];
        
        /* User specified column options */
        if ( oOptions !== undefined && oOptions !== null )
        {
                /* Backwards compatibility for mDataProp */
                if ( oOptions.mDataProp && !oOptions.mData )
                {
                        oOptions.mData = oOptions.mDataProp;
                }

                if ( oOptions.sType !== undefined )
                {
                        oCol.sType = oOptions.sType;
                        oCol._bAutoType = false;
                }
                
                $.extend( oCol, oOptions );
                _fnMap( oCol, oOptions, "sWidth", "sWidthOrig" );

                /* iDataSort to be applied (backwards compatibility), but aDataSort will take
                 * priority if defined
                 */
                if ( oOptions.iDataSort !== undefined )
                {
                        oCol.aDataSort = [ oOptions.iDataSort ];
                }
                _fnMap( oCol, oOptions, "aDataSort" );
        }

        /* Cache the data get and set functions for speed */
        var mRender = oCol.mRender ? _fnGetObjectDataFn( oCol.mRender ) : null;
        var mData = _fnGetObjectDataFn( oCol.mData );

        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.mData );
        
        /* Feature sorting overrides column specific when off */
        if ( !oSettings.oFeatures.bSort )
        {
                oCol.bSortable = false;
        }
        
        /* Check that the class assignment is correct for sorting */
        if ( !oCol.bSortable ||
                 ($.inArray('asc', oCol.asSorting) == -1 && $.inArray('desc', oCol.asSorting) == -1) )
        {
                oCol.sSortingClass = oSettings.oClasses.sSortableNone;
                oCol.sSortingClassJUI = "";
        }
        else if ( $.inArray('asc', oCol.asSorting) == -1 && $.inArray('desc', oCol.asSorting) == -1 )
        {
                oCol.sSortingClass = oSettings.oClasses.sSortable;
                oCol.sSortingClassJUI = oSettings.oClasses.sSortJUI;
        }
        else if ( $.inArray('asc', oCol.asSorting) != -1 && $.inArray('desc', oCol.asSorting) == -1 )
        {
                oCol.sSortingClass = oSettings.oClasses.sSortableAsc;
                oCol.sSortingClassJUI = oSettings.oClasses.sSortJUIAscAllowed;
        }
        else if ( $.inArray('asc', oCol.asSorting) == -1 && $.inArray('desc', oCol.asSorting) != -1 )
        {
                oCol.sSortingClass = oSettings.oClasses.sSortableDesc;
                oCol.sSortingClassJUI = oSettings.oClasses.sSortJUIDescAllowed;
        }
}


/**
 * Adjust the table column widths for new data. Note: you would probably want to 
 * do a redraw after calling this function!
 *  @param {object} oSettings dataTables settings object
 *  @memberof DataTable#oApi
 */
function _fnAdjustColumnSizing ( oSettings )
{
        /* Not interested in doing column width calculation if auto-width is disabled */
        if ( oSettings.oFeatures.bAutoWidth === false )
        {
                return false;
        }
        
        _fnCalculateColumnWidths( oSettings );
        for ( var i=0 , iLen=oSettings.aoColumns.length ; i<iLen ; i++ )
        {
                oSettings.aoColumns[i].nTh.style.width = oSettings.aoColumns[i].sWidth;
        }
}


/**
 * Covert the index of a visible column to the index in the data array (take account
 * of hidden columns)
 *  @param {object} oSettings dataTables settings object
 *  @param {int} iMatch Visible column index to lookup
 *  @returns {int} i the data index
 *  @memberof DataTable#oApi
 */
function _fnVisibleToColumnIndex( oSettings, iMatch )
{
        var aiVis = _fnGetColumns( oSettings, 'bVisible' );

        return typeof aiVis[iMatch] === 'number' ?
                aiVis[iMatch] :
                null;
}


/**
 * Covert the index of an index in the data array and convert it to the visible
 *   column index (take account of hidden columns)
 *  @param {int} iMatch Column index to lookup
 *  @param {object} oSettings dataTables settings object
 *  @returns {int} i the data index
 *  @memberof DataTable#oApi
 */
function _fnColumnIndexToVisible( oSettings, iMatch )
{
        var aiVis = _fnGetColumns( oSettings, 'bVisible' );
        var iPos = $.inArray( iMatch, aiVis );

        return iPos !== -1 ? iPos : null;
}


/**
 * Get the number of visible columns
 *  @param {object} oSettings dataTables settings object
 *  @returns {int} i the number of visible columns
 *  @memberof DataTable#oApi
 */
function _fnVisbleColumns( oSettings )
{
        return _fnGetColumns( oSettings, 'bVisible' ).length;
}


/**
 * Get an array of column indexes that match a given property
 *  @param {object} oSettings dataTables settings object
 *  @param {string} sParam Parameter in aoColumns to look for - typically 
 *    bVisible or bSearchable
 *  @returns {array} Array of indexes with matched properties
 *  @memberof DataTable#oApi
 */
function _fnGetColumns( oSettings, sParam )
{
        var a = [];

        $.map( oSettings.aoColumns, function(val, i) {
                if ( val[sParam] ) {
                        a.push( i );
                }
        } );

        return a;
}


/**
 * Get the sort type based on an input string
 *  @param {string} sData data we wish to know the type of
 *  @returns {string} type (defaults to 'string' if no type can be detected)
 *  @memberof DataTable#oApi
 */
function _fnDetectType( sData )
{
        var aTypes = DataTable.ext.aTypes;
        var iLen = aTypes.length;
        
        for ( var i=0 ; i<iLen ; i++ )
        {
                var sType = aTypes[i]( sData );
                if ( sType !== null )
                {
                        return sType;
                }
        }
        
        return 'string';
}


/**
 * Figure out how to reorder a display list
 *  @param {object} oSettings dataTables settings object
 *  @returns array {int} aiReturn index list for reordering
 *  @memberof DataTable#oApi
 */
function _fnReOrderIndex ( oSettings, sColumns )
{
        var aColumns = sColumns.split(',');
        var aiReturn = [];
        
        for ( var i=0, iLen=oSettings.aoColumns.length ; i<iLen ; i++ )
        {
                for ( var j=0 ; j<iLen ; j++ )
                {
                        if ( oSettings.aoColumns[i].sName == aColumns[j] )
                        {
                                aiReturn.push( j );
                                break;
                        }
                }
        }
        
        return aiReturn;
}


/**
 * Get the column ordering that DataTables expects
 *  @param {object} oSettings dataTables settings object
 *  @returns {string} comma separated list of names
 *  @memberof DataTable#oApi
 */
function _fnColumnOrdering ( oSettings )
{
        var sNames = '';
        for ( var i=0, iLen=oSettings.aoColumns.length ; i<iLen ; i++ )
        {
                sNames += oSettings.aoColumns[i].sName+',';
        }
        if ( sNames.length == iLen )
        {
                return "";
        }
        return sNames.slice(0, -1);
}


/**
 * Take the column definitions and static columns arrays and calculate how
 * they relate to column indexes. The callback function will then apply the
 * definition found for a column to a suitable configuration object.
 *  @param {object} oSettings dataTables settings object
 *  @param {array} aoColDefs The aoColumnDefs array that is to be applied
 *  @param {array} aoCols The aoColumns array that defines columns individually
 *  @param {function} fn Callback function - takes two parameters, the calculated
 *    column index and the definition for that column.
 *  @memberof DataTable#oApi
 */
function _fnApplyColumnDefs( oSettings, aoColDefs, aoCols, fn )
{
        var i, iLen, j, jLen, k, kLen;

        // Column definitions with aTargets
        if ( aoColDefs )
        {
                /* Loop over the definitions array - loop in reverse so first instance has priority */
                for ( i=aoColDefs.length-1 ; i>=0 ; i-- )
                {
                        /* Each definition can target multiple columns, as it is an array */
                        var aTargets = aoColDefs[i].aTargets;
                        if ( !$.isArray( aTargets ) )
                        {
                                _fnLog( oSettings, 1, 'aTargets must be an array of targets, not a '+(typeof aTargets) );
                        }

                        for ( j=0, jLen=aTargets.length ; j<jLen ; j++ )
                        {
                                if ( typeof aTargets[j] === 'number' && aTargets[j] >= 0 )
                                {
                                        /* Add columns that we don't yet know about */
                                        while( oSettings.aoColumns.length <= aTargets[j] )
                                        {
                                                _fnAddColumn( oSettings );
                                        }

                                        /* Integer, basic index */
                                        fn( aTargets[j], aoColDefs[i] );
                                }
                                else if ( typeof aTargets[j] === 'number' && aTargets[j] < 0 )
                                {
                                        /* Negative integer, right to left column counting */
                                        fn( oSettings.aoColumns.length+aTargets[j], aoColDefs[i] );
                                }
                                else if ( typeof aTargets[j] === 'string' )
                                {
                                        /* Class name matching on TH element */
                                        for ( k=0, kLen=oSettings.aoColumns.length ; k<kLen ; k++ )
                                        {
                                                if ( aTargets[j] == "_all" ||
                                                     $(oSettings.aoColumns[k].nTh).hasClass( aTargets[j] ) )
                                                {
                                                        fn( k, aoColDefs[i] );
                                                }
                                        }
                                }
                        }
                }
        }

        // Statically defined columns array
        if ( aoCols )
        {
                for ( i=0, iLen=aoCols.length ; i<iLen ; i++ )
                {
                        fn( i, aoCols[i] );
                }
        }
}
1
2
3	/**
4	* Add a column to the list used for the table with default values
5	* @param {object} oSettings dataTables settings object
6	* @param {node} nTh The th element for this column
7	* @memberof DataTable#oApi
8	*/
9	function _fnAddColumn( oSettings, nTh )
10	{
11	var oDefaults = DataTable.defaults.columns;
12	var iCol = oSettings.aoColumns.length;
13	var oCol = $.extend( {}, DataTable.models.oColumn, oDefaults, {
14	"sSortingClass": oSettings.oClasses.sSortable,
15	"sSortingClassJUI": oSettings.oClasses.sSortJUI,
16	"nTh": nTh ? nTh : document.createElement('th'),
17	"sTitle": oDefaults.sTitle ? oDefaults.sTitle : nTh ? nTh.innerHTML : '',
18	"aDataSort": oDefaults.aDataSort ? oDefaults.aDataSort : [iCol],
19	"mData": oDefaults.mData ? oDefaults.oDefaults : iCol
20	} );
21	oSettings.aoColumns.push( oCol );
22
23	/* Add a column specific filter */
24	if ( oSettings.aoPreSearchCols[ iCol ] === undefined \|\| oSettings.aoPreSearchCols[ iCol ] === null )
25	{
26	oSettings.aoPreSearchCols[ iCol ] = $.extend( {}, DataTable.models.oSearch );
27	}
28	else
29	{
30	var oPre = oSettings.aoPreSearchCols[ iCol ];
31
32	/* Don't require that the user must specify bRegex, bSmart or bCaseInsensitive */
33	if ( oPre.bRegex === undefined )
34	{
35	oPre.bRegex = true;
36	}
37
38	if ( oPre.bSmart === undefined )
39	{
40	oPre.bSmart = true;
41	}
42
43	if ( oPre.bCaseInsensitive === undefined )
44	{
45	oPre.bCaseInsensitive = true;
46	}
47	}
48
49	/* Use the column options function to initialise classes etc */
50	_fnColumnOptions( oSettings, iCol, null );
51	}
52
53
54	/**
55	* Apply options for a column
56	* @param {object} oSettings dataTables settings object
57	* @param {int} iCol column index to consider
58	* @param {object} oOptions object with sType, bVisible and bSearchable etc
59	* @memberof DataTable#oApi
60	*/
61	function _fnColumnOptions( oSettings, iCol, oOptions )
62	{
63	var oCol = oSettings.aoColumns[ iCol ];
64
65	/* User specified column options */
66	if ( oOptions !== undefined && oOptions !== null )
67	{
68	/* Backwards compatibility for mDataProp */
69	if ( oOptions.mDataProp && !oOptions.mData )
70	{
71	oOptions.mData = oOptions.mDataProp;
72	}
73
74	if ( oOptions.sType !== undefined )
75	{
76	oCol.sType = oOptions.sType;
77	oCol._bAutoType = false;
78	}
79
80	$.extend( oCol, oOptions );
81	_fnMap( oCol, oOptions, "sWidth", "sWidthOrig" );
82
83	/* iDataSort to be applied (backwards compatibility), but aDataSort will take
84	* priority if defined
85	*/
86	if ( oOptions.iDataSort !== undefined )
87	{
88	oCol.aDataSort = [ oOptions.iDataSort ];
89	}
90	_fnMap( oCol, oOptions, "aDataSort" );
91	}
92
93	/* Cache the data get and set functions for speed */
94	var mRender = oCol.mRender ? _fnGetObjectDataFn( oCol.mRender ) : null;
95	var mData = _fnGetObjectDataFn( oCol.mData );
96
97	oCol.fnGetData = function (oData, sSpecific) {
98	var innerData = mData( oData, sSpecific );
99
100	if ( oCol.mRender && (sSpecific && sSpecific !== '') )
101	{
102	return mRender( innerData, sSpecific, oData );
103	}
104	return innerData;
105	};
106	oCol.fnSetData = _fnSetObjectDataFn( oCol.mData );
107
108	/* Feature sorting overrides column specific when off */
109	if ( !oSettings.oFeatures.bSort )
110	{
111	oCol.bSortable = false;
112	}
113
114	/* Check that the class assignment is correct for sorting */
115	if ( !oCol.bSortable \|\|
116	($.inArray('asc', oCol.asSorting) == -1 && $.inArray('desc', oCol.asSorting) == -1) )
117	{
118	oCol.sSortingClass = oSettings.oClasses.sSortableNone;
119	oCol.sSortingClassJUI = "";
120	}
121	else if ( $.inArray('asc', oCol.asSorting) == -1 && $.inArray('desc', oCol.asSorting) == -1 )
122	{
123	oCol.sSortingClass = oSettings.oClasses.sSortable;
124	oCol.sSortingClassJUI = oSettings.oClasses.sSortJUI;
125	}
126	else if ( $.inArray('asc', oCol.asSorting) != -1 && $.inArray('desc', oCol.asSorting) == -1 )
127	{
128	oCol.sSortingClass = oSettings.oClasses.sSortableAsc;
129	oCol.sSortingClassJUI = oSettings.oClasses.sSortJUIAscAllowed;
130	}
131	else if ( $.inArray('asc', oCol.asSorting) == -1 && $.inArray('desc', oCol.asSorting) != -1 )
132	{
133	oCol.sSortingClass = oSettings.oClasses.sSortableDesc;
134	oCol.sSortingClassJUI = oSettings.oClasses.sSortJUIDescAllowed;
135	}
136	}
137
138
139	/**
140	* Adjust the table column widths for new data. Note: you would probably want to
141	* do a redraw after calling this function!
142	* @param {object} oSettings dataTables settings object
143	* @memberof DataTable#oApi
144	*/
145	function _fnAdjustColumnSizing ( oSettings )
146	{
147	/* Not interested in doing column width calculation if auto-width is disabled */
148	if ( oSettings.oFeatures.bAutoWidth === false )
149	{
150	return false;
151	}
152
153	_fnCalculateColumnWidths( oSettings );
154	for ( var i=0 , iLen=oSettings.aoColumns.length ; i<iLen ; i++ )
155	{
156	oSettings.aoColumns[i].nTh.style.width = oSettings.aoColumns[i].sWidth;
157	}
158	}
159
160
161	/**
162	* Covert the index of a visible column to the index in the data array (take account
163	* of hidden columns)
164	* @param {object} oSettings dataTables settings object
165	* @param {int} iMatch Visible column index to lookup
166	* @returns {int} i the data index
167	* @memberof DataTable#oApi
168	*/
169	function _fnVisibleToColumnIndex( oSettings, iMatch )
170	{
171	var aiVis = _fnGetColumns( oSettings, 'bVisible' );
172
173	return typeof aiVis[iMatch] === 'number' ?
174	aiVis[iMatch] :
175	null;
176	}
177
178
179	/**
180	* Covert the index of an index in the data array and convert it to the visible
181	* column index (take account of hidden columns)
182	* @param {int} iMatch Column index to lookup
183	* @param {object} oSettings dataTables settings object
184	* @returns {int} i the data index
185	* @memberof DataTable#oApi
186	*/
187	function _fnColumnIndexToVisible( oSettings, iMatch )
188	{
189	var aiVis = _fnGetColumns( oSettings, 'bVisible' );
190	var iPos = $.inArray( iMatch, aiVis );
191
192	return iPos !== -1 ? iPos : null;
193	}
194
195
196	/**
197	* Get the number of visible columns
198	* @param {object} oSettings dataTables settings object
199	* @returns {int} i the number of visible columns
200	* @memberof DataTable#oApi
201	*/
202	function _fnVisbleColumns( oSettings )
203	{
204	return _fnGetColumns( oSettings, 'bVisible' ).length;
205	}
206
207
208	/**
209	* Get an array of column indexes that match a given property
210	* @param {object} oSettings dataTables settings object
211	* @param {string} sParam Parameter in aoColumns to look for - typically
212	* bVisible or bSearchable
213	* @returns {array} Array of indexes with matched properties
214	* @memberof DataTable#oApi
215	*/
216	function _fnGetColumns( oSettings, sParam )
217	{
218	var a = [];
219
220	$.map( oSettings.aoColumns, function(val, i) {
221	if ( val[sParam] ) {
222	a.push( i );
223	}
224	} );
225
226	return a;
227	}
228
229
230	/**
231	* Get the sort type based on an input string
232	* @param {string} sData data we wish to know the type of
233	* @returns {string} type (defaults to 'string' if no type can be detected)
234	* @memberof DataTable#oApi
235	*/
236	function _fnDetectType( sData )
237	{
238	var aTypes = DataTable.ext.aTypes;
239	var iLen = aTypes.length;
240
241	for ( var i=0 ; i<iLen ; i++ )
242	{
243	var sType = aTypes[i]( sData );
244	if ( sType !== null )
245	{
246	return sType;
247	}
248	}
249
250	return 'string';
251	}
252
253
254	/**
255	* Figure out how to reorder a display list
256	* @param {object} oSettings dataTables settings object
257	* @returns array {int} aiReturn index list for reordering
258	* @memberof DataTable#oApi
259	*/
260	function _fnReOrderIndex ( oSettings, sColumns )
261	{
262	var aColumns = sColumns.split(',');
263	var aiReturn = [];
264
265	for ( var i=0, iLen=oSettings.aoColumns.length ; i<iLen ; i++ )
266	{
267	for ( var j=0 ; j<iLen ; j++ )
268	{
269	if ( oSettings.aoColumns[i].sName == aColumns[j] )
270	{
271	aiReturn.push( j );
272	break;
273	}
274	}
275	}
276
277	return aiReturn;
278	}
279
280
281	/**
282	* Get the column ordering that DataTables expects
283	* @param {object} oSettings dataTables settings object
284	* @returns {string} comma separated list of names
285	* @memberof DataTable#oApi
286	*/
287	function _fnColumnOrdering ( oSettings )
288	{
289	var sNames = '';
290	for ( var i=0, iLen=oSettings.aoColumns.length ; i<iLen ; i++ )
291	{
292	sNames += oSettings.aoColumns[i].sName+',';
293	}
294	if ( sNames.length == iLen )
295	{
296	return "";
297	}
298	return sNames.slice(0, -1);
299	}
300
301
302	/**
303	* Take the column definitions and static columns arrays and calculate how
304	* they relate to column indexes. The callback function will then apply the
305	* definition found for a column to a suitable configuration object.
306	* @param {object} oSettings dataTables settings object
307	* @param {array} aoColDefs The aoColumnDefs array that is to be applied
308	* @param {array} aoCols The aoColumns array that defines columns individually
309	* @param {function} fn Callback function - takes two parameters, the calculated
310	* column index and the definition for that column.
311	* @memberof DataTable#oApi
312	*/
313	function _fnApplyColumnDefs( oSettings, aoColDefs, aoCols, fn )
314	{
315	var i, iLen, j, jLen, k, kLen;
316
317	// Column definitions with aTargets
318	if ( aoColDefs )
319	{
320	/* Loop over the definitions array - loop in reverse so first instance has priority */
321	for ( i=aoColDefs.length-1 ; i>=0 ; i-- )
322	{
323	/* Each definition can target multiple columns, as it is an array */
324	var aTargets = aoColDefs[i].aTargets;
325	if ( !$.isArray( aTargets ) )
326	{
327	_fnLog( oSettings, 1, 'aTargets must be an array of targets, not a '+(typeof aTargets) );
328	}
329
330	for ( j=0, jLen=aTargets.length ; j<jLen ; j++ )
331	{
332	if ( typeof aTargets[j] === 'number' && aTargets[j] >= 0 )
333	{
334	/* Add columns that we don't yet know about */
335	while( oSettings.aoColumns.length <= aTargets[j] )
336	{
337	_fnAddColumn( oSettings );
338	}
339
340	/* Integer, basic index */
341	fn( aTargets[j], aoColDefs[i] );
342	}
343	else if ( typeof aTargets[j] === 'number' && aTargets[j] < 0 )
344	{
345	/* Negative integer, right to left column counting */
346	fn( oSettings.aoColumns.length+aTargets[j], aoColDefs[i] );
347	}
348	else if ( typeof aTargets[j] === 'string' )
349	{
350	/* Class name matching on TH element */
351	for ( k=0, kLen=oSettings.aoColumns.length ; k<kLen ; k++ )
352	{
353	if ( aTargets[j] == "_all" \|\|
354	$(oSettings.aoColumns[k].nTh).hasClass( aTargets[j] ) )
355	{
356	fn( k, aoColDefs[i] );
357	}
358	}
359	}
360	}
361	}
362	}
363
364	// Statically defined columns array
365	if ( aoCols )
366	{
367	for ( i=0, iLen=aoCols.length ; i<iLen ; i++ )
368	{
369	fn( i, aoCols[i] );
370	}
371	}
372	}