Deflates lines and polygons to a marker when their screen size becomes too small in lower zoom levels.
HTML JavaScript
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

Leaflet.Deflate

Build Status Greenkeeper

Substitutes polygons and lines with markers when their screen size falls below a defined threshold.

Example

(NOTE: The following refence reflects pre-release version 1.0-alpha.3. If you're looking to use the latest stable release, please refer to the maintenance/0.3 branch.)

Installation

Using a hosted version

Include the source into the head section of your document.

<script src="https://unpkg.com/Leaflet.Deflate@1.0.0-alpha.3/dist/L.Deflate.js"></script>

Install via NPM

If you use the npm package manager, you can fetch a local copy by running:

npm install Leaflet.Deflate@1.0.0-alpha.3

You will find a copy of the release files in node_modules/Leaflet.Deflate/dist.

API

L.Deflate

The central class of the Leaflet.Deflate. It is used to create a feature group that deflates all layers added to the group.

Usage example

Initialize a new L.Deflate feature group, add it too your map and add layers you want to deflate.

var map = L.map("map");
var features = L.deflate({minSize: 10})
features.addTo(map);

// add layers
var polygon = L.polygon([
    [51.509, -0.08],
    [51.503, -0.06],
    [51.51, -0.047]
])
.addTo(features);

// works with GeoJSONLayer too
L.geoJson(json).addTo(features);

Creation

Factory Description
L.deflate(<Object> options) Creates a new deflatable feature group, optionally given an options object.

Options

Option Type Default Description
minSize int 20 Defines the minimum width and height in pixels for a path to be displayed in its actual shape.
markerOptions object or function {} Optional. Customize the markers of deflated features using Leaflet marker options.
markerCluster boolean false Indicates whether markers should be clustered. Requires Leaflet.MarkerCluser.
markerClusterOptions object {} Optional. Customize the appearance and behaviour of clustered markers using Leaflet.markercluster options.

Examples

Basic

To create a basic deflatable layer, you have to

  1. Create an L.Deflate feature group and add it to your map.
  2. Add features to the L.Deflate feature group.
var map = L.map("map").setView([51.505, -0.09], 12);

var deflate_features = L.deflate({minSize: 20});
deflate_features.addTo(map);

var polygon = L.polygon([
    [51.509, -0.08],
    [51.503, -0.06],
    [51.51, -0.047]
]);
deflate_features.addLayer(polygon);

var polyline = L.polyline([
    [51.52, -0.05],
    [51.53, -0.10],
], {color: 'red'});
deflate_features.addLayer(polyline);

GeoJSON

Also works with GeoJSON layers.

var map = L.map("map").setView([51.505, -0.09], 12);

var deflate_features = L.deflate({minSize: 20});
deflate_features.addTo(map);

var json = {
    "type": "FeatureCollection",
    "features": [{}]
}

L.geoJson(json, {style: {color: '#0000FF'}}).addTo(features);

Custom markers

You can change the appearance of markers representing deflated features either by providing a marker options object of a function that returns a marker options object. Usually providing a marker options objects is sufficient for most use cases, you would typically choose to provide a function if you want to base to marker appearance on the feature's properties.

Provide the object or function to the markerOption property when initializing L.deflate.

Define custom markers using a marker options object

var map = L.map("map").setView([51.550406, -0.140765], 16);

var myIcon = L.icon({
  iconUrl: 'img/marker.png',
  iconSize: [24, 24]
});

var features = L.deflate({minSize: 20, markerOptions: {icon: myIcon}});
features.addTo(map);

Define custom markers using a function

var map = L.map("map").setView([51.550406, -0.140765], 16);

function options(f) {
    // Use custom marker only for buildings
    if (f.feature.properties.type === 'building') {
        return {
            icon: L.icon({
                iconUrl: 'img/marker.png',
                iconSize: [24, 24]
            })
        }
    }

    return {};
}

var features = L.deflate({minSize: 20, markerOptions: options});
features.addTo(map);

Cluster Markers

With a little help from Leaflet.Markercluster you can cluster markers. Add the Leaflet.Markercluster libraries to the head section of your document as described in the docs. Then enable clustering by adding markerCluster: true to the options when initializing L.deflate.

var map = L.map("map").setView([51.505, -0.09], 12);

var deflate_features = L.deflate({minSize: 20, markerCluster: true});
deflate_features.addTo(map);

var polygon = L.polygon([
    [51.509, -0.08],
    [51.503, -0.06],
    [51.51, -0.047]
]);
deflate_features.addLayer(polygon);

var polyline = L.polyline([
    [51.52, -0.05],
    [51.53, -0.10],
], {color: 'red'});
deflate_features.addLayer(polyline);

Developing

You'll need to install the dev dependencies to test and write the distribution file.

npm install

To run tests:

gulp test

To write a minified JS into dist:

gulp dist

Authors

License

Apache 2.0