User Data Provider

UserDataProvider is similar to LayoutProvider but it manages user-defined data.

Like LayoutProvider, UserDataProvider is a way to connect external storage with a DXcharts React application.

What can be user-defined data in DXcharts React

The following data can be stored as user-defined data:

• custom aggregations
• custom colors from color picker
• custom timeframe presets
• favorite drawings
• recent drawings
• positions of elements such as the drawings toolbar or chart layers popover element
• drawings sidebar state

How it works

Below is an implementation of UserDataProvider that stores UserData in the localStorage.

import { UserDataProvider, UserData } from '@dx-private/dxchart5-react/dist/providers/user-data-provider';
interface LSUserDataProviderOptions {
    /**
     * timestamp in milliseconds when the layouts should be removed
     */
    expirationPeriod: number;
}
const USER_DATA_LS_KEY = 'userData';
const USERDATA_EXPIRATION_DATE_LS_KEY = 'userDataExpirationDate';
const DEFAULT_EXPIRATION_PERIOD = Number.MAX_SAFE_INTEGER;
/**
 * Creates a {@link UserDataProvider} that stores {@link UserData} in {@link localStorage}.
 */
export const createLocalStorageUserDataProvider = (
    udLSKey = USER_DATA_LS_KEY,
    options?: LSUserDataProviderOptions,
): UserDataProvider => {
    const getExpirationDateFromLS = (): number | undefined => {
        const expirationDateFromLS = localStorage.getItem(USERDATA_EXPIRATION_DATE_LS_KEY);
        if (!expirationDateFromLS) {
            return undefined;
        }
        return JSON.parse(expirationDateFromLS);
    };
    const setExpirationDateToLS = () => {
        localStorage.setItem(
            USERDATA_EXPIRATION_DATE_LS_KEY,
            JSON.stringify(options?.expirationPeriod ?? DEFAULT_EXPIRATION_PERIOD),
        );
    };
    const getUserDataFromLS = (): UserData | undefined => {
        const userDataFromLS = localStorage.getItem(udLSKey);
        if (!userDataFromLS) {
            return undefined;
        }
        return JSON.parse(userDataFromLS);
    };
    const setUserDataToLS = (userData: UserData) => {
        localStorage.setItem(udLSKey, JSON.stringify(userData));
    };
    const clearUserDataFromLS = () => {
        localStorage.removeItem(udLSKey);
        localStorage.removeItem(USERDATA_EXPIRATION_DATE_LS_KEY);
    };
    /**
     * Check if the expiration date is set and if it's expired
     */
    const expirationDate = getExpirationDateFromLS();
    if (!expirationDate) {
        clearUserDataFromLS();
        setExpirationDateToLS();
    } else {
        if (Date.now() > expirationDate) {
            clearUserDataFromLS();
            setExpirationDateToLS();
        }
    }
    /**
     * This method `dxcharts-react` will call on init and some other lifecycle events
     * to get the stored {@link UserData}
     */
    const getUserData = () => {
        const userData = getUserDataFromLS();
        if (!userData) {
            console.warn('No user data created yet');
            return Promise.resolve(null);
        }
        return Promise.resolve(userData);
    };
    /**
     * When a user changes something in {@link UserData} this method is called by `dxcharts-react`
     * to notify that you should sync {@link UserData} state with external store
     */
    const setUserData = (newUserData: UserData) => {
        setUserDataToLS(newUserData);
        return Promise.resolve(void 0);
    };
    return {
        getUserData,
        setUserData,
    };
};

API reference

UserDataProvider

To remember global user settings like custom colors and custom aggregation periods

UserDataProvider.getUserData

UserDataProvider.getUserData(): Promise<UserData>

Returns custom user data. If no data available, Promise.reject() is also valid return value

Returns

Promise<UserData>

UserDataProvider.setUserData

UserDataProvider.setUserData(userData: UserData): Promise<void>

Updates custom user data

Parameters

userData: UserData

Returns

Promise<void>