JavaScript/jQuery PivotGrid - stateStoring

A configuration object specifying properties related to state storing.

Type:

Object

State storing enables the UI component to save applied settings and restore them the next time the UI component is loaded. Assign true to the stateStoring.enabled property to enable this functionality.

The state is saved with a specified storage key.

State storing saves the following properties:

To specify the time in milliseconds between automatic state saves, set the savingTimeout property. To specify the lifetime of the saved state, set the storage type.

Use the PivotGridDataSource's state method to manage the PivotGrid's state at runtime.

View Demo

customLoad

Specifies a function that is executed on state loading. Applies only if the type is 'custom'.

Type:

Function

Return Value:

Promise<Object> (jQuery or native)

The UI component state. As a rule, it is a state that you save within the customSave function.

Use the customSave and customLoad functions to manually implement state storing: in customSave, save the state to a storage; in customLoad, load it. You can also modify the state in both functions.

View Example

If you need to save and load the state from a remote storage, use the following code:

jQuery
JavaScript
function sendStorageRequest (storageKey, dataType, method, data) {
    var deferred = new $.Deferred;
    var storageRequestSettings = {
        url: "https://url/to/your/storage/" + JSON.stringify(storageKey),
        headers: {
            "Accept" : "text/html",
            "Content-Type" : "text/html"
        },
        method: method,
        data: data ? JSON.stringify(data) : null,
        dataType: dataType,
        success: function (data) {
            deferred.resolve(data);
        },
        fail: function (error) {
            deferred.reject();
        }
    };
    $.ajax(storageRequestSettings);
    return deferred.promise();
}
$(function() {
    $("#pivotGridContainer").dxPivotGrid({
        // ...
        stateStoring: {
            enabled: true,
            type: "custom",
            customLoad: function () {
                return sendStorageRequest("storageKey", "json", "GET");
            },
            customSave: function (state) {
                sendStorageRequest("storageKey", "text", "PUT", state);
            }
        },
    });
})
Angular
TypeScript
HTML
import { HttpClient, HttpClientModule, HttpHeaders, HttpRequest } from "@angular/common/http";
import { DxPivotGridModule } from "devextreme-angular";
import "rxjs/add/operator/toPromise";
import "rxjs/add/operator/catch";
// ...
export class AppComponent {
    constructor(private httpClient: HttpClient) { }

    sendStorageRequest = (storageKey, dataType, method, data) => {
        let url  = "https://url/to/your/storage/" + JSON.stringify(storageKey);
        let req: HttpRequest<any> = new HttpRequest(method, url, {
            headers: new HttpHeaders({
                "Accept": "text/html",
                "Content-Type": "text/html"
            }),
            responseType: dataType,
            body: data ? JSON.stringify(data) : null
        });
        return httpClient.request(req)
            .toPromise();
    }

    loadState = () => {
        return this.sendStorageRequest("storageKey", "json", "Get");
    } 

    saveState = (state) => {
        this.sendStorageRequest("storageKey", "text", "Put", state);
    }
}
@NgModule({
    imports: [
        // ...
        DxPivotGridModule,
        HttpClientModule
    ],
    // ...
})
<dx-pivot-grid ...>
    <dxo-state-storing 
        [enabled]="true" 
        type="custom" 
        [customLoad]="loadState"
        [customSave]="saveState">
    </dxo-state-storing>
</dx-pivot-grid>
Vue
App.vue
<template>
    <DxPivotGrid ... >
        <DxStateStoring 
            :enabled="true" 
            type="custom" 
            :custom-load="loadState"
            :custom-save="saveState"
        />
    </DxPivotGrid>
</template>

<script>
import 'devextreme/dist/css/dx.light.css';

import DxPivotGrid, {
    DxStateStoring
} from 'devextreme-vue/pivot-grid';
import 'whatwg-fetch';

function sendStorageRequest (storageKey, method, data) {
    const url = "https://url/to/your/storage/" + JSON.stringify(storageKey);
    const requestOptions = {
        method: method,
        headers: {
            "Accept": "text/html",
            "Content-Type": "text/html"
        },
        body: data ? JSON.stringify(data) : null
    };
    return fetch(url, requestOptions)
            .then(response => response.json())
            .catch(() => { throw 'Data Loading Error'; });
}

export default {
    components: {
        DxPivotGrid,
        DxStateStoring
    },
    // ...
    methods: {
        loadState () {
            return sendStorageRequest("storageKey", "GET");
        },
        saveState (state) {
            sendStorageRequest("storageKey", "PUT", state);
        }
    }
}
</script>
React
App.js
import React, { useCallback } from 'react';
import 'devextreme/dist/css/dx.light.css';

import PivotGrid, {
    StateStoring
} from 'devextreme-react/pivot-grid';
import 'whatwg-fetch';

function sendStorageRequest (storageKey, method, data) {
    const url = "https://url/to/your/storage/" + JSON.stringify(storageKey);
    const requestOptions = {
        method: method,
        headers: {
            "Accept": "text/html",
            "Content-Type": "text/html"
        },
        body: data ? JSON.stringify(data) : null
    };
    return fetch(url, requestOptions)
            .then(response => response.json())
            .catch(() => { throw 'Data Loading Error'; });
}

export default function App() {
    const loadState = useCallback(() => {
        return sendStorageRequest("storageKey", "GET");
    }, []);

    const saveState = useCallback((state) => {
        sendStorageRequest("storageKey", "PUT", state);
    }, []);

    return (
        <PivotGrid ... >
            <StateStoring 
                enabled={true}
                type="custom"
                customLoad={loadState}
                customSave={saveState}
            />
        </PivotGrid>
    );
}
See Also

customSave

Specifies a function that is executed on state change. Applies only if the type is "custom".

Type:

Function

Function parameters:
state:

Object

The current UI component state.

Use the customSave and customLoad functions to manually implement state storing: in customSave, save the state to a storage; in customLoad, load it. You can also modify the state in both functions.

View Example

If you need to save and load the state from a remote storage, use the following code:

jQuery
JavaScript
function sendStorageRequest (storageKey, dataType, method, data) {
    var deferred = new $.Deferred;
    var storageRequestSettings = {
        url: "https://url/to/your/storage/" + JSON.stringify(storageKey),
        headers: {
            "Accept" : "text/html",
            "Content-Type" : "text/html"
        },
        method: method,
        data: data ? JSON.stringify(data) : null,
        dataType: dataType,
        success: function (data) {
            deferred.resolve(data);
        },
        fail: function (error) {
            deferred.reject();
        }
    };
    $.ajax(storageRequestSettings);
    return deferred.promise();
}
$(function() {
    $("#pivotGridContainer").dxPivotGrid({
        // ...
        stateStoring: {
            enabled: true,
            type: "custom",
            customLoad: function () {
                return sendStorageRequest("storageKey", "json", "GET");
            },
            customSave: function (state) {
                sendStorageRequest("storageKey", "text", "PUT", state);
            }
        },
    });
})
Angular
TypeScript
HTML
import { HttpClient, HttpClientModule, HttpHeaders, HttpRequest } from "@angular/common/http";
import { DxPivotGridModule } from "devextreme-angular";
import "rxjs/add/operator/toPromise";
import "rxjs/add/operator/catch";
// ...
export class AppComponent {
    constructor(private httpClient: HttpClient) { }

    sendStorageRequest = (storageKey, dataType, method, data) => {
        let url  = "https://url/to/your/storage/" + JSON.stringify(storageKey);
        let req: HttpRequest<any> = new HttpRequest(method, url, {
            headers: new HttpHeaders({
                "Accept": "text/html",
                "Content-Type": "text/html"
            }),
            responseType: dataType,
            body: data ? JSON.stringify(data) : null
        });
        return httpClient.request(req)
            .toPromise();
    }

    loadState = () => {
        return this.sendStorageRequest("storageKey", "json", "Get");
    } 

    saveState = (state) => {
        this.sendStorageRequest("storageKey", "text", "Put", state);
    }
}
@NgModule({
    imports: [
        // ...
        DxPivotGridModule,
        HttpClientModule
    ],
    // ...
})
<dx-pivot-grid ...>
    <dxo-state-storing 
        [enabled]="true" 
        type="custom" 
        [customLoad]="loadState"
        [customSave]="saveState">
    </dxo-state-storing>
</dx-pivot-grid>
Vue
App.vue
<template>
    <DxPivotGrid ... >
        <DxStateStoring 
            :enabled="true" 
            type="custom" 
            :custom-load="loadState"
            :custom-save="saveState"
        />
    </DxPivotGrid>
</template>

<script>
import 'devextreme/dist/css/dx.light.css';

import DxPivotGrid, {
    DxStateStoring
} from 'devextreme-vue/pivot-grid';
import 'whatwg-fetch';

function sendStorageRequest (storageKey, method, data) {
    const url = "https://url/to/your/storage/" + JSON.stringify(storageKey);
    const requestOptions = {
        method: method,
        headers: {
            "Accept": "text/html",
            "Content-Type": "text/html"
        },
        body: data ? JSON.stringify(data) : null
    };
    return fetch(url, requestOptions)
            .then(response => response.json())
            .catch(() => { throw 'Data Loading Error'; });
}

export default {
    components: {
        DxPivotGrid,
        DxStateStoring
    },
    // ...
    methods: {
        loadState () {
            return sendStorageRequest("storageKey", "GET");
        },
        saveState (state) {
            sendStorageRequest("storageKey", "PUT", state);
        }
    }
}
</script>
React
App.js
import React, { useCallback } from 'react';
import 'devextreme/dist/css/dx.light.css';

import PivotGrid, {
    StateStoring
} from 'devextreme-react/pivot-grid';
import 'whatwg-fetch';

function sendStorageRequest (storageKey, method, data) {
    const url = "https://url/to/your/storage/" + JSON.stringify(storageKey);
    const requestOptions = {
        method: method,
        headers: {
            "Accept": "text/html",
            "Content-Type": "text/html"
        },
        body: data ? JSON.stringify(data) : null
    };
    return fetch(url, requestOptions)
            .then(response => response.json())
            .catch(() => { throw 'Data Loading Error'; });
}

export default function App() {
    const loadState = useCallback(() => {
        return sendStorageRequest("storageKey", "GET");
    }, []);

    const saveState = useCallback((state) => {
        sendStorageRequest("storageKey", "PUT", state);
    }, []);

    return (
        <PivotGrid ... >
            <StateStoring 
                enabled={true}
                type="custom"
                customLoad={loadState}
                customSave={saveState}
            />
        </PivotGrid>
    );
}
See Also

enabled

Specifies whether or not a grid saves its state.

Type:

Boolean

Default Value: false

View Demo

savingTimeout

Specifies the delay between the last change of a grid state and the operation of saving this state in milliseconds.

Type:

Number

Default Value: 2000

When using the PivotGrid UI component, a number of settings may be changed at runtime. When these changes are being made one after another, there is no need to save the grid state after each change. Instead, specify the savingTimeout property, which dictates how much time should pass between the last change of the state and the operation of saving this state.

NOTE
If a long timeout is specified, the grid state may be lost, e.g., if the user closes the browser before the timeout is over. Hence, be mindful when specifying the savingTimeout property.

storageKey

Specifies a unique key to be used for storing the grid state.

Type:

String

Default Value: null

View Demo

type

Specifies the type of storage to be used for state storing.

Type:

String

Default Value: 'localStorage'
Accepted Values: 'custom' | 'localStorage' | 'sessionStorage'

When state storing is enabled, PivotGrid stores data about its state on the client side. The type of storage that will suit your needs best depends on the supposed lifetime of user-specified pivot grid settings, such as fields configuration, sorting, filters, expanded headers, etc. If these settings should be destroyed after a browser session ends, use a session storage. If it is important to keep them for a longer time, choose a local storage.

View Demo

If you want to define specific actions on saving and loading a state, use a custom type of storage. For this purpose, specify the customSave and customLoad callback functions.