DataTables.Type

DataTables data type object.

Description

The DataTables data type object contains information about how it should handle different data types.

Using Typescript definitions, the object has the following structure:

interface DataTable.Type {
    className?: string;
    detect: (data: any) => (boolean | null) | {
        oneOf: (data: any) => boolean,
        allOf: (data: any) => boolean,
        init: (settings: Object, column: Object, index: number) => boolean
    };
    order: {
        pre?: (data: any) => any;
        asc?: (a: any, b: any) => number;
        desc?: (a: any, b: any) => number;
    };
    render?: (data: any, type: string, row: any) => string | number | Node;
    search?: (data: any) => string;
}

Properties

The following properties are available for the data type objects:

className

The class name property is used to automatically assign a class to columns matching this data type. That might be used for stylistic changes or typography. For example the built in num data type uses dt-right as the class name to align numeric data to the right.

detect

This is how DataTables determines a data type. As of DataTables 2.1 it can take two forms, an object with multiple parameters allowing the type detection to be refined, or a single function.

We'll discuss the single function first (DataTables 2.0+) - the function will check the data that is passed in to determine if it matches the data type expected and if so it will return true. If the data doesn't match the expected format return false. Almost any data type can be passed into this function, so care must be taken - you can't just assume that it will be a string.

As an example, consider the following to detect IPv4 addresses:

function (data) {
    return typeof data === 'string' && data.match(/^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}$/))
        ? 'ipv4'
        : null;
}

As of DataTables 2.1 it is also possible to use an object with oneOf, allOf and init functions:

allOf - this is the same as the function above. All data points in the column must pass this function to allow a column to take this data type.
oneOf - At least one of the data points in the column must pass this function to allow the column to take this data type.
init - Run when type detection starts, to see if a column can be assigned a data type based on a property of the column other than the data.

order

Ordering in DataTables is done by the pre, asc and desc functions defined for a type:

pre - Pre-deformatting method. Used to convert the formatted data into orderable data
asc - Ascending ordering method
desc - Descending ordering method

Each of these functions is optional and you may use one of the following combinations:

pre only - ordering will be done using the DataTables default sort on the returned data.
asc and desc only - standard Javascript sorting functions.
All three - the preformatted data will be passed into the custom ordering methods.

It is strongly recommended that you provide a pre method if you need to transform the data from the original data type into something that the ordering methods will use. This is because the pre function is run only once per data point while ordering, while the asc and desc ordering methods might be called multiple times per data point.

As an example, consider the following ordering data type definition which is used to sort data without a the prefix (common used for books and films). Here we only need to use a pre deformatter (which is the case with most ordering definitions):

function (data) {
    return data.replace(/^ the/i, '');
}

render

The rendering function can be used to transform data into different forms for different orthogonal actions, but is specifically of use for display formatting. A function defined here will be automatically applied for a data type if a rendering function hasn't already been given for the column (columns.render).

This can be particularly useful when you don't know in advance what the data types of the inbound data is and you want to format it according to the end user's localisation preferences. For example, dates should be M/D/Y format in the US and D/M/Y in much of the rest of the world.

The following two commands assign the built in renderers to the date and num (number) data types for automatic rendering if a column is determined to match that type. They will automatically format the data in a localised manner for the end user:

DataTable.type('date', 'render', DataTable.render.date());
DataTable.type('num', 'render', DataTable.render.number());

search

The search function is used to transform the input data into the string that will matched against when DataTables performs any searching for the end user. In this way it is very similar to the pre ordering deformatter in that is pre-processes the data.

This is done as can be useful to strip out data that should not be searched, e.g. HTML tags, or it can be used to provide redundancy in search terms for example the user might search for a displayed telephone number with spaces or without. The following example demonstrates that:

function (data) {
    // Return original data and also remove any non-numeric data, so
    // '555-2368' would be returned as '555-2368 5552368' allowing
    // either form to be searched for
    return data + ' ' + data.replace(/[^\d]/g, '');
}

Further information

Use the following resources to explore the DataTables data types further:

Data type documentation
DataTable.type() - get / set details of a specific data type.
DataTable.types() - get a list of registered data types.