The leafletmap plugin inserts a map in place of a custom =LeafletMap.
The plugin uses the fabulous Leaflet JS library. The map MUST have a fixed height, so this is specified in the config attribute.
By default, the map will point at Cardiff Castle in Cardiff, Wales with a 200px height and 16 unit magnification, using OpenStreetMap as the tile provider. So
=config LeafletMap :caption<Map with default settings>
=LeafletMap
produces:
The simplest customisation is to centre the map by specifying the latitude and longitude, and to change the starting zoom level (smaller numbers are larger views). It is also possible to change the height of the map. Each map on a page must have its own id. Additionally, when developing a page, not setting a width is tiresome. Note another very underutilised feature of Rakudoc, the ability to spread meta-data across lines. The first virtual column must start in a = and there must be at least one horizontal whitespace character. Thus
=for LeafletMap
= :lat<55.948595> :long<-3.199913>
= :zoom(13) :height<300px>
= :map-id<new-map>
= :width<50vw>
= :caption<Edinburgh Castle>
= :headlevel(2)
will produce
Maps are generated from tiles and the information can be rendered in many ways. There are multiple tile providers, collected in a github resource leaflet-extras. "Leaflet-providers provides tile layers from different providers, including OpenStreetMap, Stamen, Esri and OpenWeatherMap. The full listing of free to use layers can be previewed." (from README of leaflet-providers)
Some providers have map types that do not need registration, most types need registration. Here are all the providers and variants.
For example, this is a map with the Esri.WorldImagery provider[.variant] string.
=for LeafletMap :provider<Esri.WorldImagery> :map-id<third-map> :width<50vw> :caption<Esri World Imagery>
Registration offers more variety and more complex maps, but goes beyond this simple RakuDoc::Plugin. However, the Plugin can itself be subclassed and more data included in the config attribute.
Another common need is to put markers on a map. This can be done using =LeafMarker blocks. For example, the following code creates a map with a couple of fish and chips shops.
=for LeafletMap :map-id<map-four> :height<600px> :zoom(12) :width<50vw> :caption<Two chippies>
=for LeafMarker
= :map-id<map-four> :name<mk1>
= :lat<51.48160> :long<-3.18070>
= :headlevel(0)
= :title<Cardiff Castle>
=for LeafMarker
= :map-id<map-four>
= :lat<51.529269> :long<-3.188109>
= :fa-icon<fas fa-cutlery fa-spin fa-3x fa-fw>
= :headlevel(0)
= :title<Fintans Fish & Chip Co>
=for LeafMarker
= :map-id<map-four>
= :lat<51.502576> :long<-3.190222>
= :fa-icon<fas fa-cutlery>
= :headlevel(0)
= :popup<Yan’s Fish Bar>
In order to get two custom RakuDoc blocks to work together, we need some extra options:
The map-id of the map must be set so that the markers can be associated with the correct map, especially if more than one map is on a page, otherwise the default map id is used.
:title<text> associates text to be associated with the marker, which is visible with a mouseover. Formatting limitations means that the text must be short and a single line.
:popup<text> associates text with the marker, but the user needs to click in it to see, and the limitations on the size of the text are a bit more relaxed.
:fa-icon will work if the FontAwesome plugin has been configured for rendering (see documentation on FontAwesome for detail about extra commands).
:!toc toc is set as False so that the Table of Contents is not affected. By default all custom blocks are inserted into the TOC, but markers are rarely put in the TOC.