HomeAcademyLoginTry for free
Ask or search…
⌃K
Links
Comment on page

Redux

Package
Version
Downloads
@carto/react-redux
​​
version
​​
​​
downloads
​​
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:
Param
Type
Description
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:
Param
Type
Description
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.type
string
Source type. Check available types here​
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:
Param
Type
Description
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:
Param
Type
Description
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:
Param
Type
Description
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 value

removeLayer

Action to remove a layer from the store
  • Input:
Param
Type
Description
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:
Param
Type
Description
credentials
Object
CARTO platform credentials. Check the parameters here​
  • 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:
Param
Type
Description
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:
Param
Type
Description
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:
Param
Type
Description
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:
Type
Description
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:
Param
Type
Description
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 operations

setViewState

Action to set the current ViewState of the map.
  • Input:
Param
Type
Description
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:
Param
Type
Description
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:
Param
Type
Description
widgetId
string
id of the widget

setAllWidgetsLoadingStates

Action to set the all the widgets loading state at once
  • Input:
Param
Type
Description
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:
Param
Type
Description
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:
Param
Type
Description
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:
Param
Type
Description
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);
Previous
Core
Next
UI
Last modified 7mo ago