=begin rakudoc :type<plugin>
=TITLE LeafletMap
=SUBTITLE The leafletmap plugin inserts a map in place of a custom C<=LeafletMap>.
=for AUTHOR :hidden
Richard Hainsworth aka finanalyst

=for VERSION :hidden
v0.1.1

=head Overview

The plugin uses the fabulous
L<Leaflet JS library|https://leafletjs.com>. 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
=begin code :lang<RakuDoc>
=config LeafletMap :caption<Map with default settings>
=LeafletMap
=end code

produces:
=begin section
=config LeafletMap :caption<Map with default settings>
=LeafletMap
=end section

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 C<=> and there must be at least one
horizontal whitespace character. Thus

=begin code :lang<RakuDoc>
=for LeafletMap
=  :lat<55.948595> :long<-3.199913>
=  :zoom(13) :height<300px>
=  :map-id<new-map>
=  :width<50vw>
=  :caption<Edinburgh Castle>
=  :headlevel(2)
=end code

will produce
=for LeafletMap
=  :lat<55.948595> :long<-3.199913>
=  :zoom(13) :height<300px>
=  :map-id<new-map>
=  :width<50vw>
=  :caption<Edinburgh Castle>
=  :headlevel(2)

Maps are generated from tiles and the information can be rendered in many ways. There
are multiple tile providers,
collected in a github resource L<leaflet-extras|https://github.com/leaflet-extras/leaflet-providers>.
"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.
L<Here are all|http://leaflet-extras.github.io/leaflet-providers/preview/index.html> the providers
and variants.

For example, this is a map with the Esri.WorldImagery provider[.variant] string.
=begin code :lang<RakuDoc>
=for LeafletMap :provider<Esri.WorldImagery> :map-id<third-map> :width<50vw> :caption<Esri World Imagery>
=end code
=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.

=head Markers on maps

Another common need is to put markers on a map. This can be done using C<=LeafMarker> blocks. For example,
the following code creates a map with a couple of fish and chips shops.

=begin code :lang<RakuDoc>
=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>

=end code

In order to get two custom RakuDoc blocks to work together, we need some extra options:
=item The C<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.

=item C<:title<text>> associates I<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.

=item C<:popup<text>> associates I<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.

=item C<:fa-icon> will work if the C<FontAwesome> plugin has been configured for rendering
(see documentation on FontAwesome for detail about extra commands).

=item C<:!toc> I<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.

=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>
=    :!toc
=    :title<Cardiff Castle>

=for LeafMarker
=    :map-id<map-four>
=    :lat<51.529269> :long<-3.188109>
=    :fa-icon<fa-solid fa-utensils fa-spin fa-3x fa-fw>
=    :!toc
=    :title<Fintans Fish & Chip Co>

=for LeafMarker
=    :map-id<map-four>
=    :lat<51.502576> :long<-3.190222>
=    :fa-icon<fa-solid fa-utensils>
=    :!toc
=    :popup<Yan’s Fish Bar>

=place semantic:AUTHOR :caption<Credits>
=place semantic:VERSION :!toc

=end rakudoc