Comment on page
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.
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: "",
};
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 | |
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);
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);
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)
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
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);
Action to set the default credentials parameters to use for requests to the CARTO platform.
- Input:
Param | Type | Description |
---|---|---|
credentials | Object |
- 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);
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);
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)
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)
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)
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
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)
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 |
Action to remove a specific widget loading state
- Input:
Param | Type | Description |
---|---|---|
widgetId | string | id of the widget |
Action to set the all the widgets loading state at once
- Input:
Param | Type | Description |
---|---|---|
areLoading | boolean | loading state |
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',
}
};
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"
}
*/
Action to logout, removing user info & token from redux store.
- Example:
import { logout } from "@carto/react-redux";
const action = logout();
// dispatch(action)
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);
Last modified 7mo ago