Visual Essay Map Tag

The ve-map tag indicates that a map should be added as a visualization component for the associated text element(s). Maps can be further customized with ve-map-layer directives that define layers or overlays to be applied to the map.

Syntax

<param ve-map>

Options

basemap: By default, OpenStreetMap (OSM) is used for the base map. Other base maps are available and can be requested with this attribute. The available base maps are:
center: This attribute defines the center point for the map. The center point can be defined as a latitude and longitude coordinates or using a QID for an entity that is associated with geo-coordinates. For instance, the following are equivalent. They both use the city of Ann Arbor, Michigan as the map center point. In the first version the latitude and longitude coordinates are specified and in the second the Wikidata QID for Ann Arbor is provided.
```
<param ve-map center="42.2813, -83.7483">
<param ve-map center="Q485172">
```
zoom: This attribute defines the starting map zoom level. This number can be expressed in 0.1 increments, such as zoom="3.4"
show-labels: By default, the labels for any locations plotted on a map (both markers and GeoJSON features) are not automatically displayed when the map is loaded. This attribute can be used to override this default behavior and show labels on loading. Note that a user can still open the label by hovering over and/or clicking on the label or GeoJSON defined region.
prefer-geojson: Location entities are automatically added to a map components that is visible for an active text element. By default the location is represented as a marker pinned at a discrete geo-coordinate. However, many location entities in the Wikidata knowledge graph can also be associated with GeoJSON shape files that represent the location as region using a polygon shape. If the visualization of a location on a map using the GeoJSON defined region is preferred over a simple marker/pin this attribute is used to express that preference.

The following attributes are used for the time dimension control and animation. This functionality is provided by the Leaflet TimeDimension plugin. Refer to Leaflet.TimeDimension for more details on the options.

time-dimension: Set to true to enable the time dimension controls. When enabling the time dimension the input data is expected to include a time property in the feature properties object.
data: URL to GeoJSON or delimited (.csv or .tsv) file with time data. GeoJSON files may also be loaded using the ve-map-layer tag.
time-interval: String to construct the first available time and the last available time. Format: ISO8601 Time inverval
duration: Period of time which the features will be shown on the map after their time has passed. If null, all previous times will be shown. Format: ISO8601 Duration
max-zoom: The maximum zoom level to use when auto-fit is enabled. Default=16
date-format: Format to use for the date/time in the time dimension control. Default=YYYY-MM-DD (refer to https://momentjs.com/docs/#/displaying/)
auto-play: Animate the map automatically. Default=false
auto-fit: When running the animation automatically resize the viewing area to fit all active points. Default=false
loop: Loop the animation when auto-play is enabled. Default=false
fps: Animation speed. Default=1fps

The following attributes control marker and geojson formatting:

marker-style: circle or pin - default = pin
radius: Marker radius when marker-style is set to circle. Default=4
marker-symbol: A Fontawesome icon label. Default=circle
marker-color: Default=#2C84CB
opacity: Marker opacity. Default=1
marker-symbol-color: Default=#FFF
marker-symbol-xoffset: Default=0
marker-symbol-yoffset: Default=0
stroke: Line color. Default='#FB683F'
stroke-width : Marker/GeoJSON feature line width.
stroke-opacity: Default=0
fill: Fill color. Default=#32C125
fill-opacity: Default=0.5

Custom Markers and Image Overlay

The following tag uses a Leaflet Icon to create a custom marker or put an image on the map. The syntax for the basic tag is:

<param ve-map-marker>

Below are the available options for the map marker tag.

Options:

url - required URL to image.
center - required latitude and longitude coordinates for the image placement, in that order, separated by a comma. For example: "39, 20"
size - required the size of the image in pixels, separated by a comma.
circle - when set to "true", the image is cropped to an icon-sized circle
square - when set to true, the image is cropped to an icon-sized square
iconAnchor - The coordinates of the "tip" of the icon (relative to its top left corner). The icon will be aligned so that this point is at the marker's geographical location. Centered by default.
shadowUrl - the URL to a shadow image.
shadowSize - the size of the shadow image in pixels, separated by a comma.
shadowAnchor - The coordinates of the "tip" of the shadow (relative to its top left corner) (the same as iconAnchor if not specified).
className - A custom class name to assign to both primary and shadow images. Used for custom CSS styling.

Interactions

flyto: The flyto action takes a comma-delimited value consisting latitude, longitude, and zoom level.
Below are example flyto actions for Rome, one for a click event and another for a mouseover (hover) event:

	<span data-click-map-flyto="41.893,12.483,11">Rome</span>
	<span data-mouseover-map-flyto="41.893,12.483,11">Rome</span>

Usage examples

	<param ve-map center="32.262084, 64.391554" zoom="2.5" stroke-width="0" show-labels>
	<param ve-map-layer geojson url="/geojson/peony.json" title="Peony Distribution" active>

	<param ve-map center="0.040297, -71.224280" zoom="3.8" marker-type="circle" stroke-width="0" fill-opacity="1">
	<param ve-map-layer geojson active title="Aurea" url="https://jstor-labs.github.io/plant-humanities/data/heliconia-aurea.tsv" fill="#D11141" radius="6">  
    <param ve-map-layer geojson active title="Bihai" url="https://jstor-labs.github.io/plant-humanities/data/heliconia-bihai.tsv" radius="4.5" fill="#009900">

The following example demonstrates a map with a custom marker and an image.

<param ve-map center="2, 40" zoom="4">
<param ve-map-marker
       url="https://leafletjs.com/examples/custom-icons/leaf-green.png"
       coords="17.188263050774324, 52.28406397248149"
       size="38, 95"
       iconAnchor="22, 94"
       shadowUrl="https://leafletjs.com/examples/custom-icons/leaf-shadow.png"
       shadowSize="50, 64">
<param ve-map-marker
       url="https://upload.wikimedia.org/wikipedia/commons/thumb/9/9a/Pinz%C3%B3n_azul_de_Gran_Canaria_%28macho%29%2C_M._A._Pe%C3%B1a.jpg/220px-Pinz%C3%B3n_azul_de_Gran_Canaria_%28macho%29%2C_M._A._Pe%C3%B1a.jpg""
       coords="-7.182405194219532, 35.05200886854757"
       size="129, 170"
       circle="true"
       >