Getting Started
Last updated
Last updated
This guide shows how you to create a private application with layers and widgets. A private application requires users to login into the application using their CARTO credentials.
CARTO for React applications are created using Create React App with one of the CARTO for React templates. The basic prerequisite for using Create React App is to have Node.js with a package manager (npm or yarn) previously installed. In this guide we are going to use yarn.
We are going to create a new application in the my-app
folder using the @carto/base-3
template:
Other Templates
You can also create new applications using any of the available templates, including a template for creating a CARTO 3 app with TypeScript, a basic template for CARTO 2 apps, and sample app templates for CARTO 2 and CARTO 3. Please refer to the Templates section in the Overview.
After that Create React App tool will recommend to start the project, but let's configure first a couple of details, understanding also some key points and available tools to be more productive.
These are the main folders in the generated code:
src/components/common: common components as Header, Footer, Menus, etc
src/components/layers: deck.gl layers that are available to the Map component.
src/components/views: pages which match with routes.
src/data: sources and models.
src/store: slice configuration.
src/utils: general utils.
public: the public folder contains the HTML file so you can tweak it, for example, to set the page title.
And these are the main files:
routes.js: the file where views and routes are matched.
views/Main.js: the general component that defines the layout of the application.
store/initialStateSlice.js: the file that defines the configuration of CARTO as default values for the slices. Set your CARTO account, token / api key, basemap, OAuth app configuration, etc…
store/appSlice.js: general slice of the app to include/extend with custom app functionality.
To connect your CARTO Organization you first need to create a SPA OAuth Client and get a Client ID
:
Go to the Developers section inside CARTO Workspace
Create a new SPA OAuth Client with the URL https://127.0.0.1:3000
Copy the Client ID
and introduce it at src/store/initialStateSlice.js
.
Go to the Developers section inside CARTO Workspace and copy the API Base URL.
Edit src/store/initialStateSlice.js
to add it (be sure to add the apiBaseUrl corresponding to your selected region, as stated in the Developers section of our Dashboard):
We’re going to create a view called Stores
that will be accesible in the /stores
path. When this view is loaded, the layer will be displayed.
The easiest way to create a new view in the application is to use the code generator. You need to execute the following command in the my-app
folder:
and select these options:
Now you’re ready to start the local development server using the following command:
You should see the map component with a Hello World
text on the left sidebar and a link to the new view in the top navigation bar.
Browser Certificate Warning
The application uses HTTPS by default but your browser will complain because it cannot found a valid certificate. It is safe to ignore this warning when developing but you should have a valid certificate when you deploy the application to your web server.
A source is a key piece in a CARTO for React application. Both layers and widgets depend on sources. A source exports a plain object with a certain structure that will be understood by the CARTO for React library to feed layers or widgets using the CARTO SQL and/or Maps APIs.
To create a source, the easiest way is again to use the code generator:
When you create a source in CARTO, you need to provide the connection name you want to use. CARTO provides a default carto_dw
, but you probably want to connect your own data warehouse to access your data.
We are going to create a source pointing to the public BigQuery dataset cartobq.public_account.retail_stores
using the carto_dw
connection.
Once we have defined the source, we can add now the layer to the map.
We select the following options:
If you reload the page, you will see the new layer in the map.
Finally we are ready to add some widgets to the view. We will add a Formula and a Category Widget.
The first task you need to perform is to add the following imports at the top of the src/components/views/Stores.js
file:
Then, in the same file, you need to replace the Hello World
text with:
There are two main elements in the store: the source and the viewport. When we change any of these elements, the following actions are triggered:
The layer is filtered when the source changes.
The widget is re-rendered when the source or viewport changes.
Any time we change the map extent (pan or zoom), the viewport changes and all the widgets are refreshed.
Any time a widget applies a filter (for example selecting a widget category), the filter is dispatched to the store. When we add a filter, we are changing the source, so all the components depending on the source are updated: the widgets are re-rendered and the layers are filtered. The map applies the filters using the DataFilterExtension
from deck.gl.
You already have your first CARTO for React application with layers and widgets, now you can jump to the Layers guide to learn more about working with layers and customizing styling properties: