From fd882038d78ed44dab73cf2d4e275cdf63cc74fb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADctor=20Velarde?= Date: Thu, 11 Mar 2021 18:48:22 +0100 Subject: [PATCH] Cleanup docs (#213) * doc: remove guides (transferred to docs.carto.com) * doc: cleanup README.md * doc: recover DEVELOPERS basic notes * chore: update lib to prerelease * chore: improve release scripts * chore: adapt to new lib repo name (carto-react) --- CHANGELOG.md | 2 +- DEVELOPERS.md | 91 ++++++ README.md | 246 +------------- docs/guides/01_connect_your_account.md | 25 -- docs/guides/02_page_layer_widgets.md | 299 ------------------ docs/guides/03_basemap.md | 35 -- docs/guides/04_permissions_user_management.md | 40 --- docs/guides/05_look_and_feel.md | 33 -- template-sample-app/package.json | 3 +- template-sample-app/template.json | 14 +- template-sample-app/template/package.dev.json | 14 +- template-skeleton/package.json | 3 +- template-skeleton/template.json | 14 +- template-skeleton/template/package.dev.json | 14 +- 14 files changed, 128 insertions(+), 705 deletions(-) create mode 100644 DEVELOPERS.md delete mode 100644 docs/guides/01_connect_your_account.md delete mode 100644 docs/guides/02_page_layer_widgets.md delete mode 100644 docs/guides/03_basemap.md delete mode 100644 docs/guides/04_permissions_user_management.md delete mode 100644 docs/guides/05_look_and_feel.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 133fd34b..9a88535b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,7 +8,7 @@ - Improve default popup with htmlForFeature [#202](https://github.com/CartoDB/carto-react-template/pull/202) - Change BigQuery source type name from 'bq' to 'bigquery' [#203](https://github.com/CartoDB/carto-react-template/pull/203) - Add new hygen generators for components, models and slices [#171](https://github.com/CartoDB/carto-react-template/pull/171) -- Adapt to new **multi-package** structure for carto-react libs [#206](https://github.com/CartoDB/carto-react-lib/pull/206) +- Adapt to new **multi-package** structure for carto-react libs [#206](https://github.com/CartoDB/carto-react-template/pull/206) - Fix layer generator with second layer [#204](https://github.com/CartoDB/carto-react-template/pull/204) - Fix bug in formatter applied to histogram [#211](https://github.com/CartoDB/carto-react-template/pull/211) - Cleanup templates & pin deck.gl 8.4.10 [#212](https://github.com/CartoDB/carto-react-template/pull/212) diff --git a/DEVELOPERS.md b/DEVELOPERS.md new file mode 100644 index 00000000..4d887c8b --- /dev/null +++ b/DEVELOPERS.md @@ -0,0 +1,91 @@ + +# Developer notes + +To develop for a template itself, you need to create a `package.json` file in the template folder and add it to the gitignore list, as this file would overwrite the one created by create-react-app when used. This is as easy as follows: + +```bash +git clone https://github.com/CartoDB/carto-react-template.git +cd carto-react-template +cp -R hygen/_templates/ template-sample-app/template/_templates +cp -R hygen/_templates/ template-skeleton/template/_templates +cd template-sample-app/template +ln -s package.dev.json package.json +cd template-skeleton/template +ln -s package.dev.json package.json +``` + +Then you are ready to install the dependencies executing `yarn` in the template folder and start the development server with `yarn start`. + +## Testing the template generation + +> ⚠️ Important: remember to synchronize the changes applied to your `template/package.json` with `template.json` and remove the `template/package.json` file before testing or execute `yarn clean` to clean it automatically. + +You can test the template locally by calling `create-react-app` specifying the folder of this project: + +```bash +npx create-react-app test-template --template file:./carto-react-template/template-sample-app +``` + +## Publishing the templates to npm + +> ⚠️ Important: remember to set the right version for each template, tag the release in the GitHub repository and deploy the sample app with the latest changes + +For each template, execute the release command from its **base folder**. Before this command is executed, a pre-hook will clean all unnecesary development files and folders and copy the hygen templates, before making the npm release + +```bash +cd template-sample-app +yarn release +``` + + +## Deploying the sample app + +The sample app corresponding to https://sample-app-react.carto.com/ is hosted in Firebase, so before deploying it you'll need to log into Firebase using: + +```bash +cd template-sample-app/template +yarn firebase login +``` + +Then, just build the sample-app template and deploy it by executing: + +```bash +cd template-sample-app/template +yarn build +yarn firebase deploy +``` + +### Updating supported browsers + +This project supports [browserslist](https://github.com/browserslist/browserslist) and it has an unsupported browser page. In case of updating browserslist configuration, ensure to update the detection script by running: + +```bash +yarn updateSupportedBrowsers +``` + +## Using locally the CARTO for React library + +In order to work side by side with a local version of the `CARTO for React library` packages (available at https://github.com/CartoDB/carto-react`), follow these instructions: + +```bash +git clone https://github.com/CartoDB/carto-react.git +cd react +yarn +yarn start +yarn link-all +``` + +Now that all packages are compiled, link them into `carto-react-template` with: + +```bash +cd carto-react-template +cd template-sample-app/template +yarn link-carto-react +yarn start + +cd template-skeleton/template +yarn link-carto-react +yarn start +``` + +From this moment, template-sample-app or template-skeleton will be using your local version of the library packages. diff --git a/README.md b/README.md index 1ffec1c2..215caafc 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ It is based on the most popular toolchain [Create React App](https://github.com/ ## Getting started -The basic prerequisite for using Create React App is to have a package manager ([npm](https://www.npmjs.com/get-npm) and [yarn](https://yarnpkg.com/)) previously installed. `yarn` is preferred for developers contributing to the projects, as it will ensure a better integration with external libs. +The basic prerequisite for using Create React App is to have a package manager ([npm](https://www.npmjs.com/get-npm) or [yarn](https://yarnpkg.com/)) previously installed. `yarn` is preferred for developers contributing to the projects, as it will ensure a better integration with external libs. To download our skeleton template for create-react-app, just type: @@ -41,246 +41,8 @@ yarn start A full [Sample Application](#sample-application) with the most common functionality is available at https://sample-app-react.carto.com -Want to continue? Start [connecting your CARTO account](docs/guides/01_connect_your_account.md). +--- -**Deploy** +**Want to know more about it?** +Visit [CARTO for React](https://docs.carto.com/react/) for more details, guides and a reference. -Use CARTO platform and deploy everywhere. These are the deployment methods available: - -* [GitHub pages](https://create-react-app.dev/docs/deployment/#github-pages) -* [Firebase](https://create-react-app.dev/docs/deployment/#firebase) -* [Azure](https://create-react-app.dev/docs/deployment/#azure) -* [Netlify](https://create-react-app.dev/docs/deployment/#netlify) -* [Heroku](https://create-react-app.dev/docs/deployment/#heroku) -* [Amazon S3 and CloudFront](https://create-react-app.dev/docs/deployment/#s3-and-cloudfront) -* [AWS Amplify](https://create-react-app.dev/docs/deployment/#aws-amplify) -* [Vercel](https://create-react-app.dev/docs/deployment/#vercel) -* or even use your own [static server](https://create-react-app.dev/docs/deployment/#static-server) - -## How-to Guides - -* [Connect your CARTO account](docs/guides/01_connect_your_account.md) - -* [Create a page with a layer and widgets](docs/guides/02_page_layer_widgets.md) - -* [CARTO and Google Basemaps](docs/guides/03_basemap.md) - -* [Permissions and user management](docs/guides/04_permissions_user_management.md) - -* [Look and feel](docs/guides/05_look_and_feel.md) - -## Architecture - -![alt_text](docs/images/architecture.png 'Architecture') - -CARTO for react is based on the following libraries: - -- [CARTO for deck.gl](https://carto.com/developers/deck-gl) as the library to visualize maps. For the basemaps you can use either Google Maps or CARTO basemaps. -- [React](https://reactjs.org/) as the JavaScript library for building user interfaces and [Redux](https://redux.js.org/) for managing global state for the application. We use [React-Redux](https://react-redux.js.org/) for managing the interactions between the React components with the Redux store. -- [Material-UI](https://material-ui.com/): UI React components for faster and easier web development. -- [CARTO for React lib](https://github.com/CartoDB/carto-react-lib): A set of packages created to make easy integration with CARTO platform and its APIs, geospatial widgets and a custom theme for [Material-UI](https://material-ui.com/). - -**Why React?** - -LI Apps tend to be applications with a reduced number of pages, but with lots of functionalities at each page and many relations between them. - -In the past, they were developed using imperative programming (with MVC patterns or similar), but it easily ends up in a messy application with a huge amount of relations between components. And each time you need to add something new, a new bug is also introduced. - -The reactive programming (React and deck.gl) comes to fix this issue and make your application easy to maintain, to test and to scale. We're 100% sure that you can create something manageable even if your application is really complex and includes lots of features with multiple interactions. - -Yes, it's a new paradigm, but once you learn it, you'll love it. - -## Folder structure - -* **src/store**: configuration of the application. -* **src/components/common**: common components as Header, Footer, Menus, etc -* **src/components/layers**: deck.gl layers that area available to the Map component. -* **src/components/views**: pages which match with routes. -* **src/models**: async functions to connect with external APIs. -* **src/utils**: general utils. -* **public**: the public folder contains the HTML file so you can tweak it, for example, to set the page title. - -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 define the configuration of CARTO as default values for the slices. Set your CARTO account, apiKeys, basemap, OAuth apps, etc... -* **store/appSlice.js**: general slice of the app to include/extend with custom app functionality. - -## UI components - -CARTO for React lib comes with a set of [UI components](https://storybook-react.carto.com) ready to be used to create the best LI Apps. - -## @carto/react - -We've created this library to: - -1. Make easy integration with CARTO platform and its APIs. - -2. Provide a catalog of very useful widgets for LI Apps. - -3. Create a custom theme for [Material-UI](https://material-ui.com/) to reduce the design work of your team. - -There is a full [reference](https://github.com/CartoDB/carto-react-lib/) available for each package. - -## Frequently Asked Questions (FAQ) - -**Installing npm modules, learning React with Redux, learning Material-UI, it is just too much for my application, is there a simpler way?** - -If your application is not so complex and does not need the benefits added by this template, you can just use CARTO for deck.gl with the scripting API. Please check the [examples](https://carto.com/developers/deck-gl/examples/). - -**I’m using Vue or Angular for building my applications, what are my options?** - -At this moment, we only have a CARTO for React. If you are building an application using Vue, Angular or other JavaScript framework, you don’t have to worry, it is completely feasible and you just need to use the CARTO for deck.gl pure JavaScript flavor. Please check the [example](https://github.com/CartoDB/viz-doc/tree/master/deck.gl/examples/pure-js). - -## Sample Application - -A full [Sample Application](#sample-application) with the most common functionality when creating LI Apps is also available at https://sample-app-react.carto.com - -To download it, just run: - -```bash -npx create-react-app my-app --template @carto/sample-app -cd my-app -yarn start -``` - -This application uses a dataset with retail locations and another related dataset with the monthly revenue information for each location. It includes the following views/pages: - -- **Stores view**. This view demostrates how to: - - Visualize a CARTO dataset applying a by-value style (color based on store type) and create a corresponding legend. - - Include interactive data-driven widgets that allow the users to get information about the dataset and filter the information in the map. - - Formula widget showing the total revenue from all the stores - - Category widget showing the revenue by store type - - Histogram widget showing revenue buckets - - Search a location by address, city… using CARTO geocoding services through the Data Services API and zoom to the results. - - Display information about a feature when hovering over. When we hover over the store, we will display a pop-up or tooltip with the total revenue for the store. - - Select a feature and display detailed information. When we click on a store, the map will be centered in the location and the store will be highlighted. It demostrates how you can use CARTO SQL API to create spatial queries against CARTO. The following information will be displayed in the sidebar: - - Total revenue of the store - - Histogram (line chart) with the store revenue per month, showing the average per month of all stores for comparison - - Calculate an isochrone using CARTO Data Services API. We can select a store from a list in the sidebar and calculate isochrones specifying the mode (car or walking) and range (time in minutes) - -- **KPI view**. This view shows how to build a geospatial bussiness dashboard by creating a KPI in a few lines of code: - - Visualize a CARTO dataset using a choropleth map with manual breaks where the store color depends on the total revenue per area and create a corresponding legend. - - Include interactive data-driven widgets that allow the users to get information about the dataset and filter the information in the map. - - Formula widget with the total revenue from all stores - - Category widget showing the total revenue per area - - Histogram widget showing the total revenue per month - -## Code Generator - -We use [Hygen](https://www.hygen.io/) to generate the code of the most common operations. - -Create a new View: - -```bash -yarn hygen view new -``` - -Create a new Source: - -```bash -yarn hygen source new -``` - -Create a new Layer (and attach to the previous Source, and optionally previous View): - -```bash -yarn hygen layer new -``` - -For further information: - -```bash -yarn hygen help -``` - -## Developer Notes - -To develop the template itself you need to create a `package.json` file in the template folder and add it to the gitignore list, as this file would overwrite the one created by create-react-app when used. This is as easy as follows: - -```bash -git clone https://github.com/CartoDB/carto-react-template.git -cd carto-react-template -cp -R hygen/_templates/ template-sample-app/template/_templates -cp -R hygen/_templates/ template-skeleton/template/_templates -cd template-sample-app/template -ln -s package.dev.json package.json -cd template-skeleton/template -ln -s package.dev.json package.json -``` - -Then you are ready to install the dependencies executing `yarn` in the template folder and start the development server with `yarn start`. - -### Testing the template generation - -> ⚠️ Important: remember to synchronize the changes applied to your `template/package.json` with `template.json` and remove the `template/package.json` file before testing or execute `yarn clean` to clean it automatically. - -You can test the template locally by calling `create-react-app` specifying the folder of this project: - -```bash -npx create-react-app test-template --template file:./carto-react-template/template-sample-app -``` - -### Publishing the template to npm - -> ⚠️ Important: remember to set the right version for each template, tag the release in the GitHub repository and deploy the sample app with the latest changes - -For each template, execute the release command from their **base folder**. This folder will clean all unnecesary development files and folders and copy the hygen templates. - -```bash -cd template-sample-app -yarn release -``` - - -### Deploying the sample app - -The sample app is hosted in Firebase, so before deploying it you'll need to log into Firebase using: - -```bash -cd template-sample-app/template -yarn firebase login -``` - -Then, just build the sample-app template and deploy it by executing: - -```bash -cd template-sample-app/template -yarn build -yarn firebase deploy -``` -### Updating supported browsers - -This project supports [browserslist](https://github.com/browserslist/browserslist) and has an unsupported browser page. In case of updating browserslist configuration, ensure to update the detection script by running: - -```bash -yarn updateSupportedBrowsers -``` - -### Using locally the CARTO for React lib packages - -In order to work with a local version of the `CARTO for React lib` packages (`@carto/react-*`) follow these instructions: - -```bash -git clone https://github.com/CartoDB/carto-react-lib.git -cd react -yarn -yarn build -yarn link-all -``` - -Now that all packages are compiled, link them into `carto-react-template` with: - -```bash -cd carto-react-template -cd template-sample-app/template -yarn link-carto-react -yarn start - -cd template-skeleton/template -yarn link-carto-react -yarn start -``` - -In this moment, template-sample-app or template-skeleton will be using your local version of the library packages. diff --git a/docs/guides/01_connect_your_account.md b/docs/guides/01_connect_your_account.md deleted file mode 100644 index 24c1e3f2..00000000 --- a/docs/guides/01_connect_your_account.md +++ /dev/null @@ -1,25 +0,0 @@ - -# Connect your CARTO account - -As a first step you need to connect your CARTO account. - -Edit `src/store/initialStateSlice.js` file and add your own credentials. - -```javascript - ... - credentials: { - username: '', - apiKey: '', - serverUrlTemplate: 'https://{user}.carto.com', - }, - ... - }, -``` - -The API KEY could be set to `default_public` if you're dealing with public datasets and you don't need to use dataservices (geocoding, routing or isochrones). - -If you're dealing with private data and/or data services you need to provide a valid [API KEY](https://carto.com/developers/auth-api/guides/CARTO-Authorization/). - -OAuth Apps are available for more complex use cases, we'll cover this later on [Permissions and user management](04_permissions_user_management.md). - -Once you've connected your account, jump to the next guide [Create a page with a layer and widgets](02_page_layer_widgets.md). diff --git a/docs/guides/02_page_layer_widgets.md b/docs/guides/02_page_layer_widgets.md deleted file mode 100644 index c5fa9739..00000000 --- a/docs/guides/02_page_layer_widgets.md +++ /dev/null @@ -1,299 +0,0 @@ -# Create a page with a layer and widgets - -On this guide we're going to explain how to create a new page with a layer and 2 widgets. - -#### Before to start - -During this guide, we're going to be using the code generator called [Hygen](http://www.hygen.io/). For the proper working of Hygen some commented lines are necessary to indicate where to put some generated lines. The commented lines begin with `[hygen]`, so **please** don't delete them, otherwise hygen won't work properly. - -### Upload the dataset - -Go to your dashboard and click on `New Dataset`->`Upload`. - -Copy the following URL and click on `Submit` - -```url -https://public.carto.com/api/v2/sql?filename=retail_stores&q=select+*+from+public.retail_stores&format=shp -``` - -If you want to access the dataset from the application, you can make it public. You can also create an [API KEY](https://carto.com/developers/auth-api/guides/CARTO-Authorization/) and keep them private. Totally up to you. - -### Create a view - -Now, we're going to create a view called Stores that respond to the path `/stores`. - -There is an interactive command to generate the code required for a View: - -```bash -yarn hygen view new -``` - -And answer the following: - -```bash -✔ Name: Stores -✔ Route path: /stores -✔ Do you want a link in the menu? (y/N) y -``` - -It'll modify the routes to add the `/stores` path, add the view to the Header and create the new View at `src/components/views/Stores.js` - -Now you're ready to start the server: - -```bash -yarn -yarn start -``` - -You should see the map with a `Hello World` on the left sidebar. - -### Create a source - -A Source is a piece code that connects to CARTO backend services to fetch features from a dataset. Layers and Widgets both depend on the sources. That's why it's important to know how to create them correctly. - -The sources and the models are the only one pieces that connect with the CARTO backend, but there are some differences: - -1. The model exports simple functions that receive parameters and make a request to receive the values that feed a view. That request can be against the CARTO SQL API or your own backend. -2. The source exports a plain object with a certain structure that will be understood by CARTO React library to feed layers and widgets. - -Both model and source folders can be found inside the `/data` folder: - -``` -└── data - ├── models - └── sources -``` - -The goal of `/data` folder is to easily differentiate the parts of the project that have a communication with external services, like CARTO APIs, your own backend, geojson files or whatever. - -To create a source you can use hygen: - -```yarn hygen source new``` - -In this case, we're going to create a new source that can feed a layer & widgets with the dataset we uploaded before. In this case, it's going to be called `StoresSource` (source suffix is optional, but recommended): - -```bash -✔ Name: StoresSource -✔ Choose type: SQL dataset -✔ Type a query: select cartodb_id, store_id, storetype, revenue, address, the_geom_webmercator from retail_stores -``` - -After filling all the requirements, it creates a new file `src/data/sources/storesSource.js` that will contains the following basic structure: - -```javascript -const STORES_SOURCE_ID = 'StoresSource'; - -const source = { - id: STORES_SOURCE_ID, - data: ` - select cartodb_id, store_id, storetype, revenue, address, the_geom_webmercator from retail_stores - `, - type: 'sql', -}; - -export default source; -``` - -This structure can be improved and it's **recommended** to follow those improvements: create a new constant called `STORES_SOURCE_COLUMNS` that exposes the columns that will be used, for example, in widgets. An example would be a widget that sum the revenues, then we will have: - -```javascript -export const STORES_SOURCE_COLUMNS = { - REVENUE: 'revenue', - STORE_TYPE: 'storeType', -} - -export default { - id: STORES_SOURCE_ID, - data: ` - select - store_id, - storetype as ${STORES_SOURCE_COLUMNS.STORE_TYPE}, - revenue as ${STORES_SOURCE_COLUMNS.REVENUE}, - address, - the_geom_webmercator - from retail_stores - `, - type: 'sql', -}; -``` - -Doing that, our code will be less likely to have bugs due to future changes in the model of the database; you will use in the widgets `STORES_SOURCE_COLUMNS.REVENUE` and you won't care about how revenue is recovered or which is the column that contains that value. It's better for big teams with different roles, where the backend engineer takes the responsability to define the models and sources and the frontender just consumes them in a safe way using constants defined by the backend. - -### Create a layer - -We're going to visualize now the source we've just created. - -Let's create the required code for the Layer: - -```bash -yarn hygen layer new -``` - -And answer the following (be sure you attach the layer to the view previously created): - -```bash -✔ Name: StoresLayer -✔ Choose a source: StoresSource -✔ Do you want to attach to some view (y/N) y -✔ Choose a view: Stores -``` - -It'll create a new layer file `src/components/layers/StoresLayer.js`, if you check the code of `src/components/views/Stores.js` you will see how the layer is attached. - -If you reload now, you'll see the new layer in the map. - -The code that has been added to the view is: - -```javascript - import { STORES_LAYER_ID } from 'components/layers/StoresLayer'; - import storesSource from 'data/sources/storesSource'; - - useEffect(() => { - // Add the source to the store - dispatch( - addSource(storesSource) - ); - - // Add the layer to the store - dispatch( - addLayer({ - id: STORES_LAYER_ID, - source: storesSource.id, - }) - ); - - // Cleanup - return () => { - dispatch(removeLayer(STORES_LAYER_ID)); - dispatch(removeSource(storesSource.id)); - }; - }, [dispatch]); -``` - -`dispatch` function dispatches an action to Redux store. This is how this works: - -1. The view dispatches the new source to the store. -2. The view dispatches the new layer to the store. -3. The Map Component is re-rendered since the store has changed. -4. The Map Component get all the layers in the store and draw them. - -That's reactive programming, we can add the layer from any place of the application just dispatching the right action. - -Now let's take a look at `src/components/layers/StoresLayer.js`: - -```javascript -export const STORES_LAYER_ID = 'storesLayer'; - -export default function StoresLayer() { - // get the layer from the store - const { storesLayer } = useSelector((state) => state.carto.layers); - // get the source from the store - const source = useSelector((state) => selectSourceById(state, storesLayer?.source)); - // set required CARTO layer props, they manage the viewport changes and filters - // we'll explain what are the filters later in this guide with the widgets - const cartoLayerProps = useCartoLayerProps(source); - - if (storesLayer && source) { - // if the layer and the source are defined in the store - return new CartoSQLLayer({ - id: STORES_LAYER_ID, - data: source.data, - credentials: source.credentials, - getFillColor: [241, 109, 122], - pointRadiusMinPixels: 2 - ...cartoLayerProps, - }); - } -} -``` - -Summary: - -- To create a layer you need to: - 1. Define a function that returns a deck.gl layer. - 2. Exports the ID as a constant. -- The layer must be added to the application layers array. -- You need to add the source and the layer to the store. -- `cartoLayerProps` are required. - -### Create widgets - -Let's create a Formula and a Category Widget inside the View. - -Replace the text `Hello World` with: - -```javascript -
- - - - - -
-``` - -> **Note**: as you can see, we are using here the `STORES_SOURCE_COLUMNS` that we created before, instead of hardcoded column names. - -Add the following imports: - -```javascript -import { Divider } from '@material-ui/core'; -import { FormulaWidget, CategoryWidget, HistogramWidget } from '@carto/react-widgets'; -import { AggregationTypes } from '@carto/react-core'; -import { currencyFormatter } from 'utils/formatter'; -``` - -### Widgets source - -Two modes can be used: - -- Client-side widgets (default mode). Widgets will consume `viewport features` data, listening to the viewport changes. The viewport is part of the store, so any time it changes, the widget refresh to filter the data with the new viewport. It works with both 'bigquery' and 'sql' source types. -- Global: Only 'sql' sources can use this mode. Widgets will consume `global` data, without listening to the viewport changes. `viewportFilter` prop must be false. - - - -Remarks -* Setting `viewportFilter={true}` is the same as not specifying the prop, because the default value is true. -* BigQuery sources don't allow `viewportFilter` prop set to 'false'. Otherwise, you will get an error. - -## How the pieces work together - -There are two main elements in the store: the source and the viewport. - -The layer is filtered when the source changes. - -The widget is re-rendered when the source or viewport changes. - -Any time we change the viewport of the map (pan or zoom), the viewport changes and all the widgets (with the `viewportFilter` prop) are refreshed. - -Any time a widget applies a filter (for example clicking on a widget category), the filter is dispatched to the store: - -```javascript -dispatch( - addFilter({ - id: source.id, - column, - type: FilterTypes.IN, - values: categories - }) -) -``` - -The filter is a change in the source, so it forces to re-render the widgets and filter layers that uses the same source. - -The map applies filters using `DataFilterExtension` from deck.gl, applying the current filters of the source. diff --git a/docs/guides/03_basemap.md b/docs/guides/03_basemap.md deleted file mode 100644 index 75c46841..00000000 --- a/docs/guides/03_basemap.md +++ /dev/null @@ -1,35 +0,0 @@ -# CARTO and Google Basemaps - -It is quite easy to change the basemap for the application. By default, the application will use the CARTO Positron basemap, but you can choose any other CARTO basemap (Dark Matter, Voyager) or you can also use a Google basemap. - -
- -| BASEMAP | PREVIEW -| -----|--------- -| POSITRON | | https://basemaps.cartocdn.com/gl/positron-gl-style/style.json | -| DARK_MATTER | | https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json | -| VOYAGER | | https://basemaps.cartocdn.com/gl/voyager-gl-style/style.json | -| GOOGLE_ROADMAP | No preview available yet | -| GOOGLE_SATELLITE | No preview available yet | -| GOOGLE_HYBRID | No preview available yet | - -
- -You need to edit the `src/store/initialStateSlice.js` file. At the beginning of this file we are importing the basemap from the `@carto/react` package. - -If you want to use the Google road basemap, you need to import it like this: - -```javascript -import { GOOGLE_ROADMAP } from '@carto/react-basemaps'; -``` - -Then you need to modify the "basemap" property in the initialState object: - -```javascript -export const initialState = { - ... - basemap: GOOGLE_ROADMAP, - googleApiKey: 'AAAAABBBBBBBCCCCCCC11111122222233333', - ... -}; -``` diff --git a/docs/guides/04_permissions_user_management.md b/docs/guides/04_permissions_user_management.md deleted file mode 100644 index 1d802896..00000000 --- a/docs/guides/04_permissions_user_management.md +++ /dev/null @@ -1,40 +0,0 @@ - -# Permissions and user management - -CARTO supports [OAuth](https://en.wikipedia.org/wiki/OAuth) to communicate with our [APIs](https://carto.com/developers/). OAuth is the preferred way to manage credentials, so we recommend you use this protocol for implementing **authentication & authorization** in your applications. - -OAuth `scopes` are used to specify what permissions will users have to give to the application. For example, `datasets:r:table_name` will grant `read` access to the table `table_name`. - -The workflow is: - -1) You login with the desired scopes. -2) You get an API_KEY (token) to call CARTO APIs but restricted to the requested scopes. - -The first thing you need to do is go to your CARTO dashboard and create a new OAuth app as described in the [documentation](https://carto.com/developers/fundamentals/authorization/#oauth-apps), in order to get the clientID for your application. - -Then, edit the `src/store/initialStateSlice.js` file and modify the clientId property in the `oauthInitialState` object. You can also modify the `scopes` property to specify what permissions you want to give the application. - -When you want the users to authenticate and give access to their CARTO account (it can be when loading the application or when you are using a restricted feature), you need to use the OAuthLogin component. This will display a popup with the implicit OAuth flow. - -Once the flow has been completed you can get the user credentials like this: - -```javascript -import { selectOAuthCredentials } from '@carto/react-redux'; -const credentials = useSelector(selectOAuthCredentials); -``` - -This credentials can be used, for instance, when adding a new data source: - -```javascript -dispatch( - addSource({ - id: '', - data: '', - credentials, - }) -); -``` - -Or to call directly to our APIs from your models. You have an example of this at [IsochroneModel](https://github.com/CartoDB/carto-react-template/blob/develop/template-sample-app/template/src/models/IsochroneModel.js). - -The credentials object contains the username and the API key, so you can use them to call any of the CARTO REST APIs endpoints. diff --git a/docs/guides/05_look_and_feel.md b/docs/guides/05_look_and_feel.md deleted file mode 100644 index 7197d565..00000000 --- a/docs/guides/05_look_and_feel.md +++ /dev/null @@ -1,33 +0,0 @@ -# Look and feel - -When you are building your own application, you usually want to adapt the look & feel to use a different typography or define your own primary and secondary colors. - -The user interface components are based on Material-UI. We have created a default CARTO theme. You can customize the theme by changing the theme configuration variables. You can find the variables defined for the CARTO theme in the carto-theme.js file in the @carto/react package. - -There are lots of properties that you can adapt to your needs. Some of the main configuration properties are: - -- [palette](https://material-ui.com/customization/palette/). Definition of colors (primary, secondary, error, warning…) -- [typography](https://material-ui.com/customization/typography/). Default font family, heading styles, body styles… -- [breakpoints](https://material-ui.com/customization/breakpoints/). Support for different screen sizes. - -For instance, if you want to change the main color (used for the navigation bar background), you can edit the `App.js` file and add the following instruction before the theme creation: - -```javascript -... -import { cartoThemeOptions } from '@carto/react-ui'; -... -cartoThemeOptions.palette.primary.main = "#800000"; -let theme = createMuiTheme(cartoThemeOptions); -... -``` - -If you want to change the font family for the application title (subtitle-1), you can add the following instruction before the theme creation: - -```javascript -... -import { cartoThemeOptions } from '@carto/react-ui'; -... -cartoThemeOptions.typography.subtitle1.fontFamily = "'Times New Roman'"; -let theme = createMuiTheme(cartoThemeOptions); -... -``` \ No newline at end of file diff --git a/template-sample-app/package.json b/template-sample-app/package.json index 3a6f118d..f2b56cdc 100644 --- a/template-sample-app/package.json +++ b/template-sample-app/package.json @@ -24,7 +24,8 @@ "build": "cd template && react-scripts build", "test": "cd template && react-scripts test", "clean": "cd template && rm -rf build && rm -rf _templates && rm -rf node_modules && rm -f package.json && rm -f yarn.lock && rm -f package-lock.json", - "release": "yarn clean && cp template/README.md README.md && cp -r ../hygen/_templates template/_templates && sync && yarn publish --access public --non-interactive" + "prerelease": "yarn clean && cp template/README.md README.md && cp -r ../hygen/_templates template/_templates && sync", + "release": "yarn publish --access public --non-interactive" }, "husky": { "hooks": { diff --git a/template-sample-app/template.json b/template-sample-app/template.json index 0ad3abd5..6f36312b 100644 --- a/template-sample-app/template.json +++ b/template-sample-app/template.json @@ -1,13 +1,13 @@ { "package": { "dependencies": { - "@carto/react-api": "0.0.1-rc.5", - "@carto/react-auth": "0.0.1-rc.5", - "@carto/react-basemaps": "0.0.1-rc.5", - "@carto/react-core": "0.0.1-rc.5", - "@carto/react-redux": "0.0.1-rc.5", - "@carto/react-ui": "0.0.1-rc.5", - "@carto/react-widgets": "0.0.1-rc.5", + "@carto/react-api": "0.0.1-rc.6", + "@carto/react-auth": "0.0.1-rc.6", + "@carto/react-basemaps": "0.0.1-rc.6", + "@carto/react-core": "0.0.1-rc.6", + "@carto/react-redux": "0.0.1-rc.6", + "@carto/react-ui": "0.0.1-rc.6", + "@carto/react-widgets": "0.0.1-rc.6", "@formatjs/intl-getcanonicallocales": "^1.5.3", "@formatjs/intl-locale": "^2.4.14", "@formatjs/intl-numberformat": "^6.1.4", diff --git a/template-sample-app/template/package.dev.json b/template-sample-app/template/package.dev.json index 8200c857..c1a10692 100644 --- a/template-sample-app/template/package.dev.json +++ b/template-sample-app/template/package.dev.json @@ -3,13 +3,13 @@ "version": "1.0.0-beta12", "private": true, "dependencies": { - "@carto/react-api": "0.0.1-rc.5", - "@carto/react-auth": "0.0.1-rc.5", - "@carto/react-basemaps": "0.0.1-rc.5", - "@carto/react-core": "0.0.1-rc.5", - "@carto/react-redux": "0.0.1-rc.5", - "@carto/react-ui": "0.0.1-rc.5", - "@carto/react-widgets": "0.0.1-rc.5", + "@carto/react-api": "0.0.1-rc.6", + "@carto/react-auth": "0.0.1-rc.6", + "@carto/react-basemaps": "0.0.1-rc.6", + "@carto/react-core": "0.0.1-rc.6", + "@carto/react-redux": "0.0.1-rc.6", + "@carto/react-ui": "0.0.1-rc.6", + "@carto/react-widgets": "0.0.1-rc.6", "@formatjs/intl-getcanonicallocales": "^1.5.3", "@formatjs/intl-locale": "^2.4.14", "@formatjs/intl-numberformat": "^6.1.4", diff --git a/template-skeleton/package.json b/template-skeleton/package.json index 9d1cba7b..1f0cf09a 100644 --- a/template-skeleton/package.json +++ b/template-skeleton/package.json @@ -24,7 +24,8 @@ "build": "cd template && react-scripts build", "test": "cd template && react-scripts test", "clean": "cd template && rm -rf build && rm -rf _templates && rm -rf node_modules && rm -f package.json && rm -f yarn.lock && rm -f package-lock.json", - "release": "yarn clean && cp template/README.md README.md && cp -r ../hygen/_templates template/_templates && sync && yarn publish --access public --non-interactive" + "prerelease": "yarn clean && cp template/README.md README.md && cp -r ../hygen/_templates template/_templates && sync", + "release": "yarn publish --access public --non-interactive" }, "husky": { "hooks": { diff --git a/template-skeleton/template.json b/template-skeleton/template.json index 0ad3abd5..6f36312b 100644 --- a/template-skeleton/template.json +++ b/template-skeleton/template.json @@ -1,13 +1,13 @@ { "package": { "dependencies": { - "@carto/react-api": "0.0.1-rc.5", - "@carto/react-auth": "0.0.1-rc.5", - "@carto/react-basemaps": "0.0.1-rc.5", - "@carto/react-core": "0.0.1-rc.5", - "@carto/react-redux": "0.0.1-rc.5", - "@carto/react-ui": "0.0.1-rc.5", - "@carto/react-widgets": "0.0.1-rc.5", + "@carto/react-api": "0.0.1-rc.6", + "@carto/react-auth": "0.0.1-rc.6", + "@carto/react-basemaps": "0.0.1-rc.6", + "@carto/react-core": "0.0.1-rc.6", + "@carto/react-redux": "0.0.1-rc.6", + "@carto/react-ui": "0.0.1-rc.6", + "@carto/react-widgets": "0.0.1-rc.6", "@formatjs/intl-getcanonicallocales": "^1.5.3", "@formatjs/intl-locale": "^2.4.14", "@formatjs/intl-numberformat": "^6.1.4", diff --git a/template-skeleton/template/package.dev.json b/template-skeleton/template/package.dev.json index 8200c857..c1a10692 100644 --- a/template-skeleton/template/package.dev.json +++ b/template-skeleton/template/package.dev.json @@ -3,13 +3,13 @@ "version": "1.0.0-beta12", "private": true, "dependencies": { - "@carto/react-api": "0.0.1-rc.5", - "@carto/react-auth": "0.0.1-rc.5", - "@carto/react-basemaps": "0.0.1-rc.5", - "@carto/react-core": "0.0.1-rc.5", - "@carto/react-redux": "0.0.1-rc.5", - "@carto/react-ui": "0.0.1-rc.5", - "@carto/react-widgets": "0.0.1-rc.5", + "@carto/react-api": "0.0.1-rc.6", + "@carto/react-auth": "0.0.1-rc.6", + "@carto/react-basemaps": "0.0.1-rc.6", + "@carto/react-core": "0.0.1-rc.6", + "@carto/react-redux": "0.0.1-rc.6", + "@carto/react-ui": "0.0.1-rc.6", + "@carto/react-widgets": "0.0.1-rc.6", "@formatjs/intl-getcanonicallocales": "^1.5.3", "@formatjs/intl-locale": "^2.4.14", "@formatjs/intl-numberformat": "^6.1.4",