Skip to content

Latest commit

 

History

History
1552 lines (1102 loc) · 48.4 KB

actions.md

File metadata and controls

1552 lines (1102 loc) · 48.4 KB
Raw

Table of Contents

forwardActions

A set of helpers to forward dispatch actions to a specific instance reducer

forwardTo

Returns an action dispatcher that wraps and forwards the actions to a specific instance

Parameters

Examples

// action and forward dispatcher
import {toggleSplitMap, forwardTo} from '@kepler.gl/actions';
import {connect} from 'react-redux';

const MapContainer = props => (
 <div>
  <button onClick={() => props.keplerGlDispatch(toggleSplitMap())}/>
 </div>
)

const mapDispatchToProps = (dispatch, props) => ({
 dispatch,
 keplerGlDispatch: forwardTo(‘foo’, dispatch)
});

export default connect(
 state => state,
 mapDispatchToProps
)(MapContainer);

isForwardAction

Whether an action is a forward action

Parameters

  • action Object the action object

Returns boolean boolean - whether the action is a forward action

unwrap

Unwrap an action

Parameters

  • action Object the action object

Returns Object unwrapped action

wrapTo

Wrap an action into a forward action that only modify the state of a specific kepler.gl instance. kepler.gl reducer will look for signatures in the action to determine whether it needs to be forwarded to a specific instance reducer.

wrapTo can be curried. You can create a curried action wrapper by only supply the id argument

A forward action looks like this

 {
   type: "@@kepler.gl/LAYER_CONFIG_CHANGE",
   payload: {
     type: '@@kepler.gl/LAYER_CONFIG_CHANGE',
     payload: {},
     meta: {
      // id of instance
       _id_: id
      // other meta
     }
   },
   meta: {
     _forward_: '@redux-forward/FORWARD',
     _addr_: '@@KG_id'
   }
 };

Parameters

  • id string The id to forward to
  • action Object the action object {type: string, payload: *}

Examples

import {wrapTo, togglePerspective} from '@kepler.gl/actions';

// This action will only dispatch to the KeplerGl instance with `id: map_1`
this.props.dispatch(wrapTo('map_1', togglePerspective()));

// You can also create a curried action for each instance
const wrapToMap1 = wrapTo('map_1');
this.props.dispatch(wrapToMap1(togglePerspective()));

ActionTypes

Kepler.gl action types, can be listened by reducers to perform additional tasks whenever an action is called in kepler.gl

Type: Object

Examples

// store.js
import {handleActions} from 'redux-actions';
import {createStore, combineReducers, applyMiddleware} from 'redux';
import {taskMiddleware} from 'react-palm/tasks';

import keplerGlReducer from '@kepler.gl/reducers';
import {ActionTypes} from '@kepler.gl/actions';

const appReducer = handleActions(
  {
    // listen on kepler.gl map update action to store a copy of viewport in app state
    [ActionTypes.UPDATE_MAP]: (state, action) => ({
      ...state,
      viewport: action.payload
    })
  },
  {}
);

const reducers = combineReducers({
  app: appReducer,
  keplerGl: keplerGlReducer
});

export default createStore(reducers, {}, applyMiddleware(taskMiddleware));

mapStyleActions

Actions handled mostly by mapStyle reducer. They manage the display of base map, such as loading and receiving base map styles, hiding and showing map layers, user input of custom map style url.

addCustomMapStyle

Add map style from user input to reducer and set it to current style This action is called when user click confirm after putting in a valid style url in the custom map style dialog. It should not be called from outside kepler.gl without a valid inputStyle in the mapStyle reducer. param {void}

inputMapStyle

Input a custom map style object

Parameters

  • inputStyle Object
    • inputStyle.url string style url e.g. 'mapbox://styles/heshan/xxxxxyyyyzzz'
    • inputStyle.id string style url e.g. 'custom_style_1'
    • inputStyle.style Object actual mapbox style json
    • inputStyle.name string style name
    • inputStyle.layerGroups Object layer groups that can be used to set map layer visibility
    • inputStyle.icon Object icon image data url
  • mapState Object mapState is optional

loadCustomMapStyle

Callback when a custom map style object is received

Parameters

  • customMapStyle Object
    • customMapStyle.icon string
    • customMapStyle.style Object
    • customMapStyle.error any

loadMapStyleErr

Callback when load map style error

Parameters

  • error any

loadMapStyles

Callback when load map style success

Parameters

  • newStyles Object a {[id]: style} mapping

mapConfigChange

Update visibleLayerGroupsto change layer group visibility

Parameters

  • mapStyle Object new config {visibleLayerGroups: {label: false, road: true, background: true}}

mapStyleChange

Change to another map style. The selected style should already been loaded into mapStyle.mapStyles

Parameters

  • styleType string the style to change to

requestMapStyles

Request map style style object based on style.url.

Parameters

set3dBuildingColor

Set 3d building layer group color

Parameters

main

Main kepler.gl actions, these actions handles loading data and config into kepler.gl reducer. These actions is listened by all subreducers,

addDataToMap

Add data to kepler.gl reducer, prepare map with preset configuration if config is passed. Kepler.gl provides a handy set of utils to parse data from different formats to the data object required in dataset. You rarely need to manually format the data obejct.

Use KeplerGlSchema.getConfigToSave to generate a json blob of the currents instance config. The config object value will always have higher precedence than the options properties.

Kepler.gl uses dataId in the config to match with loaded dataset. If you pass a config object, you need to match the info.id of your dataset to the dataId in each layer, filter and interactionConfig.tooltips.fieldsToShow

Parameters

  • data Object
    • data.datasets (Array<Object> | Object) *required datasets can be a dataset or an array of datasets Each dataset object needs to have info and data property.
      • data.datasets.info Object -info of a dataset
        • data.datasets.info.id string id of this dataset. If config is defined, id should matches the dataId in config.
        • data.datasets.info.label string A display name of this dataset
      • data.datasets.data Object *required The data object, in a tabular format with 2 properties fields and rows
        • data.datasets.data.fields Array<Object> *required Array of fields,
          • data.datasets.data.fields.name string *required Name of the field,
        • data.datasets.data.rows Array<Array> *required Array of rows, in a tabular format with fields and rows
    • data.options Object
      • data.options.centerMap boolean default: true if centerMap is set to true kepler.gl will place the map view within the data points boundaries. options.centerMap will override config.mapState if passed in.
      • data.options.readOnly boolean default: false if readOnly is set to true the left setting panel will be hidden
      • data.options.keepExistingConfig boolean whether to keep exiting map data and associated layer filter interaction config default: false.
    • data.config Object this object will contain the full kepler.gl instance configuration {mapState, mapStyle, visState}

Examples

// app.js
import {addDataToMap} from '@kepler.gl/actions';

const sampleTripData = {
  fields: [
    {name: 'tpep_pickup_datetime', format: 'YYYY-M-D H:m:s', type: 'timestamp'},
    {name: 'pickup_longitude', format: '', type: 'real'},
    {name: 'pickup_latitude', format: '', type: 'real'}
  ],
  rows: [
    ['2015-01-15 19:05:39 +00:00', -73.99389648, 40.75011063],
    ['2015-01-15 19:05:39 +00:00', -73.97642517, 40.73981094],
    ['2015-01-15 19:05:40 +00:00', -73.96870422, 40.75424576]
  ]
};

const sampleConfig = {
  visState: {
    filters: [
      {
        id: 'me',
        dataId: 'test_trip_data',
        name: 'tpep_pickup_datetime',
        type: 'timeRange',
        view: 'enlarged'
      }
    ]
  }
};

this.props.dispatch(
  addDataToMap({
    datasets: {
      info: {
        label: 'Sample Taxi Trips in New York City',
        id: 'test_trip_data'
      },
      data: sampleTripData
    },
    options: {
      centerMap: true,
      readOnly: false,
      keepExistingConfig: false
    },
    info: {
      title: 'Taro and Blue',
      description: 'This is my map'
    },
    config: sampleConfig
  })
);

keplerGlInit

Initialize kepler.gl reducer. It is used to pass in mapboxApiAccessToken to mapStyle reducer.

Parameters

  • payload Object
    • payload.mapboxApiAccessToken string mapboxApiAccessToken to be saved to mapStyle reducer
    • payload.mapboxApiUrl string mapboxApiUrl to be saved to mapStyle reducer.
    • payload.mapStylesReplaceDefault Boolean mapStylesReplaceDefault to be saved to mapStyle reducer

receiveMapConfig

Pass config to kepler.gl instance, prepare the state with preset configs. Calling KeplerGlSchema.parseSavedConfig to convert saved config before passing it in is required.

You can call receiveMapConfig before passing in any data. The reducer will store layer and filter config, waiting for data to come in. When data arrives, you can call addDataToMap without passing any config, and the reducer will try to match preloaded configs. This behavior is designed to allow asynchronous data loading.

It is also useful when you want to prepare the kepler.gl instance with some preset layer and filter settings. Note Sequence is important, receiveMapConfig needs to be called before data is loaded. Currently kepler.gl doesn't allow calling receiveMapConfig after data is loaded. It will reset current configuration first then apply config to it.

Parameters

  • config Object *required The Config Object
  • options Object *optional The Option object
    • options.centerMap boolean default: true if centerMap is set to true kepler.gl will place the map view within the data points boundaries
    • options.readOnly boolean default: false if readOnly is set to true the left setting panel will be hidden
    • options.keepExistingConfig boolean whether to keep exiting layer filter and interaction config default: false.

Examples

import {receiveMapConfig} from '@kepler.gl/actions';
import KeplerGlSchema from '@kepler.gl/schemas';

const parsedConfig = KeplerGlSchema.parseSavedConfig(config);
this.props.dispatch(receiveMapConfig(parsedConfig));

resetMapConfig

Reset all sub-reducers to its initial state. This can be used to clear out all configuration in the reducer.

visStateActions

Actions handled mostly by visState reducer. They manage how data is processed, filtered and displayed on the map by operates on layers, filters and interaction settings.

addFilter

Add a new filter

Parameters

  • dataId string dataset id this new filter is associated with

Returns {type: ActionTypes.ADD_FILTER, dataId: dataId}

addLayer

Add a new layer

Parameters

  • props Object new layer props

Returns {type: ActionTypes.ADD_LAYER, props: props}

applyCPUFilter

Trigger CPU filter of selected dataset

Parameters

  • dataId (string | Arrary<string>) single dataId or an array of dataIds

Returns {type: ActionTypes.APPLY_CPU_FILTER, dataId: string}

enlargeFilter

Show larger time filter at bottom for time playback (apply to time filter only)

Parameters

  • idx Number index of filter to enlarge

Returns {type: ActionTypes.ENLARGE_FILTER, idx: idx}

interactionConfigChange

Update interactionConfig

Parameters

  • config Object new config as key value map: {tooltip: {enabled: true}}

Returns {type: ActionTypes.INTERACTION_CONFIG_CHANGE, config: config}

layerConfigChange

Update layer base config: dataId, label, column, isVisible

Parameters

  • oldLayer Object layer to be updated
  • newConfig Object new config

Returns {type: ActionTypes.LAYER_CONFIG_CHANGE, oldLayer: oldLayer, newConfig: newConfig}

layerTextLabelChange

Update layer text label

Parameters

  • oldLayer Object layer to be updated
  • idx Number -idx of text label to be updated
  • prop string prop of text label, e,g, anchor, alignment, color, size, field
  • value any new value

layerTypeChange

Update layer type. Previews layer config will be copied if applicable.

Parameters

  • oldLayer Object layer to be updated
  • newType string new type

Returns {type: ActionTypes.LAYER_TYPE_CHANGE, oldLayer: oldLayer, newType: newType}

layerVisConfigChange

Update layer visConfig

Parameters

  • oldLayer Object layer to be updated
  • newVisConfig Object new visConfig as a key value map: e.g. {opacity: 0.8}

Returns {type: ActionTypes.LAYER_VIS_CONFIG_CHANGE, oldLayer: oldLayer, newVisConfig: newVisConfig}

layerVisualChannelConfigChange

Update layer visual channel

Parameters

  • oldLayer Object layer to be updated
  • newConfig Object new visual channel config
  • channel string channel to be updated

Returns {type: ActionTypes.LAYER_VISUAL_CHANNEL_CHANGE, oldLayer: oldLayer, newConfig: newConfig, channel: channel}

loadFiles

Trigger file loading dispatch addDataToMap if succeed, or loadFilesErr if failed

Parameters

Returns {type: ActionTypes.LOAD_FILES, files: any}

loadFilesErr

Trigger loading file error

Parameters

  • error any

Returns {type: ActionTypes.LOAD_FILES_ERR, error: Object}

onLayerClick

Trigger layer click event with clicked object

Parameters

  • info Object Object clicked, returned by deck.gl

Returns {type: ActionTypes.LAYER_CLICK, info: info}

onLayerHover

Trigger layer hover event with hovered object

Parameters

  • info Object Object hovered, returned by deck.gl

Returns {type: ActionTypes.LAYER_HOVER, info: info}

onMapClick

Trigger map click event, unselect clicked object

Returns {type: ActionTypes.MAP_CLICK}

onMouseMove

Trigger map mouse moveevent, payload would be React-map-gl MapLayerMouseEvent https://visgl.github.io/react-map-gl/docs/api-reference/types#maplayermouseevent

Parameters

  • evt Object MapLayerMouseEvent

Returns {type: ActionTypes.MAP_CLICK}

removeDataset

Remove a dataset and all layers, filters, tooltip configs that based on it

Parameters

Returns {type: ActionTypes.REMOVE_DATASET, key: key}

removeFilter

Remove a filter from visState.filters, once a filter is removed, data will be re-filtered and layer will be updated

Parameters

  • idx Number idx of filter to be removed

Returns {type: ActionTypes.REMOVE_FILTER, idx: idx}

removeLayer

Remove a layer

Parameters

  • idx Number idx of layer to be removed

Returns {type: ActionTypes.REMOVE_LAYER, idx: idx}

reorderLayer

Reorder layer, order is an array of layer indexes, index 0 will be the one at the bottom

Parameters

Examples

// bring `layers[1]` below `layers[0]`, the sequence layers will be rendered is `1`, `0`, `2`, `3`.
// `1` will be at the bottom, `3` will be at the top.
this.props.dispatch(reorderLayer([1, 0, 2, 3]));

Returns {type: ActionTypes.REORDER_LAYER, order: order}

setEditorMode

Set the map mode

Parameters

  • mode string one of EDITOR_MODES

Examples

import {setMapMode} from '@kepler.gl/actions';
import {EDITOR_MODES} from '@kepler.gl/constants';

this.props.dispatch(setMapMode(EDITOR_MODES.DRAW_POLYGON));

setFilter

Update filter property

Parameters

  • idx Number -idx of filter to be updated
  • prop string prop of filter, e,g, dataId, name, value
  • value any new value
  • valueIndex Number array properties like dataset require index in order to improve performance

Returns {type: ActionTypes.SET_FILTER, idx: idx, prop: prop, value: value}

setFilterPlot

Set the property of a filter plot

Parameters

  • idx Number
  • newProp Object key value mapping of new prop {yAxis: 'histogram'}

Returns {type: ActionTypes.SET_FILTER_PLOT, idx: any, newProp: any}

setMapInfo

Set the property of a filter plot

Parameters

  • info
  • idx Number
  • newProp Object key value mapping of new prop {yAxis: 'histogram'}

Returns {type: ActionTypes.SET_FILTER_PLOT, idx: any, newProp: any}

showDatasetTable

Display dataset table in a modal

Parameters

  • dataId string dataset id to show in table

Returns {type: ActionTypes.SHOW_DATASET_TABLE, dataId: dataId}

toggleFilterAnimation

Start and end filter animation

Parameters

Returns {type: ActionTypes.TOGGLE_FILTER_ANIMATION, idx: idx}

toggleLayerForMap

Toggle visibility of a layer in a split map

Parameters

  • mapIndex Number index of the split map
  • layerId string id of the layer

Returns {type: ActionTypes.TOGGLE_LAYER_FOR_MAP, mapIndex: any, layerId: any}

updateAnimationTime

Reset animation

Parameters

  • value Number Current value of the slider

Returns {type: ActionTypes.UPDATE_ANIMATION_TIME, value: value}

updateFilterAnimationSpeed

Change filter animation speed

Parameters

  • idx Number idx of filter
  • speed Number speed to change it to. speed is a multiplier

Returns {type: ActionTypes.UPDATE_FILTER_ANIMATION_SPEED, idx: idx, speed: speed}

updateLayerAnimationSpeed

update trip layer animation speed

Parameters

  • speed Number speed to change it to. speed is a multiplier

Returns {type: ActionTypes.UPDATE_LAYER_ANIMATION_SPEED, speed: speed}

updateLayerBlending

Update layer blending mode

Parameters

  • mode string one of additive, normal and subtractive

Returns {type: ActionTypes.UPDATE_LAYER_BLENDING, mode: mode}

updateVisData

Add new dataset to visState, with option to load a map config along with the datasets

Parameters

  • datasets (Array<Object> | Object) *required datasets can be a dataset or an array of datasets Each dataset object needs to have info and data property.
    • datasets.info Object -info of a dataset
      • datasets.info.id string id of this dataset. If config is defined, id should matches the dataId in config.
      • datasets.info.label string A display name of this dataset
    • datasets.data Object *required The data object, in a tabular format with 2 properties fields and rows
      • datasets.data.fields Array<Object> *required Array of fields,
        • datasets.data.fields.name string *required Name of the field,
      • datasets.data.rows Array<Array> *required Array of rows, in a tabular format with fields and rows
  • options Object
    • options.centerMap boolean default: true if centerMap is set to true kepler.gl will place the map view within the data points boundaries
    • options.readOnly boolean default: false if readOnly is set to true the left setting panel will be hidden
  • config Object this object will contain the full kepler.gl instance configuration {mapState, mapStyle, visState}

Returns {type: ActionTypes.UPDATE_VIS_DATA, datasets: datasets, options: options, config: config}

uiStateActions

Actions handled mostly by uiState reducer. They manage UI changes in tha app, such as open and close side panel, switch between tabs in the side panel, open and close modal dialog for exporting data / images etc. It also manges which settings are selected during image and map export

addNotification

Add a notification to be displayed. Existing notification is going to be updated in case of matching ids.

Parameters

  • notification Object The notification object to be added

cleanupExportImage

Delete cached export image

hideExportDropdown

Hide side panel header dropdown, activated by clicking the share link on top of the side panel

openDeleteModal

Toggle active map control panel

Parameters

  • datasetId string id of the dataset to be deleted

removeNotification

Remove a notification

Parameters

  • id string id of the notification to be removed

setExportData

Whether to including data in map config, toggle between true or false

setExportDataType

Set data format for exporting data

Parameters

  • dataType string one of 'text/csv'

setExportFiltered

Whether to export filtered data, true or false

Parameters

  • payload boolean set true to ony export filtered data

setExportImageDataUri

Set exportImage.setExportImageDataUri to a dataUri

Parameters

  • dataUri string export image data uri

setExportImageSetting

Set exportImage settings: ratio, resolution, legend

Parameters

  • newSetting Object {ratio: '1x'}

setExportSelectedDataset

Set selected dataset for export

Parameters

setUserMapboxAccessToken

Whether we export a mapbox access token used to create a single map html file

Parameters

  • payload string mapbox access token

showExportDropdown

Hide and show side panel header dropdown, activated by clicking the share link on top of the side panel

Parameters

  • id string id of the dropdown

startExportingImage

Set exportImage.exporting to true

toggleMapControl

Toggle active map control panel

Parameters

toggleModal

Show and hide modal dialog

Parameters

toggleSidePanel

Toggle active side panel

Parameters

  • id string id of side panel to be shown, one of layer, filter, interaction, map

rootActions

Root actions managers adding and removing instances in root reducer. Under-the-hood, when a KeplerGl component is mounted or unmounted, it will automatically calls these actions to add itself to the root reducer. However, sometimes the data is ready before the component is registered in the reducer, in this case, you can manually call these actions or the corresponding updater to add it to the reducer.

deleteEntry

Delete an instance from keplerGlReducer. This action is called under-the-hood when a KeplerGl component is un-mounted to the dom. If mint is set to be true in the component prop, the instance state will be deleted from the root reducer. Otherwise, the root reducer will keep the instance state and later transfer it to a newly mounted component with the same id

Parameters

  • id string the id of the instance to be deleted

registerEntry

Add a new kepler.gl instance in keplerGlReducer. This action is called under-the-hood when a KeplerGl component is mounted to the dom. Note that if you dispatch actions such as adding data to a kepler.gl instance before the React component is mounted, the action will not be performed. Instance reducer can only handle actions when it is instantiated.

Parameters

  • payload Object
    • payload.id string *required The id of the instance
    • payload.mint boolean Whether to use a fresh empty state, when mint: true it will always load a fresh state when the component is re-mounted. When mint: false it will register with existing instance state under the same id, when the component is unmounted then mounted again. Default: true
    • payload.mapboxApiAccessToken string mapboxApiAccessToken to be saved in map-style reducer.
    • payload.mapboxApiUrl string mapboxApiUrl to be saved in map-style reducer.
    • payload.mapStylesReplaceDefault Boolean mapStylesReplaceDefault to be saved in map-style reducer.

renameEntry

Rename an instance in the root reducer, keep its entire state

Parameters

  • oldId string *required old id
  • newId string *required new id

mapStateActions

Actions handled mostly by mapState reducer. They manage map viewport update, toggle between 2d and 3d map, toggle between single and split maps.

fitBounds

Fit map viewport to bounds

Parameters

  • bounds Array<Number> as [lngMin, latMin, lngMax, latMax]

Examples

import {fitBounds} from '@kepler.gl/actions';
this.props.dispatch(fitBounds([-122.23, 37.127, -122.11, 37.456]));

togglePerspective

Toggle between 3d and 2d map.

Examples

import {togglePerspective} from '@kepler.gl/actions';
this.props.dispatch(togglePerspective());

toggleSplitMap

Toggle between single map or split maps

Parameters

  • index Number? index is provided, close split map at index

Examples

import {toggleSplitMap} from '@kepler.gl/actions';
this.props.dispatch(toggleSplitMap());

updateMap

Update map viewport

Parameters

  • viewport Object viewport object container one or any of these properties width, height, latitude longitude, zoom, pitch, bearing, dragRotate
    • viewport.width Number? Width of viewport
    • viewport.height Number? Height of viewport
    • viewport.zoom Number? Zoom of viewport
    • viewport.pitch Number? Camera angle in degrees (0 is straight down)
    • viewport.bearing Number? Map rotation in degrees (0 means north is up)
    • viewport.latitude Number? Latitude center of viewport on map in mercator projection
    • viewport.longitude Number? Longitude Center of viewport on map in mercator projection
    • viewport.dragRotate boolean? Whether to enable drag and rotate map into perspective viewport

Examples

import {updateMap} from '@kepler.gl/actions';
this.props.dispatch(
  updateMap({latitude: 37.75043, longitude: -122.34679, width: 800, height: 1200})
);

layerColorUIChange

Set the color palette ui for layer color

Parameters

  • oldLayer Object layer to be updated
  • prop String which color prop
  • newConfig object to be merged

setExportMapFormat

Set the export map format (html, json)

Parameters