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:
-
aoColumnDefs: This array allows you to target a specific column, multiple columns, or all columns, using the aTargets property of each object in the array (please note that aoColumnDefs was introduced in DataTables 1.7). This allows great flexibility when creating tables, as the aoColumnDefs arrays can be of any length, targeting the columns you specifically want. The aTargets property is an array to target one of many columns and each element in it can be:
- a string - class name will be matched on the TH for the column
- 0 or a positive integer - column index counting from the left
- a negative integer - column index counting from the right
- the string "_all" - all columns (i.e. assign a default)
- aoColumns: If specified, then the length of this array must be equal to the number of columns in the original HTML table. Use 'null' where you wish to use only the default values and automatically detected options.
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.
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 Strings |
| 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
]
} );
} );
|
aTargets
Show details
|
Used only in a column definition (aoColumnDefs) to target specific columns with the definition given (see above). |
| Default: |
|
| Type: |
Array |
| Code example: |
$(document).ready(function() {
$('#example').dataTable( {
"aoColumnDefs": [
{ "sClass": 'center', "aTargets": [ -1, -2 ] }
]
} );
} );
|
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( {
"aoColumns": [
{ "aoColumnDefs": 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( {
"aoColumns": [
{ "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. |
| 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
] } );
} );
|
fnRender
Show details
|
Custom display function that will be called for the display of each cell in this column. |
| Default: |
void - use the raw data |
| Input parameters: |
1. object: - object with the following parameters:
- int:iDataRow - the row in aoData
- int:iDataColumn - the column in question
- array:aData - the data for the row in question
- object:oSettings - the settings object for this DataTables instance
|
| Return parameter: |
string: - the string you which to use in the display |
| Code example: |
/* Using aoColumnDefs */
$(document).ready(function() {
$('#example').dataTable( {
"aoColumnDefs": [
{
"fnRender": function ( oObj ) {
return oObj.aData[0] +' '+ oObj.aData[3];
},
"aTargets": [ 0 ]
}
]
} );
} );
/* Using aoColumns */
$(document).ready(function() {
$('#example').dataTable( {
"aoColumns": [
{ "fnRender": function ( oObj ) {
return oObj.aData[0] +' '+ oObj.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: |
The current column |
| Type: |
Integer |
| 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
]
} );
} );
|
sClass
Show details
|
Class to give to each cell in this column. |
| Default: |
|
| 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
]
} );
} );
|
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: |
|
| 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: |
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: |
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: |
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
]
} );
} );
|
DataTables
