<?xml version="1.0" encoding="UTF-8" ?>
<dt-option group="feature">
	<name>stateSave</name>
	<summary>State saving - restore table state on page reload</summary>
	<since>1.10</since>

	<type type="boolean" />
	<default value="false" />

	<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 `dt-init stateDuration` indicated to DataTables which API should be used (`localStorage`: 0 or greater, or `sessionStorage`: -1).

		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.

		Please note that the use of the HTML5 APIs for data storage means that the built in state saving option **will not work with IE6/7** as these browsers do not support these APIs. Alternative options of using cookies or saving the state on the server through Ajax can be used through the `dt-init stateSaveCallback` and `dt-init stateLoadCallback` options.

		Child rows state can also be maintained, but this requires some work to be done by the developer. There is a `-event 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 childrow. 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.

		Note: As of 1.11.0 the datatables state is stored regardless of the `-init stateSave` option. This data is only used to revert to a state when the `-init stateSave` option is enabled - otherwise it is not used.
	</description>

	<example title="Enable state saving"><![CDATA[
$('#example').dataTable( {
  stateSave: true
} );
]]></example>

	<example title="Enable state saving and override state save/load handlers to use only the table's DOM id"><![CDATA[
$('#example').dataTable( {
  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 ) )
    }
} );
]]></example>

	<related type="api">state()</related>
	<related type="api">state.clear()</related>
	<related type="api">state.loaded()</related>
	<related type="api">state.save()</related>
	<related type="option">stateSaveCallback</related>
	<related type="option">stateDuration</related>
	<related type="option">stateLoadCallback</related>
	<related type="option">stateLoadParams</related>
	<related type="option">stateLoaded</related>
	<related type="option">stateSaveParams</related>
	<related type="event">stateLoaded</related>
	<related type="event">stateLoadParams</related>
	<related type="event">stateSaveParams</related>
</dt-option>
