MapView
The MapView is a component that renders a map with various geospatial data
layers.
Import
import { MapView } from '@dynatrace/strato-geo';
Use cases
The minimal representation of a MapView component is a base layer that
contains a world map.
The height of the MapView component must be set explicitly using the height
prop. The width of the MapView component will be determined by the width of
the parent container.
Learn more about the MapView props here.
Formatter
There are two other options in the formatter that allow for greater
customization. The first option enables you to prepend the unit to the value,
while the second option enables you to ignore the original unit and append a
custom string instead. Additionally, there is a custom formatter option
available to allow you to change the input unit to one of your choice, e.g.: if
the input unit is bits, you are able to switch and display the unit as
bytes, correctly formatted. The formatted value is applied in the tooltip and
the legend.
Truncation mode
The purpose of truncation is to gracefully handle extra long tooltips or legends
within data visualization components. By changing the value of this property,
you have control over where truncation is applied within charts. By default, the
truncation is applied to the middle value with the use of an ellipsis.
Truncation can, however be changed to instead be applied at the start or end
of data visualization component elements.
Controlled and uncontrolled states
The MapView component can be used in both controlled and uncontrolled states.
In the uncontrolled state it's possible to configure the initial longitude,
latitude and zoom level of the map using initialViewState prop. By default,
the map will be centered on the equator and zoomed out to show the whole world.
In the controlled state, user can attach state handlers to the MapView
component using the onViewStateChange prop, as well as dynamically change the
longitude, latitude and zoom level of the map.
Data layers
The MapView component supports rendering of data layers on the map using the
different subcomponents. Multiple data layers of the same type can be rendered.
The order of the data layers is determined by the order of the subcomponents of
the MapView component.
For detailed documentation about each data layer, please refer to the respective docs pages.
Color configuration
All data layers support multiple ways of color configuration. In general, there
are two ways of configuring colors: granular color configuration per layer using
a color prop, and color configuration using a legend.
Granular color configuration per layer
For a granular color customization of a single layer, layer's color prop
should be used. It supports a string or a callback that returns a string. The
string value should be any valid CSS color, including rgba, hex, transparent, or
a color name.
If string is provided, it will be used as a color for all data points in the layer, while providing a callback that receives a data point as an argument allows to customize the color per data point.
Color configuration using a legend
Using predefined legend subcomponents it's possible to easily set an advanced colors configuration for multiple data layers at once.
There are three legend subcomponents that can be used to configure colors of the
data layers: SequentialLegend, ThresholdLegend, and CategoricalLegend.
To connect a data layer to the legend, a color property of the layer should be
set to legend string. All data layers with legend color will be colored
according to the legend configuration. Only one legend subcomponent can be used
at a time.
As most of the data layer subcomponents have minimal required data properties of
latitude and longitude, the value associated with the data point must be
provided using the valueAccessor prop. The string provided as a value accessor
will be used to access the property of the data point object. Be aware, that
while some legends expect the value to be a numeric (SequentialLegend and
ThresholdLegend), other expect a string value (CategoricalLegend).
Sequential legend
The SequentialLegend subcomponent allows to automatically split the value
range of the data points into multiple even-sized buckets and assign a color to
each bucket. The sequential legend will automatically consider the minimum and
maximum values of data provided in all layers which have set the coloring prop
to legend and have valid value accessors referring to numerical values. The
value boundaries can be manually customised using the min and max numeric
props. To define a color palette to be used, a colorPalette prop should be
set. The colorPalette prop supports custom color palettes as an array of
string values, as well as variety of predefined color palettes ( see
coloring for more details).
The data layer's valueAccessor prop must reference a numeric property of the
data point object.
Threshold legend
The ThresholdLegend subcomponent is similar to the SequentialLegend, but
allows to define custom value ranges for each bucket. To configure the threshold
legend, an array of ranges must be provided using the ranges prop. Each range
must contain min and max props that define the range boundaries, and a
color prop. If a range contains an Infinity value, the value will be be
displayed as the maximum value present in the data, or as 0 if the data only
contains negative values. A -Infinity value will show the minimum value
present in the data, or 0 if the data only contains positive values.
The data layer's valueAccessor prop must reference a numeric property of the
data point object.
Categorical legend
The CategoricalLegend subcomponent allows mapping of a string value to a
specific color, thus creating a categorical color mapping. To configure the
categorical legend, an key-value object where every key is category name, and
every value is assigned color string can be provided as colorPalette prop.
When passing a predefined color palette, a key of the color palette item will be mapped to the equal category name (if found), and a value of the color palette item will be used as a color. If a category name is not found in the color palette, a default color of the data layer will be used.
The categorical legend supports legend items interactions. When hovering on a legend item name, data points of this category will be highlighted on the map. When hovering on a legend item icon, the opposite will happen - all other categories will be highlighted. When clicking left mouse button (LButton) on a legend item name, all other categories will be hidden.
Legend shared properties
All legend subcomponents support the following shared properties:
position- defines the position of the legend on the map. Supported options areright,bottom, andauto. The default value isauto, which will place the legend on the right side of the map if the map width is greater than the height, and on the bottom of the map otherwise.hidden- defines whether the legend should be hidden. The legend is visible by default.
Disputed borders and disabled state
The MapView component, when used in the Dynatrace infrastructure, supports
rendering of disputed borders. Read permissions should be set for fetching
disputed borders and map’s disabled state, there is more information about
permission scopes.
Depending on country code provided in the tenant configurations, relevant
disputed borders (if any) for that country will be rendered, if not the default
map will be shown.
The MapView component has an automatic disabled state. When set the respective
setting is configured in the client environment, the MapView component will
display a predefined message about the disabled state instead of the map.
Updating map display
By changing the include/exclude props the map display will be updated.
Zoom in and zoom out to see Spain with or without regions.
There can be also conditional layers rendering inside of map, zoom in and zoom
out to see ChoroplethLayer or DotLayer
Chart interactions
The MapView chart interaction provide flexible and easy way to explore your
data. To incorporate these interactions, the ChartInteractions component must
be added to the MapView. The chart interaction can then either be triggered
using keyboard shortcuts, mouse interactions, programmatically, or by the
optional chart toolbar. To enable the toolbar with the chart interactions, the
ChartToolbar subcomponent must be added to the MapView. The initial position
of the toolbar can be set using the placement prop.
Zoom and pan
There is a number of zoom interactions available for the MapView component.
In order to enable either of these zoom options on a chart it is necessary to
add the ChartInteractions.Zoom subcomponent to the ChartInteractions
component.
It's possible to zoom in/out when hovering a cursor over the chart and using
either a scroll wheel, pinching on a trackpad, double click LButton, or by
clicking LButton and holding Shift while dragging the cursor. To reset the
zoom to the initial state, a ChartToolbar reset button must be clicked.
A ChartToolbar component also provides a zoom-to-fit button that, when
clicked, will zoom the map to fit all the data points from all the data layers.
A zoom level determines how much of the world is visible on a map.There are 23 zoom levels in total supported, with 0 being the lowest zoom level (fully zoomed out) and 22 being the highest (fully zoomed in).
Zoom level breakdown by what is visible on the map:
- 0: The whole world
- 3: A continent
- 4: Large islands
- 6: Large rivers
- 10: Large rivers
- 15: Buildings
To pan a map, click and hold LButton and drag the cursor.
Download data as CSV
All the data from data layers can be download in CSV format using a toolbar
button. To enable this feature, a ChartToolbar subcomponent with
ChartToolbar.DownloadData inside of it must be provided. The CSV file will
contain two required columns: latitude and longitude. Depending on the shape
of the data point, all additional properties will be added as columns to the CSV
file.
It's also possible to programmatically trigger the download of the CSV file by
calling the downloadData method on the MapView instance reference.
Add Tooltip
The MapView component has an optional tooltip that displays additional data
point information when hovering over data points from any of the data layers. To
enable the tooltip a Tooltip subcomponent should be used inside the data layer
component (e.g. DotLayer.Tooltip, BubbleLayer.Tooltip, etc.). When a
Tooltip subcomponent is provided without any children, the default tooltip
will be used. Every data layer has its own default tooltip due to data shape
difference.
Customize Tooltip
Tooltip sections
It's possible to customize the tooltip by providing a custom template that can
consist of tooltip sections, items, and atoms. The Tooltip comprises three
main sections: Tooltip.Header, Tooltip.Body, and Tooltip.Footer. Each
section can contain different subsections, items, and atoms.
The Tooltip.Header serves as the topmost part of the tooltip and it always
contains a divider at its bottom. It is also possible to set an optional
Tooltip.Subheader within a Tooltip.Header to add additional information that
is rendered in a new block.
The Tooltip.Body is the central and interactive part of the tooltip. The
Tooltip.Body content is virtualized by default to improve performance, and it
can be disabled by setting the virtualization prop to false.
In order to have a proper virtualization, the itemHeight prop, which is the
height of every Tooltip.Item subcomponent within the Tooltip.Body, is
needed.
The Tooltip.Footer subcomponent always includes a divider at the top. This
section can be used to display the total number of items available or any other
contextual information.
Items
Tooltip.Items are independent components that can be placed in the header,
body, or footer sections. Each of these items serve a specific purpose and acts
as a flexbox. It is recommended nesting Tooltip.Symbol, Tooltip.Content, and
Tooltip.Value within the Tooltip.Item so that the space will be distributed
evenly.
The tooltip template can nest any custom HTML and styles can be overridden.
Tooltip Atoms
Multiple Tooltip.Item components can be combined in various ways, and the
space distribution is flexible, allowing their arrangement according to
preferences.
Chart states
Loading
The MapView component is able to show the default loading indicator setting
the loading prop to true.
Error
The <ErrorState /> subcomponent can be used to customise the error message
that will be displayed when an error occurs in the MapView component.