open-map-gl v1.0.0

Open Map GL

This library is a wrapper for the maplibre GL one and help you use the javascript GL as react components. The benefits of this library is that you can use any open GL map (i.e. the ones created with TileServer-GL or MapTiler-GL) that generates the style.json and the tileserver.

For further details about MapLibre look at the following links:

• MapTiler, React, MapLibre integration
• MapLibre API docs

Important Note

Please keep in account that at the moment the package is under development/testing so some features might not be available.

Before you start

Please consider that in order to use mapLibre GL under the hood on your application, you need to copy and paste the following script tag below in the head tag of your index.html:

<link href='https://unpkg.com/maplibre-gl@1.15.2/dist/maplibre-gl.css' rel='stylesheet' />

Table of contents

• Components Overview
• Map
  • Map Properties
  • Map Usage
  • Map Methods
• Marker
  • Marker Properties
  • Marker Usage
• Popup
  • Popup Properties
  • Popup Usage
• Source
  • Geojson Properties
• Layer
  • Symbol
  • Line
  • Circle
• Utilities

Components Overview

The library currently supports the following components:

• Map, that is the map Container and holds all the objects that can be used as a children
• Marker, that let you show one or more markers on the map
• Popup, that can be opened (or closed) on the map
• Source, that let you load any type of source. Even though all the sources provided by maplibre are potentially available only the geojson one has currently been tested.
• Layer, that shows graphically the data present in a source, i.e. a geojson source. Even though all the layers provided by maplibre are potentially available, only the point and line have currently been tested.

Map

Map Properties

Below the properties that can be used with the Map Component:

Map Usage

In this section we are going to illustrate the methods that can be called by the map. In order to use any of these map events, it's important to use the ref property above to point the map with a React ref variable (useRef hook):

import React, { useRef } from 'react';
import { Map } from 'open-map-gl';

const App = () => {
    const _map = useRef();

    return <Map 
        ref={_map} 
        style="..." //enter your style json here
        accessToken="..." //use the access token only if your backend will require it: please remember that at the moment solution will manage only get requests
        mapCssStyle={{
            position: 'absolute',
            width: '100%',
            height: '100%',
        }}
        mapContainerCssStyle={{
            position: 'relative',
            width: '100%',
            height: 'calc(100vh - 77px)'
        }}
    />
}

Map Methods

Map Methods are important in order to make actions from the map within the application code. In order to call map function it's required to provide a map with a reference (see the example above on how to use a ref hook). An example of how to use them:

import React, {useEffect} from 'react';
...
//after the renderization this is a demo to see how the camera flies to after two seconds of the map renderization
useEffect(() => {
    setTimeout(() => {
        _map.current.flyTo({center: [0,0], zoom: 9});
    }, 2000)
}, []);

Available methods:

• flyTo(option, eventData?)
• fitBounds(bounds, options?, eventData?)
• fitScreenToCoordinates(p0, p1, bearing, options?, eventData?)
• getBearing()
• getBounds()
• getCanvas()
• getCanvasContainer()
• getCenter()
• getContainer()
• getFilter(layerId)
• getLayer(id)
• getLayoutProperty(layerId, name)
• getLight()
• getMaxBounds()
• getMaxPitch()
• getMaxZoom()
• getMinPitch()
• getMinZoom()
• getPadding()
• getPaintProperty(layerId, name)
• getPitch()
• getPixelRatio()
• getRenderWorldCopies()
• getSource(id)
• getStyle()
• getZoom()
• hasControl(control)
• hasImage(id)
• isMoving()
• isRotating()
• isSourceLoaded(id)
• isStyleLoaded()
• isZooming()
• jumpTo(options, eventData?)
• listImages()
• loaded()
• moveLayer(id, beforeId?)
• panBy(offset, options?, eventData?)
• panTo(lngLat, options? eventData?)
• project(lngLat)
• queryRenderedFeatures(geometry?, options?)
• querySourceFeatures(sourceId, parameters?)
• redraw()
• resetNorth(options?, eventData?)
• resetNorthPitch(options?, eventData?)
• resize(eventData?)
• rotateTo(bearing, options?, eventData?)
• setBearing(bearing, eventData?)
• setCenter(center, eventData?)
• setFeatureState(feature, state)
• setFilter(layerId, filter, options={})
• setLayerZoomRange(layerId, minzoom, maxzoom)
• setLayoutProperty(layerId, name, value, options={})
• setLight(light, options={})
• setMaxBounds(bounds)
• setMaxPitch(maxPitch)
• setMaZoom(maxZoom)
• setMinPitch(minPitch)
• setMinZoom(minZoom)
• setPadding(padding, eventData?)
• setPaintProperty(layerId, name, value, options={})
• setPitch(pitch, eventData?)
• setPixelRatio(pixelRatio)
• setStyle(style, options?)
• setZoom(zoom, eventData?)
• zoomIn(options?, eventData)
• zoomOut(options?, eventData)
• zoomTo(zoom, options?, eventData)

Marker Component

The marker is the pin that can be available on the map. You can use the marker when you don't have so many points to render, otherwice is better to go to the Symbol Layersolution.

Marker Properties

Below the properties that can be used with the Marker Component:

Marker Usage

The basic usage of the marker will also show the marker creation with the add on of the popup:

import React from 'react';
import { Map, Marker, createPopup, Popup } from 'open-map-gl';

const App = () => {

    const popup = createPopup({
        coords: [7, 45],
        options: {
            offset: 25
        },
        text: "This is an example of popup"
    })

    return <React.Fragment>
        <Map
            style="..." //enter your style json here
            accessToken="..." //use the access token only if your backend will require it: please remember that at the moment solution will manage only get requests
            mapCssStyle={{
                position: 'absolute',
                width: '100%',
                height: '100%',
            }}
            mapContainerCssStyle={{
                position: 'relative',
                width: '100%',
                height: 'calc(100vh - 77px)'
            }}
        >
            <Marker
                coords={[7, 45]}
                popup={popup}
                onDragEnd={evt => console.log(evt.target)}
            />
        </Map>
    </React.Fragment>
}

export default App;

Popup

Popup Properties

Below the properties that can be used with the Popup Component:

Popup Usage

A basic example to show a popup direcly visible on the map once the app start:

import React from 'react';
import { Map, Marker, createPopup, Popup } from 'open-map-gl';

const App = () => {

    return <React.Fragment>
        <Map
            style="..." //enter your style json here
            accessToken="..." //use the access token only if your backend will require it: please remember that at the moment solution will manage only get requests
            mapCssStyle={{
                position: 'absolute',
                width: '100%',
                height: '100%',
            }}
            mapContainerCssStyle={{
                position: 'relative',
                width: '100%',
                height: 'calc(100vh - 77px)'
            }}
        >
            <Popup 
                coords={[7, 45]}
                options={{
                    maxWidth: 100,
                    offset: 50
                }}
                text="This is another example"
            />
        </Map>
    </React.Fragment>
}

export default App;

Source

A source can be used in order to load on the map data, image, videos or canvas. Note that, even though the usage of other things out of data might work, those features haven't been tested yet and the only tested one is the geojson type.

Geojson Properties

Below are stated all the properties that can be used once invoking a Source component of geojson. The default properties that can be applied to the geojson are available in the maplibre official doc. An additional property that is needed for the geojson is the id that is used in order to uniquely identify a source: it's important to remember to add this field once a Source component is declared and if you have more than one source in the code to create different id, otherwise it will be rendered only the first one (in order to see the second with the same name you should unmount the previous source first). Since a source does not show anything without layers the usage example will be done on the layer section.

Layer

The layer is one or more graphical representation of the source data. There are several layers that can be used and more than one layer can be used in order to differently show cluster of data in the source itself. There are several properties that belongs to each layer, independently from the type:

• id, it represents the unique layer ID (the concept about unique ID for each layer is the same as per the source).
• beforeId, if one or more layer overlaps, it can be useful to render a specific layer before another one, in order to manually decide which come upon and below (generally speaking React will render from top to bottom so if you don't set this property than the last written will be upon).
• source, it states the name of source where the layer belongs to.
• type, it selects the graphical type of the layer, that can be symbol, line, circle, fill.
• inspectClusterOnClick, a boolean value that let the user to click and drill down a cluster to every single point. This feature can be used only if the cluster function has been enabled in the Source component.

Let's have a look at all the specific properties of each layer type available.

Symbol

This is the layer that is applied to points or line space application (if we want to show symbols on the line to be applied regularly at a specified distance) and shows on the map small images or icons. A symbol can be retried from backend info if those are available at backend side or can be created directly on the frontend by using the useImageIcon hook coming together with this library.

Further details on the property that can be used are available at the maplibre official doc. A usage example of the symbol appliacation

import React, {useRef} from 'react';
import { Map, Source, Layer, useImageIcon } from 'open-map-gl';

const DUMMY_POINTS = {...} //a geojson object: it might be a single feature or a feature collection

const App = () => 

    const _map = useRef();
    useImageIcon(_map, 'test-icon', 'https://maplibre.org/maplibre-gl-js-docs/assets/osgeo-logo.png'); //the utils that let's you load images directly from frontend

    return <Map
        ref={_map}
        //...map properties...//
        >
        <Source
            id="source-test"
            type="geojson"
            data={DUMMY_POINTS}
        >
            <Layer 
                id="symbol-to-test"
                type="symbol"
                source="source-test"
                layout={{
                    'icon-image': 'test-icon',
                    'icon-size': 1.5
                }}    
            />
        </Source>
    </Map>
}

export default App;

Circle

This is another representation of the points that provider a circle with color, radius, and other properties. An interesting usage can be done for the cluster data, once enabling the feature of the cluster from the source. In this case, we will see at certain zoom an aggregation of data with the count of point belonging to each cluster.

Further details on the property that can be used are available at the maplibre official doc.

A usage example of the circle:

import React, {useState} from 'react';
import { Map, Source, Layer } from 'open-map-gl';

const App = () => {

    const [data, setData] = useState(null);

    useEffect(() => {
        fetch('...') //the link where you have data on DB
            .then(response => response.json())
            .then(newData => setData(newData[0]))
            .catch(err => console.error('Error on fetch', err.message));
    }, []);

    return <Map
        //...map properties...//
    >
        <Source
            id="source-test"
            type="geojson"
            data={data}
        >
            <Layer
                id='layer-circle'
                type='circle'
                source='source-test'
                filter={['!=', 'isSelected', true]}
                paint={{
                    'circle-radius': 10,
                    'circle-color': '#B42222'
                }}
            />
            <Layer
                id='layer-circle-2'
                type='circle'
                source='source-test'
                filter={['==', 'isSelected', true]}
                paint={{
                    'circle-radius': 10,
                    'circle-color': '#B4FFFF'
                }}
            />
        </Source>
    </Map>
}

export default App;

Line

The line layer is used once we have linestring to show in the geojson object.

Further details on the line properties are available at the maplibre official doc.

An usage example of the line:

import React from 'react';
import { Map, Source, Layer } from 'open-map-gl';

const DUMMY_LINES = { /*... your base here...*/ };

const App = () => {

    return <Map
       //...map properties...//
    >
        <Source
            id="source-test"
            type="geojson"
            data={DUMMY_LINES}
        >
            <Layer
                id="symbol"
                type="line"
                source="source-test"
                layout={{
                    'line-join': 'round',
                    'line-cap': 'round'
                }}
                paint={{
                    'line-color': '#C33A1D',
                    'line-width': 3
                }}
            />
        </Source>
    </Map>

}

export default App;

Utilities

This section provides helpful function or hook function to be used in order to facilitate the usage of the whole library.

useImageIcon

This is a hook function that help you create a symbol icon on frontend directly. It might be useful once backend Sprite are not configured yet or you just have to use one single image (for multiple image usage is of course faster have the image on backend side). This hook accept the following parameters:

• map, it's the ref object of the map itself. In order to use this function, it's important to create a reference of the map
• imageName, the name we will call in the layer properties the symbol
• imageUrl, the Url where the image is available. This can be a URL or a React loaded png image on the project itself

In order to see how to use it please see the example in the Symbol section.