stateSave

State saving - restore table state on page reload.

Description

Enable or disable state saving. DataTables stores state information such as pagination position, display length, filtering and sorting. When this initialisation option is active and the end user reloads the page the table's state will be altered to match what they had previously set up.

Data storage for the state information in the browser is performed by use of the localStorage or sessionStorage HTML5 APIs. The stateDuration parameter is used to indicate to DataTables which API should be used (localStorage: 0 or greater, or sessionStorage: -1). The stateDuration parameter can also be used to indicate how long a saved state should be considered valid for. Please refer to stateDuration for additional details.

To be able to uniquely identify each table's state data, information is stored using a combination of the table's DOM id and the current page's pathname. If the table's id changes, or the page URL changes, the state information will be lost.

If you do not wish to use localStorage or sessionStorage, alternative options such as saving the state on a server through Ajax can be used through the stateSaveCallback and stateLoadCallback options.

Each individual part of the state object is optional (see stateSaveCallback for details of the JSON state structure) and can be removed by the state saving process (typically this would be done in stateSaveParams). Futhermore, as of DataTables 2.2, column state can be restored, even if columns are reordered, added or removed through use of the columns.name parameter. The name is a unique identifier for each column and the state will include that information and restore based on it.

There are a number of conditions under which a state might not be restored:

• If the saved state is too old (stateDuration)
• If stateLoadParams or stateLoadParams cancels the loading
• Column specific information will not be restored if the number of columns in the table does not match the number of columns from the state and columns.name was not used.

Child rows state can also be maintained, but this requires some work to be done by the developer. There is a requestChild that is triggered whenever DataTables wants to insert a child row into the table. The developer must set a callback function for this event that deals with the display of the child row. It is also worth noting that for this to work the rows have to have ids, and that this functionality is only available in version 1.11.0 and above.

Type

This option can be given in the following type(s):

• boolean

Default

• Value: false

Examples

new DataTable('#myTable', {
	stateSave: true
});

new DataTable('#myTable', {
	stateSave: true,
	ajax: '/api/data',
	columns: [
		{ data: 'name', name: 'name' },
		{ data: 'position', name: 'position' },
		{ data: 'office', name: 'office' },
		{ data: 'age', name: 'age' },
		{ data: 'start_date', name: 'start_date' },
		{ data: 'salary', name: 'salary' }
	]
});

new DataTable('#myTable', {
	stateSave: true,
	stateSaveCallback: function (settings, data) {
		localStorage.setItem(
			'DataTables_' + settings.sInstance,
			JSON.stringify(data)
		);
	},
	stateLoadCallback: function (settings) {
		return JSON.parse(localStorage.getItem('DataTables_' + settings.sInstance));
	}
});

Related

The following options are directly related and may also be useful in your application development.