Development Road Map Brainstorm [#2350121]

Goals

Because there are a wide range of Leaflet related modules, many of whom have duplicative js code, it would be good to assemble a road-map for identifying how these all relate to the common Leaflet.js back end, identify areas of code redundancy and conflict, explore methods for relating as plugins and generally identifying the various development goals of motivated parties.

User Interface
Extending Leaflet
- Pluggable Extensions in Drupal / LeafletJS
- Alter Hooks
- Token/Argument Support
Layer Control
Performance & Server-Side Data - not really Leaflet specific, but things like views support for clustering and bounding box filtering.

User Interface Needs

Panels support (a la Leaflet GeoJSON) - Views is currently the only UI means of configuring Leaflet maps in Drupal, and while this capability is useful and convenient, there is a strong argument for using Views only as a data source to supply other Entities the raw materials for creating maps.
Config Form Hooks - Leaflet configuration needs to expose hooks to sub-modules to allow them to gracefully add to configuration forms for use in the existing Views Display config screen, as well as any future Panels-based config screen.
Javascript Events - A more robust javascript event model to allow sub-modules to modify leaflet map layers and settings gracefully.
Multiple Feature Layers - It would be useful to support multiple, switcheable layers (such as provided by Leaflet GeoJSON module).

Leaflet Related Modules

Module Name	Provides UI	Adds/Alters Layers in js	Leaflet Hooks Used	Triggers Used	Proposed Triggers	Extends leaflet.drupal.js	Extends leaflet.js
Leaflet	Node Field Widget Views Display	No		N/A	None	Provider of leaflet.drupal.js	No
Leaflet More Maps	No	No	hook_leaflet_map_info(), hook_leaflet_map_info_alter()	No	No	No	No
Leaflet GeoJSON	Panels Beans	No	hook_leaflet_map_info(), hook_leaflet_map_info_alter()	No	No	No	Yes - registers an event listener for Leaflet "moveend" to call new function "makeGeoJSONLayer"

Leaflet

The base module integrates with leaflet.js by providing geojson export of a map definition.
Includes a single example map with a base layer and geojson feature from Drupal content.
Uses file "leaflet.drupal.js" to integrate with Leaflet.js library

Supports the use of a single layer class for base and overlays, "L.TileLayerZoomSwitch", by calling "extend()" method of Leaflet "TileLayer" (L.TileLayer.extend).
L.TileLayerZoomSwitch Adds grouping and switchability, but effectively limits access to "TileLayer" features, does not support other Leaflet.js TilerLayer types such as "Raster Layer"s TileLayer.WMS & ImageOverlay
This also excludes adding "Vector Layer" and "Other Layers" (such as GeoJSON)

Does not implement CTools plugin framework

Leaflet More Maps

Expands map definitions for Leaflet to include over 20 maps with multiple layers and selection styles.
Extends or overwrites (?) "leaflet.drupal.js" with code in "leaflet_more_maps.js"

Leaflet Marker Cluster

Enables marker clustering in the Leaflet map.
Overwrites much code from leaflet.drupal.js (even has a mea culpa in the javscript file see Code 1 below)

Code 1: Sorry, I had to.

*
 * We are overriding a large part of the JS defined in leaflet (leaflet.drupal.js).
 * Not nice, but we can't do otherwise without refactoring code in Leaflet.
 */

Leaflet GeoJSON

Provides access to a Views GeoJSON as a layer in Leaflet
Does NOT overwrite js code, uses "include" on object "initialize" method to apply geoJSON options onto Leaflet Lmap object (Seee Code 2 below)
Adds critical function to allow client to load features from http request "makeGeoJSONLayer(map, url)"

this event called when Leaflet map "moveend()" method is triggered (as soon as user finishes dragging/zooming)

Could this config options js code live in Drupal in the map array created/modified by "hook_leaflet_map_info()"?

Code 2: Leaflet GeoJSON Injection.

  // Inject into leaflet initialize.
  // @todo: there should be a nicer way to do that?
  _leaflet_bbox_old_leaflet_initialize = L.Map.prototype.initialize;
  L.Map.include({
    initialize: function(/*HTMLElement or String*/ id, /*Object*/ options) {
      _leaflet_bbox_old_leaflet_initialize.apply(this, [id, options]);
      this.on('load', Drupal.leafletBBox.onMapLoad, this);
    }
  });

Leaflet OMS

Extends Leaflet with the Overlapping Marker Spiderfier library
Overwrites the whole attach code from leaflet.drupal.js - just to add a few new lines.

Leaflet Popup Outside

Displays Pop-Ups in a div external to the map
Over-rides default Pop-up behavior in js by "Attaching to Leaflet object via its API" (from code comments)

Leaflet Label

Displays Pop-Ups in a div external to the map
Over-rides default Pop-up behavior in js using "bind" method, similar to Leaflet Popup Outside (see "Code 3" below)
Could this be merged with LPO for toolkit of labelling solutions?

Code 3: Using javascript ".bind" method.

(function ($) {

  $(document).bind('leaflet.feature', function(e, lFeature, feature) {
    if (feature.label) {
      lFeature.bindLabel(feature.label);
    }
  });

})(jQuery);

Use cases

It is helpful to consider the types of uses of the module to see how best to provide the base API and how a user can extend it.

Map with markers/shapes from remote GeoJSON source (see image 1 below)-
- Data will be dynamically tile-able, for better performance
- Source of data is "truly remote", data sourced outside of Drupal
- Source of data is "local remote", i.e., served by the same Drupal instance
"Progressive Server Side Clustering" - client side map and server each handle some of the clustering tasks.
- Video demo from @chriscallip here: http://www.youtube.com/watch?v=pRYKNlaTbKk
- can this use "quantity-based" zoom level to switch server/client - both server and client would need shared q-based algorithm
Map with markers of nodes
Map with markers of other content
And markers that pop up an info window

Source of data is the node
Source of data is one or more fields on the view

Markers with extended behavior (hover state opens one popup, click navigates or focuses another list on screen)
Default marker popup
External event focuses and pops a marker

Image 1: Geocluster with Leaflet shows remote access use diagram (@dasjo thesis problem statement).

Geocluster Views Use Case

Coding Approaches

Javascript

The base script leaflet.drupal.js adds "trigger" access to the base map class, whereby modules that extend it make a call to "bind" to advertise that they will be including modifications during the triggered event (see "Code 4" below).

Code 4: The following two triggers are exposed by leaflet.drupal.js:

        // Allow others to do something with the feature.
        $(document).trigger('leaflet.feature', [lFeature, feature]);

        // Allow other modules to get access to the map object using jQuery's trigger method
        $(document).trigger('leaflet.map', [this.map, lMap]);

Code 5: "bind" example, adding a location control (given here by @pvhee ):

$(document).bind('leaflet.map', function(e, map, lMap) {
  // do something with your map, e.g. adding a support for LocateControl, https://github.com/domoritz/leaflet-locatecontrol
  L.control.locate().addTo(map);
}

Drupal

Javascript Inclusion

When using included js in Drupal, things such as "Leaflet GeoJSON" modify the map object after the base Drupal Leaflet module has done it's thing. In order to make this proceed without error, any script that is doing this modification must be loaded after drupal.leaflet.js as indicated in this thread and as outlined in the API.

Configuration in Drupal UI

Views UI for map creation
Fields config in "Manage Display"

Configuration via Leaflet hooks

hook_leaflet_map_info - From Leaflet API - modules implementing this hook can append map definitions with multiple layers via properly formatted Drupal Leaflet arrays, see "Code 6" below (which I think are translated directly into Leaflet JS Object properties?)
hook_leaflet_map_info_alter - Leaflet API (See "Code 7" below).

Code 6: Example Drupal Leaflet map definition array for OSM Weather Map from Leaflet More Maps. Variables $prot and $zxy

  // Use headless protocol rather than logic based on global $is_https;
  $prot = '//';
  // As used by most.
  $zxy = '{z}/{x}/{y}.png';
  // As used by Esri.
  $zyx = '{z}/{y}/{x}.png';

  $attr_owm = 'OpenWeatherMap. ' . $attr_osm;
  $map_info['osm-weather'] = array(
    'label' => 'OSM OpenWeatherMap (zoom 0..18)',
    'description' => t('Precipitation with pressure contours'),
    'settings' => $default_settings,
    'layers' => array(
      'base' => array(
        'urlTemplate' => $prot . "{s}.tile.openstreetmap.org/$zxy",
        'options' => array('attribution' => $attr_owm),
        'layer_type' => 'base', // Allowed values "base" or "overlay"
      ),
      'precipitation' => array(
        'urlTemplate' => $prot . "{s}.tile.openweathermap.org/map/precipitation/$zxy",
        'options' => array(
          'attribution' => $attr_owm,
          'transparent' => true,
        ),
        'layer_type' => 'overlay', // Allowed values "base" or "overlay"
      ),
      'pressure' => array(
        'urlTemplate' => $prot . "{s}.tile.openweathermap.org/map/pressure_cntr/$zxy",
        'options' => array('attribution' => $attr_owm),
        'layer_type' => 'overlay', // Allowed values "base" or "overlay"
      ),
    ),
  );

Code 7: Example of hook_leaflet_map_info_alter() as implemented by LeafletMoreMaps.

function leaflet_more_maps_leaflet_map_info_alter(&$map_info) {
  @ksort($map_info, SORT_NATURAL | SORT_FLAG_CASE);
}

Comments

Comment #1

das-peter CreditAttribution: das-peter commented 4 October 2014 at 04:28

Issue summary:

Issue summary:	View changes
Related issues:		+#1893660: Refactor leaflet.drupal.js to allow other modules to extend and hook into map creation