Redux
@carto/react-redux
Functions to manage application state using React-Redux and the Redux Toolkit. This package includes 2 slices to manage the main redux blocks of a CARTO for React application. A slice is a way to manage a “portion” or slice of the redux store with a module:
cartoSlice: to deal with basemap, viewState, sources, layers, and filters on sources.oauthSlice: to use an OAuth app.
Tip: The CARTO for React template already makes extensive use of these slices for redux out of the box, to provide several features in an easy way.
CARTO Slice
createCartoSlice
A function that accepts an initialState, setups the state, and creates the reducers that support CARTO for React architecture. In the CARTO 3 templates this slice includes also the OAuth settings; in the CARTO 2 templates there is a separate slice for OAuth settings.
Input:
initialState
Object
the initial state
An initial state object might look like:
import { POSITRON } from "@carto/react-basemaps";
export const initialState = {
viewState: {
latitude: 31.802892,
longitude: -103.007813,
zoom: 2,
pitch: 0,
bearing: 0,
dragRotate: false,
},
basemap: POSITRON,
credentials: {
username: "public",
apiKey: "default_public",
serverUrlTemplate: "https://{user}.carto.com",
},
googleApiKey: "",
};addSource
Action to add a source to the store.
Input:
props
Object
{ id, data, type, credentials, connection }
props.id
string
Unique id for the source
props.data
string
Table name, tileset name or SQL query
props.credentials
string
Credentials for accessing the source
props.connection
string
Connection name. Used only for CARTO 3.
props.filtersLogicalOperator
FiltersLogicalOperators
Logical operation to use for combining filters. Can take the values FiltersLogicalOperators.AND and FiltersLogicalOperators.OR. Default value is AND. Note: this property is only available beginning with v1.3
[props.queryParameters]
QueryParameters (@deck.gl/carto)
Optional. SQL query parameters
Example:
import { addSource } from "@carto/react-redux";
import { MAP_TYPES } from '@deck.gl/carto';
const source = {
id: "sourceOne",
type: MAP_TYPES.QUERY,
connection: 'bqconn',
data: "SELECT * FROM my_table",
filtersLogicalOperator: FiltersLogicalOperators.OR
};
const action = addSource(source);
// dispatch(action);removeSource
Action to remove a source from the store
Input:
sourceId
string
id of the source to remove
Example:
import { removeSource } from "@carto/react-redux";
const action = removeSource("sourceOne");
// dispatch(action);addLayer
Action to add a Layer to the store. By default, the layer visible attribute is set to true unless the layerAttributes property overrides the visible property.
Important! This doesn’t imply adding a whole deck.gl layer to the redux store, just a “pointer” to it, by using an id shared with a Layer file + linking it to a source. See code generated by hygen assistants in the create-react-app template projects.
Input:
props
Object
{ id, source, layerAttributes }
props.id
string
unique id for the layer
props.source
string
id of the source of the layer
[props.layerAttributes]
Object
(optional) custom attributes to pass to the layer
Example:
const action = addLayer({
id: "layerOne",
source: "sourceOne",
layerAttributes: {
extraAttribute: 1,
},
});
// dispatch(action);
// extraAttribute will be available inside the Layer, for custom operations inside it (eg. styling)updateLayer
Action to update a Layer in the store
Input:
props
Object
{ id, layerAttributes }
props.id
string
unique id for the CARTO layer already in the store
props.layerAttributes
Object
custom attributes to update in the layer
Example:
const action = updateLayer({
id: "layerOne",
layerAttributes: {
extraAttribute: 100,
},
});
// dispatch(action);
// extraAttribute will be updated to the new valueremoveLayer
Action to remove a layer from the store
Input:
id
string
id of the layer to remove
Example:
const action = removeLayer("layerOne");
// dispatch(action);setCredentials
Action to set the default credentials parameters to use for requests to the CARTO platform.
Input:
Example:
import { API_VERSIONS } from "@deck.gl/carto";
import { setCredentials } from "@carto/react-redux";
const action = setCredentials({
apiBaseUrl: 'https://gcp-us-east1.api.carto.com',
apiVersion: API_VERSIONS.V3,
accessToken: 'eyJhb...'
});
// dispatch(action);setBasemap
Action to set a basemap. To see available maps, check the reference for @carto/react-basemaps. If you use a Google Maps basemap, you would need to manage its api_key properly.
Input:
basemap
String
the new basemap to add
Example:
import { DARK_MATTER } from "@carto/react-basemaps";
import { setBasemap } from "@carto/react-redux";
const action = setBasemap(DARK_MATTER);
// dispatch(action);addFilter
Action to add a filter on a given source by a column. This is done internally (and in a transparent way) by widgets.
Input:
props
Object
{ id, column, type, values, [owner], [params]}
props.id
string
Identifier of the source to apply the filter on
props.column
string
Column from the source to use by the filter
props.type
FilterType
Type of filter
props.values
array
Values for the filter (eg: [‘a’, ‘b’] for ‘in’ or [10, 20] for ‘between’)
[props.owner]
string
(optional) Identifier of the widget triggering the filter (to be excluded)
[props.params]
object
(optional) Additional filter parameters (depending on filter type)
Example:
This would apply a filter equivalent to a ‘WHERE country IN (‘Spain’)’ to the source. It is important to notice that a source can have multiple filters at the same type.
import { addFilter } from "@carto/react-redux";
const action = addFilter({
id: "sourceOne", // a valid sourceId
column: "country",
type: "in",
values: ["Spain"],
});
// dispatch(action)removeFilter
Action to remove a column filter from a source.
Input:
props
Object
{ id, column }
props.id
string
sourceId of the source to remove the filter from
props.column
string
column of the filter to remove
Example:
This would remove a filter (the previous example on addFilter)
import { removeFilter } from "@carto/react-redux";
const action = removeFilter({
id: "sourceOne",
column: "country",
});
// dispatch(action)clearFilters
Action to remove all filters from a source.
Input:
id
sourceId of the source to remove all filters from
Example:
This would remove all filters from a source with id ‘sourceOne’
import { clearFilters } from "@carto/react-redux";
const action = clearFilters("sourceOne");
// dispatch(action)selectSourceById
Redux selector to get a source by ID
Input:
state
Object
root redux state
sourceId
string
id of the source to recover from redux
Example:
import { useSelector } from "react-redux";
import { selectSourceById } from "@carto/react-redux";
const source = useSelector((state) => selectSourceById(state, "sourceOne") || {});
// source is now available, for further operationssetViewState
Action to set the current ViewState of the map.
Input:
viewState
Object
ViewState, as defined by deck.gl
Example Example to increase the zoom level
import { useSelector } from "react-redux";
import { setViewState } from "@carto/react-redux";
const zoomLevel = useSelector((state) => state.carto.viewState.zoom);
const action = setViewState({ zoom: zoomLevel + 1 });
// dispatch(action)setWidgetLoadingState
Action to set the loading state to a specific widget. It can be useful when creating custom widgets.
Input:
props
Object
{ widgetId, isLoading}
props.widgetId
string
id of the widget
props.isLoading
boolean
loading state
removeWidgetLoadingState
Action to remove a specific widget loading state
Input:
widgetId
string
id of the widget
setAllWidgetsLoadingStates
Action to set the all the widgets loading state at once
Input:
areLoading
boolean
loading state
OAuth Slice
createOauthCartoSlice
A function that accepts an initialState, setup the state, and creates reducers to manage OAuth with the CARTO 2 platform. This slice is not used with CARTO 3 templates because OAuth is managed through the Auth0 React SDK.
Input:
initialState
Object
the initial state
An initial state object might look like:
export const oauthInitialState = {
oauthApp: {
clientId: 'YOUR-CARTO-OAUTH-APP-CLIENTID'
scopes: [
'user:profile', // to load avatar photo
'datasets:metadata', // to list all your datasets,
'dataservices:geocoding', // to use geocoding through Data Services API
'dataservices:isolines', // to launch isochrones or isodistances through Data Services API
],
authorizeEndPoint: 'https://carto.com/oauth2/authorize',
}
};setTokenAndUserInfoAsync
Action to set the userInfo in the redux store, once there is a valid token (and set them both in state).
Input:
props
Object
oauthParams, as returned by useOAuthLogin hook ({ accessToken, expirationDate, userInfoUrl})
Example:
import { setTokenAndUserInfoAsync } from "@carto/react-redux";
// const oauthApp = { whatever your app requires... }
const onParamsRefreshed = (oauthParams) => {
if (oauthParams.error) {
console.error(`OAuth error: ${oauthParams.error}`);
} else {
const action = setTokenAndUserInfoAsync(oauthParams);
dispatch(action);
}
};
const [handleLogin] = useOAuthLogin(oauthApp, onParamsRefreshed);
/*
oauthParams look something like:
{
accessToken: "xxxxxxxxx",
expirationDate: 1616013732973.8652,
userInfoUrl: "https://a-certain-user.carto.com/api/v4/me"
}
*/logout
Action to logout, removing user info & token from redux store.
Example:
import { logout } from "@carto/react-redux";
const action = logout();
// dispatch(action)selectOAuthCredentials
Selector to fetch the current OAuth credentials from the redux store.
Returns:
credentials
Object
{ username, apiKey, serverUrlTemplate }
credentials.username
string
CARTO username
credentials.apiKey
string
apiKey coming from OAuth
credentials.serverUrlTemplate
string
required for further api requests
Example:
import { useSelector } from "react-redux";
import { selectOAuthCredentials } from "@carto/react-redux";
const oauthCredentials = useSelector(selectOAuthCredentials);Last updated
Was this helpful?