# Map Data Source
<flow-map-data-source> A map data source specifies geospatial data to display on a map.
Data sources are referenced by Map Layers to visualize geospatial features specified by the data source.
# Types of Data Source
Data sources may specify map vector tiles or GeoJSON data. Set the type attribute of the Map Data Source component to specify the type.
The src attribute specifies the location of the geospatial data associated with a data source.
For vector data sources src may be:
- A Flo.w tile source ID.
- A URL to a 3rd-party map tile server returning a TileJSON (opens new window) specification.
For geojson data sources src may be:
- A Flo.w dataset ID.
- A literal GeoJSON FeatureCollection (opens new window).
- A reactive expression returning a GeoJSON FeatureCollection (opens new window).
- A URL to a 3rd-party API returning a GeoJSON FeatureCollection (opens new window).
# Map Feature Selection
The Map Data Source component supports automatic handling of feature selection by the user. Single-selection and multi-selection UI/UX models are provided that allow a user to select a map feature by clicking and extending the selection by toggling additional features.
WARNING
Feature selection functionality requires that you specify the feature-id attribute of the Map Data Source component so that features can be uniquely identified.
An exception will be thrown if you set any of the selection-* attributes discussed below without also setting the feature-id attribute.
# Selection Modes
Enable automatic selection and specify the selection mode with the selection-mode attribute.
| Mode | Behaviour |
|---|---|
none | Automatic selection is disabled (default). |
single | Clicking a feature will clear and reset the currently selected feature for the data source. |
multi | A simple click on a feature will clear the selection state and select the clicked feature. A Ctrl/Alt/Meta click will toggle the selection state of the clicked feature, adding or removing the feature from the selection. |
To style selected features use the @@selected feature state property in Map Layer style rules.
# Selection Clearing
Selection state is maintained independently for each Map Data Source that has selection enabled. By default, clicking an empty area of the map will clear all selections but clicking map features from one Map Data source will not affect selected features from another Map Datasource.
Specify selection-clear="true" to clear feature selections when the user clicks anywhere on the map: an empty area OR a feature from another Map Data Source.
# Binding Feature Selection to Application State
# selection-state
Specify selection-state to bind selected feature IDs to a Flo.w RDF reactive application state property. Binding is two-way: selecting features on the map will update the bound application state property and updating the state property will update the selection state on the map.
| Mode | Behaviour |
|---|---|
single | The bound app state property is the selected feature's ID. |
multi | The bound app state property is an array representing the selected features' IDs. |
# selection-feature-state
Specify selection-feature-state to bind selected feature properties to a Flo.w RDF reactive application state property. Binding is one-way: selecting features on the map will update the bound application state property but programmatically updating the state property has no effect. The bound state property is updated using feature data loaded by the map (either via vector tiles or GeoJSON) without making additional queries.
| Mode | Behaviour |
|---|---|
single | The bound app state property is an object containing the selected feature's properties. |
multi | The bound app state property is an object mapping feature IDs to feature property objects. |
selection-feature-state is designed to simplify displaying popups or other information panels without having to make an additional query for feature properties. If map features are reloaded for any reason (e.g. a timer change) then the bound application state property will be updated. This ensures the bound property is always in sync with displayed map features.
WARNING
If the map is panned away from a selected feature, Flo.w RDF may not be able to retrieve the map data associated with the feature. In this case, the bound state property will be set to undefined to avoid displaying stale data. This is not usually an issue as map popups are not displayed for features that are not visible in the current map viewport.
# Choosing whether to use selection-state or selection-feature-state
You can use one or both of these attributes on a single map data source. Each serves a different purpose:
| Attribute | Binding | Uses |
|---|---|---|
selection-state | two-way |
|
selection-feature-state | one-way | Getting selected feature properties for display in a map popup or information panel. |
# Displaying Map Feature Popups
Specify selection-popup on a Map Data Source to enable automatic display of a popup when a feature is clicked. The popup can be defined in two ways:
- A popup template - use the Map Popup component to define a static popup template.
- A dynamic popup - use a function to dynamically define a popup based on the clicked feature.
# Using Static Map Popup Templates
To use a static Map Popup with a Map Data Source, set the selection-popup attribute of the Map Data Source to the ID of the Map Popup. The popup will be automatically opened when a map feature is clicked.
# Using a Popup Function
To provide dynamic content for a popup, set the selectionPopup property of the Map Data Source to a Selection Popup Function that returns a popup definition.
The function that you provide is called by Flo.w RDF when a feature is clicked. The function receives the clicked feature as an argument and should return a FlowCoreMapPopupOptions object that informs Flo.w RDF what content to display in the popup and other configuration options. You may also return null from the popup definition function to prevent display of the popup.
Content can be provided as an HTML string or any dynamically-created HTML Node.
TIP
It is not possible to set an HTML attribute to a function within HTML. Setting the selectionPopup to a function must be done from JavaScript by first retrieving the Map Data Source as a DOM element and then setting the selectionPopup property of the element.
Dynamic popups are particularly useful when multiple selection is used because each popup needs to display information about a different feature. The feature ID can be retrieved from the argument passed into your popup definition function and used to craft specific HTML for the clicked feature.
# Examples
# Displaying Vector Map Tiles From a Flo.w Tile Source
The map below displays London Borough polygons using map tiles served from a Flo.w vector tile source.
# Displaying Data From a Flo.w Dataset
The map below displays air quality data points for London. The data is queried from a Flo.w dataset, which returns a GeoJSON FeatureCollection.
# Displaying a GeoJSON Feature Collection
The map below displays a GeoJSON feature collection that is programmatically generated. The map data source is set to a reactive property that receives the constructed feature collection.
This technique can be used to perform client-side geospatial analysis or transformations of other data sources such as the results of a Flo.w reactive query. Specify geospatial processing of the query results within a Flo.w RDF computed property and return the computed GeoJSON feature collection for display on the map.
# Styling Selection State
The map below displays features from two data sources: Air Quality and London Boroughs. selection-mode is specified to achieve the following behaviour:
- Air Quality: multiple features can be selected.
- London Boroughs: a single feature can be selected.
The feature state properties @@hover and @@selected are used in the map layer styles to achieve hover and selection effects.
# Binding Selected Feature IDs
The map below show the use of the selection-state attribute to bind selected feature IDs to application state properties. The bound properties are
also set when the 'Clear' button is clicked to programmatically clear the selection state.
# Binding Selected Feature Properties
The map below show the use of the selection-feature-state attribute to bind selected feature properties to application state properties. Computed properties
are registered to convert the selected feature properties for display in the footer of the map.
# Using Dynamic Popups for Multi-Selection
The map below show the use of a dynamic popup to show information for multiple selected features.