Namespace: defaults

If sorting is enabled, then DataTables will perform a first pass sort on initialisation. You can define which column(s) the sort is performed upon, and the sorting direction, with this variable. The aaSorting array should contain an array for each column to be sorted initially containing the column's index and a direction string ('asc' or 'desc').

Example

   // Sort by 3rd column first, and then 4th column
   $(document).ready( function() {
     $('#example').dataTable( {
       "aaSorting": [[2,'asc'], [3,'desc']]
     } );
   } );
   
   // No initial sorting
   $(document).ready( function() {
     $('#example').dataTable( {
       "aaSorting": []
     } );
   } );

This parameter allows you to readily specify the entries in the length drop down menu that DataTables shows when pagination is enabled. It can be either a 1D array of options which will be used for both the displayed option and the value, or a 2D array which will use the array in the first position as the value, and the array in the second position as the displayed options (useful for language strings such as 'All').

Examples

   $(document).ready(function() {
     $('#example').dataTable( {
       "aLengthMenu": [[10, 25, 50, -1], [10, 25, 50, "All"]]
     } );
   } );
 
 

   // Setting the default display length as well as length menu
   // This is likely to be wanted if you remove the '10' option which
   // is the iDisplayLength default.
   $(document).ready(function() {
     $('#example').dataTable( {
       "iDisplayLength": 25,
       "aLengthMenu": [[25, 50, 100, -1], [25, 50, 100, "All"]]
     } );
   } );

The aoColumns option in the initialisation parameter allows you to define details about the way individual columns behave. For a full list of column options that can be set, please see DataTable.defaults.columns. Note that if you use aoColumns to define your columns, you must have an entry in the array for every single column that you have in your table (these can be null if you don't which to specify any options).

An array of CSS classes that should be applied to displayed rows. This array may be of any length, and DataTables will apply each class sequentially, looping when required.

Example

   $(document).ready( function() {
     $('#example').dataTable( {
       "asStripeClasses": [ 'strip1', 'strip2', 'strip3' ]
     } );
   } )

Deferred rendering can provide DataTables with a huge speed boost when you are using an Ajax or JS data source for the table. This option, when set to true, will cause DataTables to defer the creation of the table elements for each row until they are needed for a draw - saving a significant amount of time.

Example

   $(document).ready(function() {
     var oTable = $('#example').dataTable( {
       "sAjaxSource": "sources/arrays.txt",
       "bDeferRender": true
     } );
   } );

Enable or disable filtering of data. Filtering in DataTables is "smart" in that it allows the end user to input multiple words (space separated) and will match a row containing those words, even if not in the order that was specified (this allow matching across multiple columns). Note that if you wish to use filtering in DataTables this must remain 'true' - to remove the default filtering input box and retain filtering abilities, please use

Example

   $(document).ready( function () {
     $('#example').dataTable( {
       "bFilter": false
     } );
   } );

Enable jQuery UI ThemeRoller support (required as ThemeRoller requires some slightly different and additional mark-up from what DataTables has traditionally used).

Example

   $(document).ready( function() {
     $('#example').dataTable( {
       "bJQueryUI": true
     } );
   } );

Enable or disable pagination.

Example

   $(document).ready( function () {
     $('#example').dataTable( {
       "bPaginate": false
     } );
   } );

Retrieve the DataTables object for the given selector. Note that if the table has already been initialised, this parameter will cause DataTables to simply return the object that has already been set up - it will not take account of any changes you might have made to the initialisation object passed to DataTables (setting this parameter to true is an acknowledgement that you understand this). bDestroy can be used to reinitialise a table if you need.

Example

   $(document).ready(function() {
     initTable();
     tableActions();
   } );
   
   function initTable ()
   {
     return $('#example').dataTable( {
       "sScrollY": "200px",
       "bPaginate": false,
       "bRetrieve": true
     } );
   }
   
   function tableActions ()
   {
     var oTable = initTable();
     // perform API operations with oTable 
   }

When vertical (y) scrolling is enabled, DataTables will force the height of the table's viewport to the given height at all times (useful for layout). However, this can look odd when filtering data down to a small data set, and the footer is left "floating" further down. This parameter (when enabled) will cause DataTables to collapse the table's viewport down when the result set will fit within the given Y height.

Example

   $(document).ready(function() {
     $('#example').dataTable( {
       "sScrollY": "200",
       "bScrollCollapse": true
     } );
   } );

Configure DataTables to use server-side processing. Note that the sAjaxSource parameter must also be given in order to give DataTables a source to obtain the required data for each draw.

Example

   $(document).ready( function () {
     $('#example').dataTable( {
       "bServerSide": true,
       "sAjaxSource": "xhr.php"
     } );
   } );

Allows control over whether DataTables should use the top (true) unique cell that is found for a single column, or the bottom (false - default). This is useful when using complex headers.

Example

   $(document).ready(function() {
     $('#example').dataTable( {
       "bSortCellsTop": true
     } );
   } );

Enable or disable state saving. When enabled a cookie will be used to save table display information such as pagination information, display length, filtering and sorting. As such when the end user reloads the page the display display will match what thy had previously set up.

Example

   $(document).ready( function () {
     $('#example').dataTable( {
       "bStateSave": true
     } );
   } );

This function is called when a TR element is created (and all TD child elements have been inserted), or registered if using a DOM source, allowing manipulation of the TR element (adding classes etc).

Example

   $(document).ready(function() {
     $('#example').dataTable( {
       "fnCreatedRow": function( nRow, aData, iDataIndex ) {
         // Bold the grade for all 'A' grade browsers
         if ( aData[4] == "A" )
         {
           $('td:eq(4)', nRow).html( 'A' );
         }
       }
     } );
   } );

Identical to fnHeaderCallback() but for the table footer this function allows you to modify the table footer on every 'draw' even.

Example

   $(document).ready( function() {
     $('#example').dataTable( {
       "fnFooterCallback": function( nFoot, aData, iStart, iEnd, aiDisplay ) {
         nFoot.getElementsByTagName('th')[0].innerHTML = "Starting index is "+iStart;
       }
     } );
   } )

The information element can be used to convey information about the current state of the table. Although the internationalisation options presented by DataTables are quite capable of dealing with most customisations, there may be times where you wish to customise the string further. This callback allows you to do exactly that.

Example

   $('#example').dataTable( {
     "fnInfoCallback": function( oSettings, iStart, iEnd, iMax, iTotal, sPre ) {
       return iStart +" to "+ iEnd;
     }
   } );

Called at the very start of each table draw and can be used to cancel the draw by returning false, any other return (including undefined) results in the full draw occurring).

Example

   $(document).ready( function() {
     $('#example').dataTable( {
       "fnPreDrawCallback": function( oSettings ) {
         if ( $('#test').val() == 1 ) {
           return false;
         }
       }
     } );
   } );

It is often useful to send extra data to the server when making an Ajax request - for example custom filtering information, and this callback function makes it trivial to send extra information to the server. The passed in parameter is the data set that has been constructed by DataTables, and you can add to this or modify it as you require.

Example

   $(document).ready(function() {
     $('#example').dataTable( {
       "bProcessing": true,
       "bServerSide": true,
       "sAjaxSource": "scripts/server_processing.php",
       "fnServerParams": function ( aoData ) {
         aoData.push( { "name": "more_data", "value": "my_value" } );
       }
     } );
   } );

Callback which allows modification of the saved state prior to loading that state. This callback is called when the table is loading state from the stored data, but prior to the settings object being modified by the saved state. Note that for plug-in authors, you should use the 'stateLoadParams' event to load parameters for a plug-in.

Examples

   // Remove a saved filter, so filtering is never loaded
   $(document).ready(function() {
     $('#example').dataTable( {
       "bStateSave": true,
       "fnStateLoadParams": function (oSettings, oData) {
         oData.oFilter.sSearch = "";
     } );
   } );

 

   // Disallow state loading by returning false
   $(document).ready(function() {
     $('#example').dataTable( {
       "bStateSave": true,
       "fnStateLoadParams": function (oSettings, oData) {
         return false;
     } );
   } );

Duration of the cookie which is used for storing session information. This value is given in seconds.

Example

   $(document).ready( function() {
     $('#example').dataTable( {
       "iCookieDuration": 60*60*24 // 1 day
     } );
   } )

Number of rows to display on a single page when using pagination. If feature enabled (bLengthChange) then the end user will be able to override this to a custom setting using a pop-up menu.

Example

   $(document).ready( function() {
     $('#example').dataTable( {
       "iDisplayLength": 50
     } );
   } )

The scroll gap is the amount of scrolling that is left to go before DataTables will load the next 'page' of data automatically. You typically want a gap which is big enough that the scrolling will be smooth for the user, while not so large that it will load more data than need.

Example

   $(document).ready(function() {
     $('#example').dataTable( {
       "bScrollInfinite": true,
       "bScrollCollapse": true,
       "sScrollY": "200px",
       "iScrollLoadGap": 50
     } );
   } );

This parameter allows you to have define the global filtering state at initialisation time. As an object the "sSearch" parameter must be defined, but all other parameters are optional. When "bRegex" is true, the search string will be treated as a regular expression, when false (default) it will be treated as a straight string. When "bSmart" DataTables will use it's smart filtering methods (to word match at any point in the data), when false this will not be done.

Example

   $(document).ready( function() {
     $('#example').dataTable( {
       "oSearch": {"sSearch": "Initial search"}
     } );
   } )

You can instruct DataTables to load data from an external source using this parameter (use aData if you want to pass data in you already have). Simply provide a url a JSON object can be obtained from. This object must include the parameter 'aaData' which is the data source for the table.

Example

   $(document).ready( function() {
     $('#example').dataTable( {
       "sAjaxSource": "http://www.sprymedia.co.uk/dataTables/json.php"
     } );
   } )

This initialisation variable allows you to specify exactly where in the DOM you want DataTables to inject the various controls it adds to the page (for example you might want the pagination controls at the top of the table). DIV elements (with or without a custom class) can also be added to aid styling. The follow syntax is used:

• The following options are allowed:
  • 'l' - Length changing
  'f' - Filtering input
  • 't' - The table!
  • 'i' - Information
  • 'p' - Pagination
  • 'r' - pRocessing
• The following constants are allowed:
  • 'H' - jQueryUI theme "header" classes ('fg-toolbar ui-widget-header ui-corner-tl ui-corner-tr ui-helper-clearfix')
  • 'F' - jQueryUI theme "footer" classes ('fg-toolbar ui-widget-header ui-corner-bl ui-corner-br ui-helper-clearfix')
• The following syntax is expected:
  • '<' and '>' - div elements
  • '<"class" and '>' - div with a class
  • '<"#id" and '>' - div with an ID
• Examples:
  • '<"wrapper"flipt>'
  • '<lf<t>ip>'

Example

   $(document).ready(function() {
     $('#example').dataTable( {
       "sDom": '<"top"i>rt<"bottom"flp><"clear"&lgt;'
     } );
   } );

Enable horizontal scrolling. When a table is too wide to fit into a certain layout, or you have a large number of columns in the table, you can enable x-scrolling to show the table in a viewport, which can be scrolled. This property can by any CSS unit, or a number (in which case it will be treated as a pixel measurement).

Example

   $(document).ready(function() {
     $('#example').dataTable( {
       "sScrollX": "100%",
       "bScrollCollapse": true
     } );
   } );

Enable vertical scrolling. Vertical scrolling will constrain the DataTable to the given height, an enable scrolling for any data which overflows the current viewport. This can be used as an alternative to paging to display a lot of data in a small area (although paging and scrolling can both be enabled at the same time). This property can by any CSS unit, or a number (in which case it will be treated as a pixel measurement).

Example

   $(document).ready(function() {
     $('#example').dataTable( {
       "sScrollY": "200px",
       "bPaginate": false
     } );
   } );

This parameter allows you to override the default function which obtains the data from the server ($.getJSON) so something more suitable for your application. For example you could use POST data, or pull information from a Gears or AIR database.

Parameters:

Example:

   // POST data to server
   $(document).ready(function() {
     $('#example').dataTable( {
       "bProcessing": true,
       "bServerSide": true,
       "sAjaxSource": "xhr.php",
       "fnServerData": function ( sSource, aoData, fnCallback ) {
         $.ajax( {
           "dataType": 'json', 
           "type": "POST", 
           "url": sSource, 
           "data": aoData, 
           "success": fnCallback
         } );
       }
     } );
   } );

Save the table state. This function allows you to define where and how the state information for the table is stored - by default it will use a cookie, but you might want to use local storage (HTML5) or a server-side database.

Parameters:

Example:

   $(document).ready(function() {
     $('#example').dataTable( {
       "bStateSave": true,
       "fnStateSave": function (oSettings, oData) {
         // Send an Ajax request to the server with the state object
         $.ajax( {
           "url": "/state_save",
           "data": oData,
           "dataType": "json",
           "method": "POST"
           "success": function () {}
         } );
       }
     } );
   } );