arenarium/maps Introduction
@arenarium/maps is a high performance
TypeScript library designed for applications that need to display thousands of complex markers without cluttering the map. Its purpose is to provide the logic
to simplify visualizing and searching map related information.
Installation
There are several ways to install the library:
- Using the loader package. It is the recommended way to load the library as it provides the latest patch version witch includes all the bug fixes and performance improvements. It uses the jsdelivr CDN under the hood.
- Using the main package. It installs a specific version of the library from NPM.
- Using a module script tag. It loads the latest or a specific version of the library as an ESM module from the jsdelivr CDN.
Select the installation method and continue with the installation:
To install the arenarium/maps library for MapLibre using npm, run the following command in your project directory:
Setup
Import the library loader in order to load the main library
MapManager:To initialize the library, first add a container element to your HTML where the map will be rendered.
Next, use the
MaplibreProvider class which requires a maplibregl.Map class, a maplibregl.Marker class and a maplibregl.MapOptions object. Use the MaplibreProvider instance, along with the token key, to initialize the
map manager.Map features like rotation or tilting are disabled in order for the plugin to work correctly.
You can change the map's visual appearance by setting a predefined dark or light theme:
Alternatively, you can apply a custom map style by providing a URL to a JSON file that adheres to the MapLibre Style Specification. You can also
override specific color properties within a custom style.
Markers
A marker consist of a pin, a tooltip and an optional popup:
- The pin is an element that should convey the marker's location and and basic information like an icon or a color.
- The tooltip is an element that should provide additional information thats needs to be readable, it could be small or large amount of information depending on the application.
- The popup is an element that is displayed when the user clicks on the marker. It should contain additional information thats not necessary or too large for a tooltip.
The markers toogle between the pin and the tooltip elements as the user zoom in. The pin is displayed when there is no room for the tooltip.
When the user zooms in and more space is available, more tooltips are displayed. Which tooltips are displayed first is determined primarily by
the ranking of the markers. The higher the rank, the sooner the tooltip is displayed.
To add markers to the map, you first need to define an array of
MapMarkerData objects. Provide the base marker data and the configuration
for the tooltip, pin and popup. The configurations have body callbacks which should return a HTMLElement.Use the
updateMarkers method on the map manager to update the map with new markers. If some of the provided markers already exist
on the map with the same id, it will be assumed that the data is the same (width, height, body...). This approach is designed for continuous updates
of map markers.When updating the markers, you can let the library try to automatically measure the sizes of the provided elemets, or you use the
dimensions property to manually set the sizes. Using it will also slightly improve loading performance when using a large number
of complex elements.The tooltip and popup body dimensions must abide by the following rules:
- The width, height and radius of the body must be greater than zero.
- The padding must be less than a fourth of the minimum of the width or height of the body.
The following are body callback functions for the current demo. Use them to return the
HTMLElement object for the tooltip, pin
and popup. You can create them manually or by using a specific frontend library such as React, Vue, Svelte, or any other library that supports creating
and manipulating DOM elements.To remove all markers from the map, use the
removeMarkers method:To manually toggle the popup of a marker, use the
showPopup and hidePopup methods:Configuration
MapConfiguration allows you to customize various aspects of the map and marker behavior when initializing the MapManager. You can control settings such as pin fading, popup panning, event handlers and more.To use, simply pass your configuration object when creating the map:
Refer to the
MapConfiguration schema for all available options and further customize your map experience.Usage
Usage is proportional to the number of marker updates. Every time you update map markers, some computation is required to calculate the optimal position
of the markers. The compute is provided by an API endpoint which is used by the library internally.
In case of a very large number of markers, the library will perform the computation in batches from the markers with the highest priority to the lowest
priority. The usage will therefore be potentially less than the total number of markers added to the map.
Usage does not increase on cache hits. For example if you use the same markers on your map multiple times, subsequent compute requests will hit the
cache and the usage is not increased. The cache is invalidated after a certain time.