Predefined States

At times, you might find it useful to have a set of predefined states that are immediately available to your end users, rather than requiring them to set up a table in the state to save and then create the new state. This can be particularly useful for column visibility grouping, or advanced search. This can be achieved in StateRestore using the stateRestore.predefined option.

Predefined structure

The stateRestore.predefined property takes an array of objects, each of which defines a state. The objects are defined by StateRestore.Predefined - it has a simple set of properties:

• isDefault - if the state should be used on table load
• name - the name of the state that the user will see
• state - the DataTable state object.

A simple example is shown below, which provides buttons that will toggle column visibility (you can see this example running in the StateRestore examples):

new DataTable('#example', {
    layout: {
        topStart: {
            buttons: ['statesList', 'pageLength']
        }
    },
    stateRestore: {
        canCreate: false,
        predefined: [
            {
                name: 'Summary columns',
                state: {
                    columns: [
                        {visible: true},
                        {visible: true},
                        {visible: true},
                        {visible: false},
                        {visible: false},
                        {visible: false}
                    ]
                }
            },
            {
                name: 'All columns',
                state: {
                    columns: [
                        {visible: true},
                        {visible: true},
                        {visible: true},
                        {visible: true},
                        {visible: true},
                        {visible: true}
                    ]
                }
            }
        ]
    }
});

It is worth highlighting here that states are partial - that is, you do not need to define every property that can be in a state object (DataTable.State). Rather define the properties that you wish the state to act on, and the other parameters of the table will be left as they were - i.e. in the case above, the ordering, filtering and paging applied to a table will be left as it was when toggling between states.

Static states

Please note that a predefined state is considered to be "static" - that is, an end user will not have the ability to edit or delete the state. If they are allowed to create new states though (stateRestore.canCreate, which is enabled by default), then they can duplicate the state, which they can then modify as required. If you would like the end user to be able to modify a predefined state, use the API to add states - stateRestore.add().