{hero}

stateRestore.toggle

Since: StateRestore 1.0.0

Enable/Disable the saving for various datatables elements when saving a new state.
Please note - this property requires the StateRestore extension for DataTables.

Description

This option allows the user to specify which elements should be saved when creating a new state. The option is an object containing boolean values, one for each element that could be saved. When set to true, a checkBox will appear in the creation modal for the corresponding element, allowing the user to decide whether it should be saved or not.

For the extensions that support state saving, if the extension is not present then the toggling option will not be displayed regardless of the corresponding value here.

In order to display the creation modal, stateRestore.creationModal must be set to true.

The list of boolean values is as follows, it is the format as stateRestore.saveState.

columns.search

This option allows for the saving of the search applied to individual columns to be enabled or disabled by the user.

As default the value is true, meaning that the user can decide whether the column searches will be saved. If this option is set to false, then column searches will not not be given as an option to the user on creation.

columns.visible

This option allows for the saving of the visibility of the columns to be enabled or disabled by the user.

As default the value is true, meaning that the user can decide whether the column visibilities will be saved. If this option is set to false, then column visibilites will not not be given as an option to the user on creation.

length

This option allows for the saving of the page length to be enabled or disabled by the user.

As default the value is true, meaning that the user can decide whether the page length will be saved. If this option is set to false, then the page length saving will not be given as an option to the user on creation.

Note: When using this option and saving states with paging, StateRestore will display the first row that was displayed at when the state was saved at the start of the table. This could for example result in a table with page length of 50, but starting on record 31. Without knowing the page length it is not possible for DataTables to calculate any other start position.

order

This option allows for the saving of the column sorting to be enabled or disabled by the user.

As default the value is true, meaning that the user can decide whether the column sorting will be saved. If this option is set to false, then column sorting saving will not be given as an option to the user on creation.

paging

This option allows for the saving of the paging to be enabled or disabled by the user.

As default the value is true, meaning that the user can decide whether the paging will be saved. If this option is set to false, then the paging saving will not be given as an option to the user on creation.

scroller

This option allows for the saving of the scroller position to be enabled or disabled by the user. This option is only applicable when both the stateRestore and scroller extensions are in use.

As default the value is true, meaning that the user can decide whether the scroller position will be saved. If this option is set to false, then the scroller position saving will not be given as an option to the user on creation.

search

This option allows for the saving of the search to be enabled or disabled by the user.

As default the value is true, meaning that the user can decide whether the search will be saved. If this option is set to false, then the search saving will not be given as an option to the user on creation.

searchBuilder

This option allows for the saving of the searchBuilder state to be enabled or disabled by the user. This option is only applicable when both the stateRestore and searchBuilder extensions are in use.

As default the value is true, meaning that the user can decide whether the searchBuilder state will be saved. If this option is set to false, then the searchBuilder state saving will not be given as an option to the user on creation.

searchPanes

This option allows for the saving of the searchPanes state to be enabled or disabled by the user. This option is only applicable when both the stateRestore and searchPanes extensions are in use.

As default the value is true, meaning that the user can decide whether the searchPanes state will be saved. If this option is set to false, then the searchPanes state saving will not be given as an option to the user on creation.

select

This option allows for the saving of the select state to be enabled or disabled by the user. This option is only applicable when both the stateRestore and select extensions are in use.

As default the value is true, meaning that the user can decide whether the select state will be saved. If this option is set to false, then the select state saving will not be given as an option to the user on creation.

Type

object

Description:

This initialisation option is an object that includes a variety of boolean values that alloow the user to specify which different elements of datatables should be saved when creating a new state.

Default

  • Value: object

The default value for the stateRestore.toggle option is an object as follows. This will allow the user to configure what to save for each datatables element that supports state saving.

{
    columns: {
        search: false,
        visible: false
    },
    order: false,
    paging: false,
    scroller: false,
    search: false,
    searchBuilder: false,
    searchPanes: false,
    select: false
}

Examples

Enable paging saving customisation:

$('#example').DataTable({
    dom: 'Blfrtip',
    buttons:[
        {
            extend: 'createState',
            config: {
                toggle:{
                    paging: true
                }
            }
        },
        'savedStates',
        'colvis'
    ]
});

Enable column visibility saving customisation:

$('#example').DataTable({
    dom: 'Blfrtip',
    buttons:[
        {
            extend: 'createState',
            config: {
                toggle:{
                    columns:{
                        visible: true
                    }
                }
            }
        },
        'savedStates',
        'colvis'
    ]
});

Related

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