L.Highlight

Leaflet plugin for creating highlight area for specified street/place using Nominatim. This plugin adds onto Leaflet.Layer which makes highlighting places like streets, cities etc. a lot easier. It also handles the Nominatim paging of results.

Requirements

Leaflet is required before adding L.Highlight. L.Highlight was tested on Leaflet v2.0.0-alpha.1

Basic Usage:

Clone the L.Highlight repository by doing:

git clone [email protected]:mmaciejkowalski/L.Highlight.git

In HTML, import the required Leaflet Javascript and CSS files.

<link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/leaflet.css" />
<script src="https://unpkg.com/[email protected]/dist/leaflet.js"></script>

In HTML, import the L.Highlight

<script src="leaflet-highlight.min.js"></script>

In Javascript, initialize your Leaflet Map

var map = L.map('map', {editable: true});
L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png').addTo(map);

In Javascript, add a layer with user or predefined input

// search for Politechniki Avenue around Łódź, Poland
new L.Layer.Highlight().do({q: 'Piotrkowska, Łódź'}).addTo(map);

You can also redefine your search for specific street in specific city, in case Nominatim would find another streets with this name in nearby cities.

// search for Politechniki Street exactly in Łódź, Poland
new L.Layer.Highlight().do({street: 'Piotrkowska', city: 'Łódź'}).addTo(map);

You can also do some more refined things.

// search for areas of Łódź University of Technology (Politechnika) in Łódź, Poland, color them red and attach click event handler alerting name of clicked area
new L.Layer.Highlight({email: '[email protected]'}).do({
    q: 'Politechnika, Łódź',
    filter: 'Polygon', 
}, {
    style: function() {return {color: '#f00'}},
    eventHandlers: {
        click: function(area) { 
            alert(area.sourceTarget.feature.properties.display_name)
        }
    }
}).addTo(map);

Removing layers is also a possibility, just use

// search for areas of Łódź University of Technology (Politechnika) in Łódź, Poland, color them red and attach click event handler alerting name of clicked area
<layer>.removeFrom(<map>);

It is nice for using email while calling Nominatim, so be sure to include your email in L.Highlight initialisation.

new L.Layer.Highlight({email: [email protected]}).do({street: 'Piotrkowska', city: 'Łódź'}).addTo(map);

for styling, filtering, areas and more read API Documentation below or visit demo

API Documentation:

Init options

L.Layer.Highlight accepts an initialisation object

{
    email: string, // as stated above, it is nice for using email while calling Nominatim
    nominatimAPI: string, // or you can provide your own Nominatim API - if not, default 'https://nominatim.openstreetmap.org' will be used
    maxRetries: number // max number of retries for Nominatim API calls
}

Methods

L.Layer.Highlight extends L.Layer, so it allows to use all the L.Layer methods except it will show nothing unless you deliberatly invoke the do(searchOpts, otherOpts) before addTo().

The do(searchOpts, otherOpts) method accepts two parameters:

1. search options

{
    q: string, // use this OR city & street
    city: string, // use this OR q
    street: string, // use this OR q
    limit: number, // limit number of results from Nominatim
    filter: string // limit search results for Features of this type
}

where q is a basic search query, city and street used at the same time are for advanced street search. Do not use all three at the same time. Also, filter is a GeoJSON Feature name like Polygon or LineString.

2. other options (what a fancy name!)

{
    style: Object,
    eventHandlers: {
        eventName1: function1,
        eventName2: function2,
        eventName3: function3,
        ...
    }
}

Where style is the same as in L.geoJSON and eventHandlers is an object with event names as keys and event handlers as values. These event handlers are then translated to .on(<String> type, <Function> fn) method, so:

{
    eventHandlers: {
        'click': function(clickTarget) { doSomething(clickTarget); }
    }
}

will be translated inside L.Highlight to:

.on('click', function(clickTarget) { doSomething(clickTarget); })

Probably in later releases the implementation of method on() will be implemented