DataTables logo
≡

DataTable.AjaxOptions

Options for configuring an Ajax request.

Description

DataTables provides a DataTable.ajax() method which can be used to make Ajax calls, and makes use of it for its own Ajax calls when configured with ajax to load data. The Ajax call is configured through an object of parameters that is passed to it. The parameters for this object are documented here.

The options provided here are a subset of those provided by jQuery's ajax() method and compatibility is an important characteristic in order to ensure easy porting from a jQuery based application to one which does require jQuery.

Defaults

The default values for the properties that this object makes available can be accessed using DataTable.ajax.defaults. You can use this to modify the defaults, allowing a global setting for Ajax configuration on a page, and easy addition of data such as a CSRF token in the headers. For example:

DataTable.ajax.defaults.headers._csrf = '... token ...';

TypeScript

This interface is available through the type definitions that DataTables makes available:

// Import DataTables base and the type
import DataTable, { AjaxOptions } from 'datatables.net';

// Example use
const options: AjaxOptions = {
    url: '/api/data',
    success: (json) => {
        // Do something
    }
}

// Make the Ajax call
DataTable.ajax(options);

Properties

beforeSend

A function that is executed immediately prior to the Ajax call is triggered, providing an option to give additional and low level customisation.

  • Optional
  • Type: function
  • Default: unset
  • Parameters:
    1. The XMLHttpRequest object, allowing it to be customised
    2. DataTable.AjaxOptions: The Ajax options used to configure the request.
  • Return: No return is required, although false can be returned to cancel the request.

cache

This option can be used to add a "cache busting" query parameter to the request URL. This is done, when set to false by adding a parameter with the name of _ and a current time stamp value to the request to make sure that the response will not have been cached by the browser.

  • Optional
  • Type: boolean
  • Default: true

complete

A function that will execute at the end of the response processing, regardless of whether the request was successful or not. This option can also be given as an array of functions that will be executed in sequence.

  • Optional
  • Type: function
  • Default: unset
  • Parameters:
    1. The XMLHttpRequest object, allowing it to be customised
    2. string: Status text of the response. This will be one of success, nocontent, notmodified, error or parseerror.
  • Return: No return

contentType

The content type to use when sending data to the server. You can use an empty string or false to have no content type header sent in the request. Please note that if you use FormData for the data property, this option will be ignored and the browser will set the content type automatically based on the FormData object.

  • Optional
  • Type:
    • string - Value to send
    • boolean - false to disable the content type header
  • Default: application/x-www-form-urlencoded; charset=UTF-8

data

The data to send to the server as part of the request. Depending on the method type, this will be used either as query parameters (GET) or body parameters (PUT / POST).

dataType

This option defines how the data returned from the server should be processed - i.e. as plain text or as JSON data. If not set, the software will attempt to parse the returned value as JSON, and if that fails will give the response as plain text. It can take one of two values (or be left unset): json or text. In the case of json, if the response is not valid JSON, the status will be set to parseerror.

  • Optional
  • Type: -string
  • Default: unset

deleteBody

Some HTTP servers will not accept body parameters as part of a DELETE request, blocking the request as invalid (support for body parameters in a DELETE is optional in the HTTP spec). If set to true (or undefined) the body parameters will be removed and appended as query parameters. Set to false to have the parameters sent in the request body.

  • Optional
  • Type: boolean
  • Default: true

error

A callback function that will be executed on error. This option can also be given as an array of functions that will be executed in sequence.

  • Optional
  • Type: function
  • Default: unset
  • Parameters:
    1. The XMLHttpRequest object, allowing it to be customised
    2. string: Status text of the response. This will be one of success, nocontent, notmodified, error or parseerror.
    3. string: The error from the XHR object
  • Return: No return

headers

This option can be used to specify HTTP headers to use in the request. This can be useful for if your server requires a CSRF token to be added to all requests, amount other uses.

  • Optional
  • Type: object - A key / value set of values to add to the HTTP headers
  • Default: {}

method

This option defines the HTTP method (i.e. the "verb") that the request will use. It will typically be one of GET, PUT, POST or DELETE. Case insensitive.

  • Optional
  • Type: string
  • Default: GET

password

If the request route requires HTTP Basic or Digest authentication, the password can be set using this parameter.

  • Optional
  • Type: string
  • Default: unset

success

Callback function that is executed when the Ajax request completes successfully (i.e. no error returned from the server, nor any errors in processing the returned data). This is where you handle the returned data and will almost always be set in the object, despite it being an optional parameter. This option can also be given as an array of functions that will be executed in sequence.

  • Optional
  • Type: function
  • Default: unset
  • Parameters:
    1. object | string: The response from the server. If detected as JSON (see dataType), it will be an object, otherwise it will be a string.
    2. string: Status text of the response. This will be success for this callback.
    3. The XMLHttpRequest object
  • Return: No return

submitAs

Depending on how you process data at the server-side, you might wish for the data to be sent as regular HTTP parameters, or as a JSON string. This option provides an easy configuration value to trigger that. It can take two values: http whereby the values will be sent as HTTP parameters, or json which will cause the data to be parsed into a string by JSON.stringify and then used directly in the request body.

  • Optional
  • Type: string
  • Default: http

type

An alias of the method option. See that parameter for full details.

url

This is the parameter that tells the ajax function where to make the request to. It is the one required parameter in this object.

username

If the request route requires HTTP Basic or Digest authentication, the username can be set using this parameter.

  • Optional
  • Type: string
  • Default: unset