@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