Issue #2942651 by jwilson3, itamair, hswong3i: Manage Leaflet library...

## Leaflet

# Leaflet

###General Information

**Leaflet** module provides integration with

[Leaflet map scripting library](http://leafletjs.com).

**Leaflet** module provides integration with [Leaflet map scripting

library](http://leafletjs.com).

It is based and dependant from:

  - the [Leaflet JS library](http://leafletjs.com);

  - the [Geofield](https://www.drupal.org/project/geofield) Module;

###Installation and Use

- Require/Download the Leaflet module

[using Composer to manage Drupal site dependencies](https://www.drupal.org/docs/develop/using-composer/using-composer-to-manage-drupal-site-dependencies)__,

which will also download the required

[Geofield Module](https://www.drupal.org/project/geofield)

dependency and GeoPHP library.

It is done simply running the following command from your project package root

(where the main composer.json file is sited):

    `composer require drupal/leaflet`

- Enable the **Leaflet** module to be able to use:

    - the configurable **Leaflet Map** as Geofield Widget, with [Leaflet Geoman js library](https://geoman.io/leaflet-geoman);

    - the configurable **Leaflet Map** as Geofield Formatter;

- Enable **Leaflet Views** (leaflet_views) submodule for **Leaflet Map Views

integration**

You need to add at least one geofield to the Fields list, and select the Leaflet

Map style in the Display Format.

In the settings of the style, select the geofield as the Data Source and select

a field for Title and Description (which will be rendered in the popup).

- Enable **Leaflet Markercluster** (leaflet_markercluster) submodule for

[__Leaflet Markercluster Js library__](https://github.com/Leaflet/Leaflet.markercluster) functionalities and configurations, both

in the Leaflet Formatter and in the Leaflet Map View display.

- Add, enable and configure ["Geoocoder" module](https://www.drupal.org/project/geocoder) to enable Geocoder Control

 (with Autocomplete) for quick Leaflet Map Address search & pan/zoom.

As a more powerful alternative, you can use node view modes to be rendered in

the popup. In the Description field, select "<entire node>" and then select a

View mode.

###API Usage

## Installation

### Download the Drupal Leaflet Module

[Using Composer to manage Drupal site

dependencies](https://www.drupal.org/docs/develop/using-composer/using-composer-to-manage-drupal-site-dependencies),

which will also download the required [Geofield

Module](https://www.drupal.org/project/geofield) dependency and GeoPHP

library. It is done simply running the following command from your

project package root (where the main composer.json file is sited):

    composer require drupal/leaflet

### Download Required JS Libraries

To download the required JS libraries with composer, you will need to

update your `composer.json` as below:

    {

        "extra": {

            "installer-paths": {

                "libraries/{$name}": [

                    "type:bower-asset",

                    "type:drupal-library",

                    "type:npm-asset"

                ]

            },

            "installer-types": [

                "bower-asset",

                "npm-asset"

            ]

        },

        "repositories": {

            "asset": {

                "type": "composer",

                "url": "https://asset-packagist.org"

            },

            "drupal": {

                "type": "composer",

                "url": "https://packages.drupal.org/8"

            }

        },

        "require": {

            "drupal/leaflet": "2.1.x-dev",

            "npm-asset/drustack--leaflet.resetview": "~1.0",

            "npm-asset/drustack--leaflet.syncview": "~1.0",

            "npm-asset/geoman-io--leaflet-geoman-free": "~2.11",

            "npm-asset/leaflet": "~1.7",

            "npm-asset/leaflet-fullscreen": "~1.0",

            "npm-asset/leaflet-gesture-handling": "~1.2",

            "npm-asset/leaflet.locatecontrol": "~0.76",

            "npm-asset/leaflet.markercluster": "~1.5"

        }

    }

## Usage

Enable the **Leaflet** module to be able to use:

  - The configurable **Leaflet Map** as Geofield Widget, with [Leaflet

    Geoman js library](https://geoman.io/leaflet-geoman);

  - The configurable **Leaflet Map** as Geofield Formatter;

  - Enable **Leaflet Views** (`leaflet_views`) submodule for **Leaflet

    Map Views integration** You need to add at least one geofield to the

    Fields list, and select the Leaflet Map style in the Display Format.

    In the settings of the style, select the geofield as the Data Source

    and select a field for Title and Description (which will be rendered

    in the popup).

  - Add, enable and configure ["Geoocoder"

    module](https://www.drupal.org/project/geocoder) to enable Geocoder

    Control (with Autocomplete) for quick Leaflet Map Address search &

    pan/zoom.

As a more powerful alternative, you can use node view modes to be

rendered in the popup. In the Description field, select "<entire node>"

and then select a View mode.

## API Usage

Rendering a map is as simple as instantiating the LeafletService and its

leafletRenderMap method

which takes 3 parameters:

* $map:

An associative array defining a map. See hook_leaflet_map_info(). The module

defines a default map with a OpenStreet Maps base layer.

  - $map: An associative array defining a map. See

    hook\_leaflet\_map\_info(). The module defines a default map with a

    OpenStreet Maps base layer.

  - $features: This is an associative array of all the Leaflet features

    you want to plot on the map. A feature can be a point, linestring,

    polygon, multipolygon, multipolygon, or json object. Additionally,

    features can be grouped into [leaflet layer

    groups](http://leafletjs.com/reference-1.3.0.html#layergroup) so

    they can be controlled together,

* $features:

This is an associative array of all the Leaflet features you

want to plot on the map. A feature can be a point, linestring, polygon,

multipolygon, multipolygon, or json object. Additionally, features can be

grouped into [leaflet layer groups](http://leafletjs.com/reference-1.3.0.html#layergroup)

so they can be controlled together,

  - $height: The map height, expressed in css units.

* $height:

The map height, expressed in css units.

## Tips & Tricks

###Tips & Tricks

### Bind events on geojson (json) features

- ####Bind events on geojson (json) features

  @see: https://www.drupal.org/project/leaflet/issues/3186029

See: <https://www.drupal.org/project/leaflet/issues/3186029>

    $features[] = [

    'type' => 'json',

    'json' => $geojson,

    'events' => [

      'click' => 'Drupal.manageGeojsonClick', // or whatever callback

    ],

        'type' => 'json',

        'json' => $geojson,

        'events' => [

            'click' => 'Drupal.manageGeojsonClick', // or whatever callback

        ],

    ];

    $this->leaflet->leafletRenderMap($map_info, $features, $height),

####Authors/Credits

## Authors/Credits

* [itamair](https://www.drupal.org/u/itamair)

* [levelos](http://drupal.org/user/54135)

* [pvhee](http://drupal.org/user/108811)

  - [itamair](https://www.drupal.org/u/itamair)

  - [levelos](http://drupal.org/user/54135)

  - [pvhee](http://drupal.org/user/108811)

<h2>The Drupal 8 & 9 version of Leaflet</h2>

In stable and usable version,

<ul>

  <li>embeds <a href="https://leafletjs.com/download.html" target="_blank">Leaflet Js library (version 1.4.0)</a>;</li>

  <li>embeds <a href="https://leafletjs.com/download.html" target="_blank">Leaflet JS library (version 1.4.0)</a>;</li>

  <li>provides Leaflet Map Formatter and Leaflet Map Views Integration with advanced functionalities and configurations;</li>

  <li>provides an advanced Leaflet Default Widget, with Leaflet Geoman Js library (interactive drawing of Point and Geometries) and Geocoder Autocomplete integration (with <a href="https://www.drupal.org/project/geocoder" title="Geocoder" target="_blank">Geocoder module</a>;</li>

  <li>provides an advanced Leaflet Default Widget, with Leaflet Geoman JS library (interactive drawing of Point and Geometries) and Geocoder Autocomplete integration (with <a href="https://www.drupal.org/project/geocoder" title="Geocoder" target="_blank">Geocoder module</a>;</li>

  <li>perfectly matches with the <a href="https://www.drupal.org/project/geofield_map" title="Geofield Map module" target="_blank">Geofield Map module</a> widget;</li>

  <li>nicely integrates with the <a href="https://www.drupal.org/project/leaflet_layers" title="Leaflet Layers module" target="_blank">Leaflet Layers module</a>;</li>

</ul>

<strong>IMPORTANT!: Since release 2.0.0 (specifically dedicated and compatibile with Drupal ^8.8 & ^9 and identical with last 8.x-1.41 release) Leaflet implements an advanced new Leaflet Default Widget</strong> (as optimisation and integration of <a href="https://www.drupal.org/project/leaflet_widget" title="Leaflet Widget" target="_blank">Leaflet Widget module</a>).

<strong>IMPORTANT!: Since 8.x-1.2 the Leaflet module itself contains the "Leaflet Markercluster" submodule</strong>, that integrates the <a href="https://github.com/Leaflet/Leaflet.markercluster" title="Leaflet Markercluster Js library" target="_blank">Leaflet Markercluster Js library (version 1.4.1)</a>.

<strong>IMPORTANT!: Since 8.x-1.2 the Leaflet module itself contains the "Leaflet Markercluster" submodule</strong>, that integrates the <a href="https://github.com/Leaflet/Leaflet.markercluster" title="Leaflet Markercluster JS library" target="_blank">Leaflet Markercluster JS library (version 1.4.1)</a>.

It needs to be installed <a href="https://www.drupal.org/docs/develop/using-composer/using-composer-to-manage-drupal-site-dependencies" target="_blank">using Composer to manage Drupal site dependencies</a>, which will also download the required <a href="https://www.drupal.org/project/geofield" title="Geofield Module" target="_blank">Geofield Module</a> dependency and <a href="https://geophp.net" title="GeoPHP library">GeoPHP library</a>.

It means simply running the following command from your project root (where the main composer.json file is sited):

  //  5)  Adjust the initial zoom using zoomFiner, if specified

  //  6)  Cater for a map with no features (use input settings for Zoom and Center, if supplied)

  //

  // @NOTE: This method used by Leaflet Markecluster module (don't remove/rename)

  // @NOTE: This method used by Leaflet MarkerCluster (don't remove/rename)

  Drupal.Leaflet.prototype.fitbounds = function(mapid) {

    let self = this;

    let start_zoom = self.settings.zoom ? self.settings.zoom : 12;

  Drupal.Leaflet.prototype.add_features = function (mapid, features, initial) {

    var leaflet_markercluster_options = this.settings.leaflet_markercluster.options && this.settings.leaflet_markercluster.options.length > 0 ? JSON.parse(this.settings.leaflet_markercluster.options) : {};

    var leaflet_markercluster_inlcude_path = this.settings.leaflet_markercluster.include_path;

    var leaflet_markercluster_include_path = this.settings.leaflet_markercluster.include_path;

    var cluster_layer = new L.MarkerClusterGroup(leaflet_markercluster_options);

    var collections_cluster_layers = {};

          // If the Leaflet feature is extending the Path class (Polygon,

          // Polyline, Circle) don't add it to Markercluster.

          if (lFeature.setStyle && !leaflet_markercluster_inlcude_path) {

          if (lFeature.setStyle && !leaflet_markercluster_include_path) {

            this.lMap.addLayer(lFeature);

            if (feature.popup) {

              lFeature.bindPopup(feature.popup);