A library of convenience methods for MapLibre GL. Greatly simplifies working with layers at runtime.

- Specify all layer properties (source, filter, paint, layout, minzoom, etc) and mouse events in a single shallow object. No
- Add layers without source data, or regard for asynchronous load events

const map = new ExpressML(library)
    .Map(options);

Instantiates a new map object.

library: a MapLibre or MapboxGL library class options: map options object, equivalent to the one consumed by maplibregl.Map

Returns an instance of ExpressMLMap, with all the features of maplibregl.Map plus the following.

Add layer of the corresponding type, on map load (if not already loaded).

layerType: one of Circle, Line, Fill, Text, Icon, Background. Text and Icon are actually symbol layers, but handy when needing just one or the other. To add symbol layers with both text and icons, use the vanilla map.addLayer() method.

id: string. name of layer

options (optional): a shallow object of all layer properties (except id). All parameters optional.

Sources: one of the following. If none, uses an empty geojson source by default. source: string. reference to an existing layer, much like the vanilla implementation of layer.source geojson: string or object (geojson). GeoJSON source by url string, or literal geojson object. vector + source-layer: string. vector tile source, plus source layer.

most other params of map.addLayer() can be added similarly, without nesting into source/layout/paint sub-objects.

For example, these two operations are equivalent:

map.on('load', () => {
    map.addLayer({
        id: 'name', 
        type: 'symbol',
        minzoom: 12,
        source: {
            type: 'geojson',
            data: 'https://www.example.com/data.geojson'
        }, 
        layout: {
            'text-field': 'label', 
            'symbol-placement': 'line'
        }
        paint: {
            'text-color': 'blue'
        }
    })
    .on('click', 'name', e => console.log(e.features[0]))
})

// no load event necessary
map.addText(                                                
    'name', 
    {
        geojson: 'https://www.example.com/data.geojson',    // put geojson source directly in object
        field: 'label',                                     // infers the "text-" prefix automatically, from layer type
        placement: 'line',                                  // ...while also handling obligatory "symbol-" prefixes
        minzoom: 12,                                        // accepts root-level layer properties
        color: 'blue'                                       // paint properties too 
        onClick: ft => console.log(ft)                      // plus mouse events
    }
)

see example.html for more usage examples.

Mouse events: Events on layers can also be added to the options object.

on{Click|Mouseover|Mouseout|Mouseenter|MouseLeave|Mouseup|Mousemove|Dblclick|Contextmenu}(fn(firstFeature, event))

Add a mouse event handler to the layer. The callback function receives two arguments: the first feature returned, and the mouse event object. To illustrate, these are equivalent

    {
        ...,
        onClick: (firstElement, event) => {console.log(firstElement, event)}
    }

    map.on('click', {layerName}, e=>{
        console.log(e.features[0], e)
    }), 

Remove a layer. id: string. ID of layer to remove

Shorthand for map.getSource(id).setData(data). GeoJSON sources only.