Usage

Configuration of StateRestore is performed through the stateRestore initialisation option for DataTables, while its UI is presented via Buttons, which can be set-up with one of two different interfaces (table or list based), depending on your preference.

Simple initialisation

In its most simple case, you can enable StateRestore by simply setting stateRestore: true as an option in the DataTables initialisation.

new DataTable('#example', {
    layout: {
        topStart: {
            buttons: ['stateCreate', 'statesList', 'pageLength']
        }
    },
    stateRestore: true
});

Note that you will typically use one of statesList or statesTable in the buttons array, as these define the UI that the end user will interact with. stateCreate is another common StateRestore button to use at the top level. This and the list view are used in the example above.

Options

For more complex cases, the stateRestore option can be used as an object allowing you to specify options such an Ajax end point for remote storage of states, setting which properties can be stored in a state, and other properties such as sharing and default abilities.

In this example stateRestore.ajax is used to set an Ajax route, and stateRestore.include to define table properties that the end user will be able to select if they wish to include in the state or not (live example).

new DataTable('#myTable', {
    layout: {
        topStart: {
            buttons: ['stateCreate', 'statesList', 'pageLength']
        }
    },
    stateRestore: {
        ajax: '/api/states',
        include: {
            order: null,
            pageStart: null,
            pageLength: null,
            search: null
        }
    }
});

Include properties

The state objects saved by StateRestore can be partial DataTable.State objects - that is, it need only contain the properties that you wish to save and restore. This can be particularly useful for data that updates frequently as some properties, such as start page and page length, might not be useful, but other properties such as search and order are.

The stateRestore.include property, used in the example above, provides a way to control which properties are included in the saved state. Each property can be set to one of:

• false - Not included in the saved state
• true - Will be included in the saved state
• null - The end user has the option of including the value or not. A checkbox will be shown in the create state modal allowing them to select or deselect this value (default selected).

By default, the paging and selection properties of the table are not included in StateRestore states. All other properties are included, with no end user options. This can easily be modified to suit your needs with stateRestore.include. Please see that option's documentation for further details.

API

While you will typically use statesList and statesTable to present a UI to the end user, StateRestore also have a full set of APIs which can be used to create, edit, delete and load states. This can be used to create a custom UI if you need a different form of display to integrate with your web-site. An example showing API usage is available and the full API reference) is also available.

Reference

For a complete list of the options that StateRestore supports, please refer to the DataTables initialisation options reference. The StateRestore examples also demonstrate the options available.