Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.
Improved Props and Gettings Started Docs (#2993)
ironicbrew7e2db2b7dec7
diff --git a/README.md b/README.mdindex ff5729faf..665086c18 100644--- a/README.md+++ b/README.md@@ -149,122 +149,32 @@ const Map = props => ();```-#### Props--##### `id` (String, required)--- Default: `map`--The id of this KeplerGl instance. `id` is required if you have multiple-KeplerGl instances in your app. It defines the prop name of the KeplerGl state that is-stored in the KeplerGl reducer. For example, the state of the KeplerGl component with id `foo` is-stored in `state.keplerGl.foo`.--In case you create multiple kepler.gl instances using the same id, the kepler.gl state defined by the entry will be-overridden by the latest instance and reset to a blank state.--##### `mapboxApiAccessToken` (String, required\*)--- Default: `undefined`--By default, kepler.gl uses mapbox-gl.js to render its base maps. You can create a free account at [mapbox][mapbox] and create a token at [www.mapbox.com/account/access-tokens][mapbox-token].--If you replaced kepler.gl default map styles with your own, and they are not Mapbox styles. `mapboxApiAccessToken` will not be required.--Read more about [Custom Map Styles][custom-map-styles].--##### `getState` (Function, optional)--- Default: `state => state.keplerGl`--The path to the root keplerGl state in your reducer.--##### `width` (Number, optional)--- Default: `800`--Width of the KeplerGl UI.--##### `height` (Number, optional)--- Default: `800`--##### `appName` (String, optional)--- Default: `Kepler.Gl`--App name displayed in side panel header--##### `version` (String, optional)--- Default: `v1.0`--version displayed in side panel header--##### `onSaveMap` (Function, optional)--- Default: `undefined`--Action called when click Save Map Url in side panel header.--##### `onViewStateChange` (Function, optional)--- Default: `undefined`-- Parameter: `viewState` - An updated view state object containing parameters such as longitude, latitude, zoom etc--Action triggered when map viewport is updated.--##### `getMapboxRef(mapbox, index)` (Function, optional)--- Default: `undefined`--Function called when `KeplerGL` adds or removes a `MapContainer` component having an inner Mapbox map.--The `mapbox` argument is an [`MapRef`](https://visgl.github.io/react-map-gl/docs/api-reference/types#mapref) when added or `null` when removed.--The `index` argument is 0 for a single map or 1 for an additional map (since `KeplerGL` supports an optional split map view).--##### `actions` (Object, optional)--- Default: `{}`--Actions creators to replace default kepler.gl action creator. Only use custom action when you want to modify action payload.--##### `mint` (Boolean, optional)--- Default: `true`--Whether to load a fresh empty state when component is mounted. when parse `mint: true` kepler.gl component will always load a fresh state when re-mount the same component, state inside this component will be destroyed once its unmounted.-By Parsing `mint: false` kepler.gl will keep the component state in the store even when it is unmounted, and use it as initial state when re-mounted again. This is useful when mounting kepler.gl in a modal, and keep the same map when re-open.--Read more about [Components][components].--##### `theme` (Object | String, optional)--- default: `null`--One of `"dark"`, `"light"` or `"base"`-You can pass theme name or object used to customize Kepler.gl style. Kepler.gl provide an `'light'` theme besides the default 'dark' theme. When pass in a theme object Kepler.gl will use the value passed as input to override values from [theme](https://github.com/keplergl/kepler.gl/blob/master/src/styles/base.js).--Read more about [Custom Theme][custom-theme]--#### `mapboxApiUrl` (String, optional)--- Default: `https://api.mapbox.com`--If you are using your own mapbox tile server, you can pass in your own tile server api url.--#### `mapStylesReplaceDefault` (Boolean, optional)--- Default: `false`--kepler.gl provide 4 map styles to choose from. Pass `true` if you want to supply your own `mapStyles`. See Below.--#### `mapStyles` (Array, optional)--- Default: `[]`--You can supply additional map styles to be displayed in [map style selection panel](https://github.com/keplergl/kepler.gl/blob/master/docs/user-guides/f-map-styles/1-base-map-styles.md). By default, additional map styles will be added to default map styles. If pass `mapStylesReplaceDefault: true`, they will replace the default ones. kepler.gl will attempt to group layers of your style based on its `id` naming convention and use it to allow toggle visibility of [base map layers](https://github.com/keplergl/kepler.gl/blob/master/docs/user-guides/f-map-styles/2-map-layers.md). Supply your own `layerGroups` to override default for more accurate layer grouping.+### Props++| Prop Name | Type | Default Value | Description |+|-------------------------------|-------------|----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|+| `id` | String | `map` | The unique identifier for the KeplerGl instance. Required when multiple KeplerGl instances exist. It maps to the state in the reducer (e.g. component with id `foo` can be found in`state.keplerGl.foo`). |+| `mapboxApiAccessToken` | String | `undefined` | API token for Mapbox, used for rendering base maps. Create a free token at [Mapbox](https://www.mapbox.com). |+| `getState` | Function | `state => state.keplerGl` | Function that specifies the path to the root KeplerGl state in the reducer. |+| `width` | Number | `800` | The width of the KeplerGl UI in pixels. |+| `height` | Number | `800` | The height of the KeplerGl UI in pixels. |+| `appName` | String | `Kepler.Gl` | The app name displayed in the side panel header. |+| `version` | String | `v1.0` | The version displayed in the side panel header. |+| `onSaveMap` | Function | `undefined` | A function called when the "Save Map URL" in side panel header is clicked. |+| `onViewStateChange` | Function | `undefined` | Triggered when the map viewport is updated. Receives `viewState` parameter with updated values like longitude, latitude, zoom, etc. |+| `getMapboxRef(mapbox, index)` | Function | `undefined` | Called when `KeplerGl` adds or removes a MapContainer with an inner Mapbox map. `mapbox` is a `MapRef` when added, or `null` when removed. `index` is `0` for the first map and `1` for the second map in a split view. |+| `actions` | Object | `{}` | Custom action creators to override the default KeplerGl action creators. Only use custom action when you want to modify action payload. |+| `mint` | Boolean | `true` | Determines whether to load a fresh empty state when mounted. When `false`, the state persists across remounts. Useful for modal use cases. |+| `theme` | Object/String| `null` | Set to `"dark"`, `"light"`, or `"base"`, or pass a theme object to customize KeplerGl’s style. |+| `mapboxApiUrl` | String | `https://api.mapbox.com` | The Mapbox API URL if you are using a custom Mapbox tile server. |+| `mapStylesReplaceDefault` | Boolean | `false` | Set to `true` to replace default map styles with custom ones. (see ```mapStyles``` prop) |+| `mapStyles` | Array | `[]` | An array of [custom map styles](#example-custom-map-style) for the map style selection panel. Styles replace the default ones if `mapStylesReplaceDefault` is `true`. |+| `initialUiState` | Object | `undefined` | The initial UI state applied to the `uiState` reducer. |+| `localeMessages` | Object | `undefined` | Used to modify or add new translations. Read more about [Localization][localization]. |++#### Example Custom Map Style++You can supply additional map styles to be displayed in [map style selection panel](https://github.com/keplergl/kepler.gl/blob/master/docs/user-guides/f-map-styles/1-base-map-styles.md). By default, additional map styles will be added to default map styles. If you pass `mapStylesReplaceDefault: true`, they will replace the default ones. kepler.gl will attempt to group layers of your style based on its `id` naming convention and use it to allow toggle visibility of [base map layers](https://github.com/keplergl/kepler.gl/blob/master/docs/user-guides/f-map-styles/2-map-layers.md). Supply your own `layerGroups` to override default for more accurate layer grouping.Each `mapStyles` should has the following properties:@@ -288,7 +198,6 @@ const mapStyles = [defaultVisibility: true},{- // adding this will keep the 3d building optionslug: '3d building',filter: () => false,defaultVisibility: false@@ -298,20 +207,6 @@ const mapStyles = [];```-Read more about [Custom Map Styles][custom-map-styles].--#### `initialUiState` (object, optional)--- Default: `undefined`--Intial UI State applied to uiState reducer, value will be shallow merged with default [`INITIAL_UI_STATE`](https://docs.kepler.gl/docs/api-reference/reducers/ui-state#initial_ui_state)--#### `localeMessages` (object, optional)--- Default: `undefined` Modify default translation or add new translation--Read more about [Localization][localization].-### 3. Dispatch custom actions to `keplerGl` reducer.One advantage of using the reducer over React component state to handle keplerGl state is the flexibilitydiff --git a/docs/api-reference/get-started.md b/docs/api-reference/get-started.mdindex 5a17d8e3f..e86cbc135 100644--- a/docs/api-reference/get-started.md+++ b/docs/api-reference/get-started.md@@ -16,6 +16,77 @@ Kepler.gl is built on top of [Mapbox GL](https://www.mapbox.com). A mapbox accou![Basic Usage][basic-usage]+#### 0. Working Template++```js+import * as React from "react";+import ReactDOM from "react-dom/client";+import document from "global/document";++import { applyMiddleware, combineReducers, compose, createStore } from "redux";+import { connect, Provider } from "react-redux";++import keplerGlReducer, { enhanceReduxMiddleware } from "@kepler.gl/reducers";+import KeplerGl from "@kepler.gl/components";++import AutoSizer from "react-virtualized/dist/commonjs/AutoSizer";++const reducers = combineReducers({+ keplerGl: keplerGlReducer.initialState({+ uiState: {+ readOnly: false,+ currentModal: null,+ },+ }),+});++const middleWares = enhanceReduxMiddleware([+ // Add other middlewares here+]);++const enhancers = applyMiddleware(...middleWares);++const initialState = {};+const store = createStore(reducers, initialState, compose(enhancers));++const App2 = () => (+ <div+ style={{+ position: "absolute",+ top: "0px",+ left: "0px",+ width: "100%",+ height: "100%",+ }}+ >+ <AutoSizer>+ {({ height, width }) => (+ <KeplerGl+ mapboxApiAccessToken="xxx" // Replace with your mapbox token+ id="map"+ width={width}+ height={height}+ />+ )}+ </AutoSizer>+ </div>+);++const mapStateToProps = (state) => state;+const dispatchToProps = (dispatch) => ({ dispatch });+const ConnectedApp = connect(mapStateToProps, dispatchToProps)(App2);+const Root = () => (+ <Provider store={store}>+ <App2 />+ </Provider>+);++export default Root;+```++++#### 1. Mount reducerKepler.gl uses [Redux](https://redux.js.org/) to manage its internal state, along with [react-palm](https://github.com/btford/react-palm) middleware to handle side effects. Mount kepler.gl reducer in your store, apply `taskMiddleware`.