/laji-map

Map library with geoJSON/WKT/ISO 6709 view/edit support with specialization in finnish coordinate systems

Primary LanguageTypeScriptMIT LicenseMIT

README

LajiMap is a configurable map component built on Leaflet. The main focus is on rendering geoJSON features and drawing & editing geoJSON features. It has built-in support for EPSG:3857 and EPSG:3067 projections.

Installing

npm install @luomus/laji-map --save

Usage

var LajiMap = require("laji-map");
var map = new LajiMap(options);

Options

You can also pass any options that Leaflet accepts when initializing LajiMap. Setting Leaflet options after initialization doesn't work.

Option Type Default Description
rootElem HTML elem - The node where to mount.
lang String "en" One of "en", "fi", "sv".
data Data options[] - Data to draw on map.
draw Draw options - Options for data that can be controlled with the draw control buttons.
controls Control options - An option object that defines which control should be shown.
customControls Custom controls options[] - An array of custom controls. See custom control options.
tileLayerName String "taustakartta" The default tile layer name. Possible values listed under section "Tile layer options". Overridden by tileLayers.
overlayNames String[] - The default overlay layers. Possible values listed under section "Tile layer options". Overridden by tileLayers
tileLayers TileLayers options - Options for the tile layers, which allows multiple active layers. Overrides tileLayerName.
center LatLng [65, 26] The coordinates for the initial center of the map.
zoom Int 2 The initial zoom level for the map.
zoomToData FitBounds options false Zooms the map to given data & draw data. Additional options are: {paddingInMeters: number, minZoom: number, dataIdxs: number[], draw: boolean}.
locate Object false Show user location on map. Options: {on: boolean, onLocationFound: fn(latlng, radius), onLocationError: fn(event), userLocation: {latlng, accuracy}, panOnFound: boolean (true by default)}
onPopupClose() Function - Function to call when a popup is closed
markerPopupOffset Int 40 Offset (towards up) for popups for markers.
featurePopupOffset Int 5 Offset (towards up) for popups for features other than markers.
popupOnHover Boolean false Controls whether the popups are shown on hovering a feature or by clicking a feature.
onInitializeDrawLayer Function - A callback function that is triggered after the draw layer is initialized.
lineTransect Linetransect options - Options for a line transect layer.
availableTileLayerNamesWhitelist String[] - List of tile layer names to show in the layer control. See the possible values of tileLayerName option.
availableTileLayerNamesBlacklist String[] - List of tile layer names not to show in the layer control. See the possible values of tileLayerName option.
availableOverlayNamesWhitelist String[] - List of overlay names to show in the layer control. See the possible values of overlayNames option.
availableOverlayNamesBlacklist String[] ["kiinteistojaotus", "kiinteistotunnukset", "flyingSquirrelPredictionModel", "barentsRegion"] List of overlay names not to show in the layer control. See the possible values of overlayNames option.
tileLayerOpacity Float - Tile layer opacity. Range: 0.0-1.0
on Object - Leaflet events to listen for. Must be an object with event names as keys and value as callbacks. You can also use setEventListeners().
polygon Object - Polygon options: {allowIntersection: Boolean, Path style options}
polyline Object - Polyline options: {showStart: Boolean (displays a dot at the start of the line. Default: false). showDirection: Boolean (displays arrows to show the direction. Default: true), Path style options}.
rectangle Object - Global path style options.
circle Object - Global Path style options.
marker Object - Global Path style options.
bodyAsDialogRoot Boolean true If true, body will be used as root DOM node for dialogs & blocker element. Otherwise the map container will be used as the root DOM node for dialogs.
clickBeforeZoomAndPan Boolean false Block wheel and touchstart events before map is clicked/touched.
viewLocked Boolean false Prevent all view interaction (panning, zooming).
googleApikey String - Needed for geocoding control.
lajiGeoServerAddress String "https://geoserver.laji.fi" Override the laji.fi geoserver address

Data options

Option Type Default Description
featureCollection GeoJSON featureCollection Empty feature collection The feature collection to render.
getPopup({dataIdx, featureIdx, feature, item}, callback) Function - Function that returns a popup string, or calls the callback with the popup string.
getTooltip({dataIdx, featureIdx, feature, item}, callback) Function - Function that returns a tooltip string, or calls the callback with the tooltip string.
getFeatureStyle({dataIdx, featureIdx, feature, item, hovered, editable, active}) Function See lajiMap._getDefaultDataStyle() A function that returns a Path style to use for the feature described by the input parameters.
cluster Boolean false Controls whether the features should cluster.
getClusterStyle({count, featureIdxs, cluster)) Function See lajiMap._getClusterIcon() A function that returns a Path style to use for feature clusters. The returned path style extends the default style. the count parameter is the number of features in the cluster. featureIdxs is an array of featureIdxs of the cluster and cluster is the Leaflet cluster object.
getClusterClassName({count, featureIdxs, cluster)) Function - A function that returns a class name to use for feature clusters. The count parameter is the number of features in the cluster. featureIdxs is an array of featureIdxs of the cluster and cluster is the Leaflet cluster object.
getDraftStyle Function true A function that returns a Path style to use for the feature during drawing & editing a feature.
on Object - An object containing event name -> event handler pairs. Supports both basic Leaflet layer events and cluster container events. Event handler arguments look like this: (e, {idx, layer, feature}). Example: {click: function(e, {idx, layer, feature}) { //handle event }}
editable Boolean true Controls whether the data is editable.
hasActive Boolean - Whether features can be activated.
activeIdx Integer - The initial active idx. If not given, the data doesn't allow activating any feature. If 'undefined', features can be activated but there is initially no active features.
marker Object - Marker options: {icon: (options: style options, feature: GeoJSON feature) => L.Icon (the icon should implement setStyle({color, opacity}) so laji-map can style it according to getfeatureStyle() etc., maxFillOpacity: number, controlFillOpacity }
polygon Object - Polygon options: {allowIntersection: Boolean, maxFillOpacity: Number, controlFillOpacity: Boolean}
polyline Object - Polyline options: {showStart: Boolean (displays a dot at the start of the line. Default: false). showDirection: Boolean (displays arrows to show the direction. Default: true), maxFillOpacity: Number, controlFillOpacity: Boolean}.
rectangle Boolean - Opacity is controlled by polygon opacity options
circle Object - Circle options: {maxFillOpacity: Number, controlFillOpacity: Boolean}.
onChange Function - A callback function that fires events for draw data changes. Receives an array of event objects.
highlightOnHover Boolean false Highlights layers on hover even if the item isn't editable or doesn't have an active idx.
single Boolean false Allows only a single feature on the data. Adding new feature removes all other features.
showMeasurements Boolean | {showOnHover: boolean} false Shows feature measurements.
opacity number (0 - 1) 1 Opacity of the data.
maxFillOpacity number (0 - 1) 0.4 Max fill opacity (for polygons & circles) that the layer control can adjust the opacity to. Overridable with layer type options (see options for data options marker, polygon etc).
visible Boolean true Whether the data is visible.
onOpacityChange Function - Callback for opacity change
onVisibleChange Function - Whether the data is visible.
label String - If provided, the data visibility/opacity will be controllable in the layer control.
controlFillOpacity Boolean - If provided, the data visibility/opacity controlling will control layer fillOpacity instead of opacity. Overridable with layer type options (see options for data options marker, polygon etc).

Draw options

Draw options extend data options with editable: true as default.

Option Type Default Description
rectangle Boolean true Controls whether the draw data can contain a rectangle. Adding new rectangles is prevented. Map controls are affected by this option.
polygon Boolean true Controls whether the draw data can contain a polygon. Adding new polygons is prevented. Map controls are affected by this option.
polyline Boolean true Controls whether the draw data can contain a polyline. Adding new polylines is prevented. Map controls are affected by this option.
circle Boolean true Controls whether the draw data can contain a circle. Adding new circles is prevented. Map controls are affected by this option.
marker Boolean true Controls whether the draw data can contain a marker. Adding new markers is prevented. Map controls are affected by this option.

Line transect options

Option Type Default Description
feature GeoJSON Feature - The GeoJSON feature to use as the data.
activeIdx Integer - The index of the active line transect segment.
onChange Function - A function that fires events for line transect changes. Receives an array of event objects.
getFeatureStyle({lineIdx, segmentIdx, style = <the default style object for this layer>, type = L.Polyline L.Polygon L.CircleMarker}) Function
getTooltip(lineIdx, callback) Function - Function that returns a popup string, or calls the callback with the popup string.
printMode Boolean False If true, line will be styled for printing.
editable Boolean True If false, line can't be edited.

Control options

If control options is true, it is interpreted as a control options object with all default options.

Option Type Default Description
draw Draw control options true Shows a map control for adding new features.
layer Boolean true Shows a tile/baselayer control.
zoom Boolean true Shows a zoom control.
scale Boolean true Shows a scale control as meters.
location Boolean true Shows a location control.
geocoding Boolean true Shows a geocoding control. You need to provide googleApiKey also to the map options.
coordinates Boolean false Shows a control that shows the mouse position's coordinates in various formats.
lineTransect Line transect options true Shows a control for editing a line transect. Only shown if main options lineTransectis set.
fullscreen Boolean false Shows a fullscreen control.

Draw control options

If draw control is true, it is interpreted as a draw control options object with all default options. If draw-option isn't set, the draw controls won't be shown.

Option Type Default Description
rectangle Boolean true Controls whether to show the rectangle drawing button. Shown only if main options draw.rectangle is true.
polygon Boolean true Controls whether to show the polygon drawing button Shown only if main options draw.polygon is true..
polyline Boolean true Controls whether to show the polyline drawing button. Shown only if main options draw.polyline is true.
circle Boolean true Controls whether to show the circle drawing button. Shown only if main options draw.circle is true.
marker Boolean true Controls whether to show the marker drawing button. Shown only if main options draw.marker is true.
coordinateInput Boolean true Shows a control for entering a new feature to the draw layer by coordinates.
copy Boolean false Shows a control for copying the draw data.
clear Boolean false Shows a control for clearing all draw data.
reverse Boolean false Shows a control for reversing polyline features.
delete Boolean false Shows a control for deleting features.
undo Boolean true Shows a control for undoing draw actions.
redo Boolean true Shows a control for redoing draw actions.

Line transect control options

If line transect control is true, it is interpreted as a line transect control options object with all default options.

Option Type Default Description
split Boolean true Controls whether to show the segment splitting button.
delete Boolean true Controls whether to show the segment deletion button

Custom control options

An array of custom control items. A control item is either a singular control, or a collection of control items (the control items in a collection must be singular control items).

Option Type Default Description
controls Control items[] - Sets this control item to a collection of contor items.
text String - Text to show in control button tooltip and in the context menu.
position String "topleft" The corner where the control is shown at.
fn Function - A callback function that is called upon control click.
stopFn Function - A callback function that is called upon control action cancel (an action cancel handler is created if stopFn is given). Useful for functions that start a continuous action that should be cancellable.
eventName String - A name for the event that is triggered on action stop.
iconCls String - A class that is added to the button icon.
onAdd Function - A callback that is called when the control is added to the map.
contextMenu Boolean true If true, control is added to the context menu.
group String - A pre-existing control group to add the group to. Will be displayed according to the groups rules.

Tile layer options

Tile layer options which combine tile layers and overlays into single options object. Allows multiple layers with different opacity.

Option Type Default Description
active "finnish" "world" "finnish"
layers Object - Signature: {[tile layer or overlay name]: boolean | {opacity: 0-1, visible: boolean}}

Possible layer names are:

maastokartta
taustakartta
ortokuva
laser
openStreetMap
googleSatellite
afeGrid
cgrsGrid
geobiologicalProvinces
geobiologicalProvincesBorders
municipalities
counties
ely
forestVegetationZones
mireVegetationZones
threatenedSpeciesEvaluationZones
biodiversityForestZones
habitat
ageOfTrees
ykjGrid
ykjGridLabels
kiinteistojaotus
kiinteistotunnukset
currentProtectedAreas
plannedProtectedAreas
flyingSquirrelPredictionModel
birdAtlasSocietyGridZones

Methods

TODO.

The methods that are supposed to be used as private methods, and could break LajiMap's internal state if used wrong, start with an underscore.

src/utils.js contains some utilities for geoJSON and coordinate conversion.

Events

LajiMap provides the following events in addition to the Leaflet events.

Option Data property in event
tileLayersChange tileLayers
tileLayerChange tileLayerName
tileLayerOpacityChange tileLayerOpacity
tileLayerOpacityChangeEnd tileLayerOpacity
overlaysChange overlayNames
lineTransect:split -
lineTransect:delete -
lineTransect:pointdrag -

Development

Install the dependencies with npm start.

Start the development playground with npm start.

To release a new version, run npm run publish-to-npm.

Try to keep the code style consistent - npm run lint should pass without errors.

In order to use the geocoding widget, you should provide the Google API key to properties.json. See properties.json.example.

The map options can be controlled with query parameters. In addition, testMode query param will start the map with the default options.

Tests

You might need to install playwright dependencies to run the tests:

npx playwright install

The playground server can be running or or not. If it's not running, it will be automatically started.

Run the tests:

npm test

If you run into issues with browser dependencies etc, there's also a dockerized runner:

# Run all tests (builds docker image & runs it)
npm run test:docker

# Or if you want to give playwright params, run certain tests etc:
npm run test:docker -- test/draw.spec.ts --project chromium

Test env variables

Parameters are given as envirnment variables, i.e. TEST_BROWSER=chrome npm test

Option Default Description
VERBOSE false Logs the playground URI's used by tests so you can get debug the test cases in playground easier.
DELAY - Makes all tests wait DELAY milliseconds ebetween the map being initialized and the test run.