DataTables logo DataTables

ads by Yoggrt

Columns

Although DataTables can obtain information about the table directly from the DOM, you may wish to give DataTables specific instructions for each individual column. This can be done using either the aoColumnDefs parameter, or aoColumns and the object information given for each column.

The aoColumnDefs parameter and aoColumns achieve the same aim, but differ in how they work:

Both aoColumnDefs parameter and aoColumns can be used together, although aoColumnDefs is preferred due to it's flexibility. If both are used, aoColumns definitions will take the highest priority. Likewise, if the same column is targeted multiple times in aoColumnDefs, the first elements in the array will take the highest priority, and the last the lowest.

aDataSort
Show details 		Allows a column's sorting to take multiple columns into account when doing a sort. For example first name / last name columns make sense to do a multi-column sort over the two columns.
Default: null Takes the value of the column index automatically
Type: array
Code example: 
   // Using aoColumnDefs
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumnDefs": [
         { "aDataSort": [ 0, 1 ], "aTargets": [ 0 ] },
         { "aDataSort": [ 1, 0 ], "aTargets": [ 1 ] },
         { "aDataSort": [ 2, 3, 4 ], "aTargets": [ 2 ] }
       ]
     } );
   } );
   
 
   // Using aoColumns
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumns": [
         { "aDataSort": [ 0, 1 ] },
         { "aDataSort": [ 1, 0 ] },
         { "aDataSort": [ 2, 3, 4 ] },
         null,
         null
       ]
     } );
   } );
asSorting
Show details 		You can control the default sorting direction, and even alter the behaviour of the sort handler (i.e. only allow ascending sorting etc) using this parameter.
Default: [ 'asc', 'desc' ]
Type: array
Code example: 
   // Using aoColumnDefs
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumnDefs": [
         { "asSorting": [ "asc" ], "aTargets": [ 1 ] },
         { "asSorting": [ "desc", "asc", "asc" ], "aTargets": [ 2 ] },
         { "asSorting": [ "desc" ], "aTargets": [ 3 ] }
       ]
     } );
   } );
   
 
   // Using aoColumns
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumns": [
         null,
         { "asSorting": [ "asc" ] },
         { "asSorting": [ "desc", "asc", "asc" ] },
         { "asSorting": [ "desc" ] },
         null
       ]
     } );
   } );
bSearchable
Show details 		Enable or disable filtering on the data in this column.
Default: true
Type: boolean
Code example: 
   // Using aoColumnDefs
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumnDefs": [ 
         { "bSearchable": false, "aTargets": [ 0 ] }
       ] } );
   } );
   
 
   // Using aoColumns
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumns": [ 
         { "bSearchable": false },
         null,
         null,
         null,
         null
       ] } );
   } );
bSortable
Show details 		Enable or disable sorting on this column.
Default: true
Type: boolean
Code example: 
   // Using aoColumnDefs
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumnDefs": [ 
         { "bSortable": false, "aTargets": [ 0 ] }
       ] } );
   } );
   
 
   // Using aoColumns
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumns": [ 
         { "bSortable": false },
         null,
         null,
         null,
         null
       ] } );
   } );
bUseRendered
Show details 		When using fnRender() for a column, you may wish to use the original data (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.
Default: true
Type: boolean
Code example: 
   // Using aoColumnDefs
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumnDefs": [ 
         {
           "fnRender": function ( oObj ) {
             return oObj.aData[0] +' '+ oObj.aData[3];
           },
           "bUseRendered": false,
           "aTargets": [ 0 ]
         }
       ]
     } );
   } );
   
 
   // Using aoColumns
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumns": [ 
         {
           "fnRender": function ( oObj ) {
             return oObj.aData[0] +' '+ oObj.aData[3];
           },
           "bUseRendered": false
         },
         null,
         null,
         null,
         null
       ]
     } );
   } );
bVisible
Show details 		Enable or disable the display of this column.
Default: true
Type: boolean
Code example: 
   // Using aoColumnDefs
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumnDefs": [ 
         { "bVisible": false, "aTargets": [ 0 ] }
       ] } );
   } );
   
 
   // Using aoColumns
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumns": [ 
         { "bVisible": false },
         null,
         null,
         null,
         null
       ] } );
   } );
fnCreatedCell
Show details 		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).
Default:
Type: function
Code example: 
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumnDefs": [ {
         "aTargets": [3],
         "fnCreatedCell": function (nTd, sData, oData, iRow, iCol) {
           if ( sData == "1.7" ) {
             $(nTd).css('color', 'blue')
           }
         }
       } ]
     });
   } );
fnRender
Show details 		Custom display function that will be called for the display of each cell in this column.
Default:
Type: function
Code example: 
   // Using aoColumnDefs
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumnDefs": [ 
         {
           "fnRender": function ( o, val ) {
             return o.aData[0] +' '+ o.aData[3];
           },
           "aTargets": [ 0 ]
         }
       ]
     } );
   } );
   
 
   // Using aoColumns
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumns": [ 
         { "fnRender": function ( o, val ) {
           return o.aData[0] +' '+ o.aData[3];
         } },
         null,
         null,
         null,
         null
       ]
     } );
   } );
iDataSort
Show details 		The column index (starting from 0!) that you wish a sort to be performed upon when this column is selected for sorting. This can be used for sorting on hidden columns for example.
Default: -1 Use automatically calculated column index
Type: int
Code example: 
   // Using aoColumnDefs
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumnDefs": [ 
         { "iDataSort": 1, "aTargets": [ 0 ] }
       ]
     } );
   } );
   
 
   // Using aoColumns
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumns": [ 
         { "iDataSort": 1 },
         null,
         null,
         null,
         null
       ]
     } );
   } );
mDataProp
Show details 		This property can be used to read data from any JSON data source property, including deeply nested objects / properties. mDataProp can be given in a number of different ways which effect its behaviour:
  • integer - treated as an array index for the data source. This is the default that DataTables uses (incrementally increased for each column).
  • string - read an object property from the data source. Note that you can use Javascript dotted notation to read deep properties/arrays from the data source.
  • null - the sDafaultContent option will use used for the cell (empty string by default. This can be useful on generated columns such as edit / delete action columns.
  • function - the function given will be executed whenever DataTables needs to set or get the data for a cell in the column. The function takes three parameters:
    • {array|object} The data source for the row
    • {string} The type call data requested - this will be 'set' when setting data or 'filter', 'display', 'type' or 'sort' when gathering data.
    • {*} Data to set when the second parameter is 'set'.
    The return value from the function is not required when 'set' is the type of call, but otherwise the return is what will be used for the data requested.
Default: null Use automatically calculated column index
Type: string
Code example: 
   // Read table data from objects
   $(document).ready(function() {
     var oTable = $('#example').dataTable( {
       "sAjaxSource": "sources/deep.txt",
       "aoColumns": [
         { "mDataProp": "engine" },
         { "mDataProp": "browser" },
         { "mDataProp": "platform.inner" },
         { "mDataProp": "platform.details.0" },
         { "mDataProp": "platform.details.1" }
       ]
     } );
   } );

 
   // Using mDataProp as a function to provide different information for
   // sorting, filtering and display. In this case, currency (price)
   $(document).ready(function() {
     var oTable = $('#example').dataTable( {
       "aoColumnDefs": [
       {
         "aTargets": [ 0 ],
         "mDataProp": function ( source, type, val ) {
           if (type === 'set') {
             source.price = val;
             // Store the computed dislay and filter values for efficiency
             source.price_display = val=="" ? "" : "$"+numberFormat(val);
             source.price_filter  = val=="" ? "" : "$"+numberFormat(val)+" "+val;
             return;
           }
           else if (type === 'display') {
             return source.price_display;
           }
           else if (type === 'filter') {
             return source.price_filter;
           }
           // 'sort' and 'type' both just use the integer
           return source.price;
         }
       ]
     } );
   } );
sClass
Show details 		Class to give to each cell in this column.
Default: Empty string
Type: string
Code example: 
   // Using aoColumnDefs
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumnDefs": [ 
         { "sClass": "my_class", "aTargets": [ 0 ] }
       ]
     } );
   } );
   
 
   // Using aoColumns
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumns": [ 
         { "sClass": "my_class" },
         null,
         null,
         null,
         null
       ]
     } );
   } );
sContentPadding
Show details 		When DataTables calculates the column widths to assign to each column, it finds the longest string in each column and then constructs a temporary table and reads the widths from that. The problem with this is that "mmm" is much wider then "iiii", but the latter is a longer string - thus the calculation can go wrong (doing it properly and putting it into an DOM object and measuring that is horribly(!) slow). Thus as a "work around" we provide this option. It will append its value to the text that is found to be the longest string for the column - i.e. padding. Generally you shouldn't need this, and it is not documented on the general DataTables.net documentation
Default: Empty string
Type: string
Code example: 
   // Using aoColumns
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumns": [ 
         null,
         null,
         null,
         {
           "sContentPadding": "mmm"
         }
       ]
     } );
   } );
sDefaultContent
Show details 		Allows a default value to be given for a column's data, and will be used whenever a null data source is encountered (this can be because mDataProp is set to null, or because the data source itself is null).
Default: null
Type: string
Code example: 
   // Using aoColumnDefs
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumnDefs": [ 
         {
           "mDataProp": null,
           "sDefaultContent": "Edit",
           "aTargets": [ -1 ]
         }
       ]
     } );
   } );
   
 
   // Using aoColumns
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumns": [ 
         null,
         null,
         null,
         {
           "mDataProp": null,
           "sDefaultContent": "Edit"
         }
       ]
     } );
   } );
sName
Show details 		This parameter is only used in DataTables' server-side processing. It can be exceptionally useful to know what columns are being displayed on the client side, and to map these to database fields. When defined, the names also allow DataTables to reorder information from the server if it comes back in an unexpected order (i.e. if you switch your columns around on the client-side, your server-side code does not also need updating).
Default: Empty string
Type: string
Code example: 
   // Using aoColumnDefs
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumnDefs": [ 
         { "sName": "engine", "aTargets": [ 0 ] },
         { "sName": "browser", "aTargets": [ 1 ] },
         { "sName": "platform", "aTargets": [ 2 ] },
         { "sName": "version", "aTargets": [ 3 ] },
         { "sName": "grade", "aTargets": [ 4 ] }
       ]
     } );
   } );
   
 
   // Using aoColumns
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumns": [ 
         { "sName": "engine" },
         { "sName": "browser" },
         { "sName": "platform" },
         { "sName": "version" },
         { "sName": "grade" }
       ]
     } );
   } );
sSortDataType
Show details 		Defines a data source type for the sorting which can be used to read realtime information from the table (updating the internally cached version) prior to sorting. This allows sorting to occur on user editable elements such as form inputs.
Default: std
Type: string
Code example: 
   // Using aoColumnDefs
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumnDefs": [
         { "sSortDataType": "dom-text", "aTargets": [ 2, 3 ] },
         { "sType": "numeric", "aTargets": [ 3 ] },
         { "sSortDataType": "dom-select", "aTargets": [ 4 ] },
         { "sSortDataType": "dom-checkbox", "aTargets": [ 5 ] }
       ]
     } );
   } );
   
 
   // Using aoColumns
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumns": [
         null,
         null,
         { "sSortDataType": "dom-text" },
         { "sSortDataType": "dom-text", "sType": "numeric" },
         { "sSortDataType": "dom-select" },
         { "sSortDataType": "dom-checkbox" }
       ]
     } );
   } );
sTitle
Show details 		The title of this column.
Default: null Derived from the 'TH' value for this column in the original HTML table.
Type: string
Code example: 
   // Using aoColumnDefs
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumnDefs": [ 
         { "sTitle": "My column title", "aTargets": [ 0 ] }
       ]
     } );
   } );
   
 
   // Using aoColumns
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumns": [ 
         { "sTitle": "My column title" },
         null,
         null,
         null,
         null
       ]
     } );
   } );
sType
Show details 		The type allows you to specify how the data for this column will be sorted. Four types (string, numeric, date and html (which will strip HTML tags before sorting)) are currently available. Note that only date formats understood by Javascript's Date() object will be accepted as type date. For example: "Mar 26, 2008 5:03 PM". May take the values: 'string', 'numeric', 'date' or 'html' (by default). Further types can be adding through plug-ins.
Default: null Auto-detected from raw data
Type: string
Code example: 
   // Using aoColumnDefs
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumnDefs": [ 
         { "sType": "html", "aTargets": [ 0 ] }
       ]
     } );
   } );
   
 
   // Using aoColumns
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumns": [ 
         { "sType": "html" },
         null,
         null,
         null,
         null
       ]
     } );
   } );
sWidth
Show details 		Defining the width of the column, this parameter may take any CSS value (3em, 20px etc). DataTables applys 'smart' widths to columns which have not been given a specific width through this interface ensuring that the table remains readable.
Default: null Automatic
Type: string
Code example: 
   // Using aoColumnDefs
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumnDefs": [ 
         { "sWidth": "20%", "aTargets": [ 0 ] }
       ]
     } );
   } );
   
 
   // Using aoColumns
   $(document).ready(function() {
     $('#example').dataTable( {
       "aoColumns": [ 
         { "sWidth": "20%" },
         null,
         null,
         null,
         null
       ]
     } );
   } );