@wq/leaflet

@wq/leaflet

@wq/leaflet is a plugin for @wq/app that provides integration with Leaflet. When used together with @wq/map, @wq/leaflet can leverage the wq configuration object to generate interactive maps for pages rendered via @wq/app. The generated maps can automatically download and display GeoJSON data rendered by wq.db's REST API or any third party service.

Installation

wq.app for PyPI

python3 -m venv venv      # create virtual env (if needed)
. venv/bin/activate       # activate virtual env
python3 -m pip install wq # install wq framework (wq.app, wq.db, etc.)
# pip install wq.app      # install wq.app only

@wq/leaflet for npm

npm install @wq/leaflet  # install @wq/leaflet, @wq/map, and deps

API

@wq/leaflet should be registered with @wq/app as a plugin. @wq/map will be registered automatically. To enable @wq/leaflet's ESRI and WMS layer support, import @wq/leaflet/mapserv instead of @wq/leaflet.

import app from '@wq/app';
import leaflet from '@wq/leaflet'; // Or @wq/leaflet/mapserv

app.use(leaflet);  // Automatically registers @wq/map

app.init(...);

@wq/leaflet consists primarily of React components that override the placeholders defined in @wq/map. The components in @wq/leaflet extend the existing react-leaflet library.

Configuration

@wq/leaflet relies on @wq/map's configuration and conventions, as well as two additional options to configure popup content and marker icons.

app.init({
  // @wq/map config
  "map": {
    "bounds": [[-4, -4], [4, 4]
  },
  
  // @wq/leaflet config
  "leaflet": {
    "popups": {
      "item": "<h3>{{label}}</h3><p>{{description}}</p>"
    }
  },
  
  // @wq/jquery-mobile config (backwards compatibility)
  /*
  "jqmrenderer": {
    "templates": {
      "item_popup": "<h3>{{label}}</h3><p>{{description}}</p>"
    }
  },
  */
  
  // @wq/app pages & routes
  "pages": {
    "item": {
      "url": "items",
      "list": true,
      "form": [ ... ],
      "map": [{
        "mode": "list",
        "layers": [{
           // @wq/map general overlay props
           "name": "Items",
           "type": "geojson",
           
           // @wq/leaflet-specific props
           "popup": "item",
           "icon": "{{#flag}}red{{/flag}}{{^flag}}default{{/flag}}"
        }]
      }],
      ...
    }
  }
});

Popups

Popups are specified as Mustache templates that are rendered with the properties of the features in a GeoJSON layer. Popup templates can be defined via config.leaflet.popups. Then, the configuration for each Geojson layer can specify a template name as the popup property. For backwards compatibility with @wq/map 1.2 and earlier, @wq/leaflet will also check the @wq/jquery-mobile template list for any templates ending in *_popup.

Marker Icons

Marker icons are instances of L.Icon for use in layer configurations. While it is possible to define icons directly via config.leaflet.icons, it is more convenient to use the leaflet.createIcon(name, options) method, which includes built-in defaults for options that are optimized to make it trivial to define icons that have the same dimensions and shadow as Leaflet's default icon:

name	default
iconSize	[25, 41]
iconAnchor	[12, 41]
popupAnchor	[1, -34]
shadowSize	[41, 41]
shadowUrl	L.Icon.Default.imagePath + '/marker-shadow.png'

import app from '@wq/app';
import leaflet from '@wq/leaflet';
import config from './config';

leaflet.createIcon("green", {'iconUrl': "/images/red.png"});

app.init(config).then(...)

leaflet.createIcon() should be called during application startup, i.e. preferably before or right after init(). With the icons defined, the configuration for each Geojson layer can specify icon as:

• the name of an icon to use
• a Mustache template that will compile to an icon name (as in the example above),
• or a function returning an icon name.

If a template or a function, it will be called with the feature.properties for each feature in the dataset.

Components

@wq/leaflet provides implementations of the components defined by @wq/map.

plugin key	description
components	High-level map components (Map, Legend, etc.)
basemaps	Basemap layers, typically tiled imagery or road network
overlays	Overlay layers, such as GeoJSON vectors

General Components

See @wq/map for more info.

name	details
Map	Top level component that renders react-leaflet's <Map/>
Legend	Wrapper for react-leaflet's <LayersControl/>
BasemapToggle	Wrapper for react-leaflet's <LayersControl.BaseLayer/>
OverlayToggle	Wrapper for react-leaflet's <LayersControl.Overlay/>
MapInteraction	Not overridden by @wq/leaflet

Basemap Components

See basemap components for more info. @wq/leaflet implements the default tile, empty, and group layer types. @wq/leaflet/mapserv also provides a few additional basemap types via esri-leaflet and react-leaflet

config name	component	details
tile	Tile	Raster tile layer, typically with 256x256 tile images in "Web Mercator" projection
empty	Empty	Provides an option to completely disable the basemap.
group	Group	Treats a group of related layers as a single basemap. The configuration for the group should specify a layers array containing one or more basemap layer configurations.
esri-basemap*	EsriBasemap	Renders one of the named Esri basemaps with optional labels.
esri-tiled*	EsriTiled	Renders a custom Esri TiledMapLayer
wms-tiled*	WmsTiled	Requests tiles from a WMS service

Options marked with * are only available by importing @wq/leaflet/mapserv instead of @wq/leaflet

Overlay Components

See overlay components for more info. @wq/leaflet implements the default geojson, empty, and group layer types. @wq/leaflet/mapserv also provides a few additional overlay types from esri-leaflet and leaflet.wms

config name	component	details
geojson	Geojson	GeoJSON overlay. If a URL is provided it will be retrieved and loaded
empty	Empty	Non-rendered layer that essentially is just to provide a toggle-able entry in the legend. (Typically used with a custom component somewhere else in the tree that calls useMapState() and renders accordingly)
group	Group	Treats a group of related layers as a single overlay. The configuration for the group should specify a layers array containing one or more overlay configurations.
esri-dynamic*	EsriDynamic	Renders custom Esri dynamic (non-tiled) map imagery
esri-feature*	EsriFeature	Renders custom Esri feature vectors
wms*	Wms	Non-tiled WMS service
n/a	Highlight	GeoJSON overlay with preset highlight styles, which renders the contents (if any) of useMapState().highlight
n/a	Draw	Drawing tools based on react-leaflet-draw

Options marked with * are only available by importing @wq/leaflet/mapserv instead of @wq/leaflet