Skip to main content

<map-link>

The <map-link> element is an extended HTML link element, for use in Web maps. Most of the extensions center on proposed new values of the rel attribute.

<map-link> has several uses:

  • include layer data attribution / licensing links in the bottom right-hand corner of the map
  • provide links to different styles of the layer, via style and self rel values. These links are rendered as user affordances, and can be used to switch, for example, from satellite to map view of a layer.
  • provide links to alternate projections for a layer, via the alternate rel value, in conjunction with the projection="..." attribute. Such links are automatically followed by the polyfill when appropriate.
  • provide a URL template that is processed and converted to a URL and fetched by the polyfill, each time the map requires new content to render, such as a tile, via the tile, image, feature and query rel values, in conjunction with the tref="..." attribute. Such links are automatically created and followed / imported when appropriate.
  • include links to legend graphics for a layer. Currently such links are rendered as hyperlinks, not as graphics.
  • provide links to CSS and pmtiles stylesheets via the stylesheet rel value, which are imported by the polyfill automatically.
  • provide links to layers at next native zoom level via zoomin, zoomout rel values. Such links are automatically followed by the polyfill when appropriate.

Attributes

rel

The rel attribute designates the type of resource that is linked to. MapML defines several uses of existing and new rel keyword values.

ValueDescription
licenseThe href value links to a license description resource for the layer. The title attribute is used as the text to display for the link. The hyperlink is presented in the attribution control, at the lower right corner of the map viewport.
alternateThe alternate rel value is used with the projection attribute to provide the link to an equivalent layer resource in a different projection than that provided by the current resource. This can be very useful for providing an author-friendly experience, where a map document may be added as a layer to a map that declares a different projection than that of the layer. The polyfill will automatically "redirect" to the alternate projection document that matches that of the map.
selfThe self style (or style self) link rel indicates that the current document is one of a set of named alternate styles for a layer. Other members of the set are <map-link> elements tagged with the style link relation. Other members of the set of alternate / different styles for the layer are presented to the user as a set of mutually exclusive choices. User selection of one of the choices replaces the current layer entirely.
styleThe style link relation by itself designates that link as an alternate or different style of the current layer style. This is often used to switch between, for example, satellite and cartographic views of the same layer. When used in conjunction with the self link relation, i.e. rel="self style", the current document is identified as a member of the set of alternate styles, and is selected in the layer control affordance for changing styles.
tileThis link relation is used in conjunction with the tref="..." attribute to define a URL template that identifies native (server) tile resources. Can be used in conjunction with the type="..." attribute to indicate the media type of the remote resource, for example: type="text/mapml" tells the polyfill to parse and render the fetched resource as map feature content. This link relation is used with standard Web Map Tile Services (WMTS), and its non-standard equivalents.
imageThe image link relation is used similarly to the tile link relation, except it tells the polyfill that the remote resources to be fetched are images that will be trimmed (by the server) to exactly match the width and height of the map viewport. This link relation is used with standard Web Map Services (WMS) and its non-standard equivalents.
featuresThe features link relation tells the polyfill to parse and render the fetched resource as map feature content.
zoominThe link href is followed automatically by the polyfill when the map is zoomed in by the user to a value greater than the maximimum value of the zoom range of the current layer. The referenced map layer resource replaces the current map layer. The polyfill does not represent this link as a user-visible affordance, it is followed automatically. If the remote resource does not contain a reciprocal zoomout link, the map state change is one-way i.e. the layer is permanently replaced.
zoomoutThe link href is followed automatically by the polyfill when the map is zoomed out by the user to a value less than the minimum value of the zoom range of the current layer. The referenced map layer resource replaces the current map layer. The polyfill does not represent this link as a user-visible affordance, it is followed automatically. If the remote resource does not contain a reciprocal zoomin link, the map state change is one-way i.e. the layer is permanently replaced.
legendThe legend link relation designates a link to metadata, typically an image, describing the symbology used by the current layer. Currently, the polyfill creates a hyperlink for the label of the layer in the layer control, which opens in a new browsing context.
queryThe query link relation is used in combination with the tref="..." attribute to establish a URL template that composes a map query URL based on user map gestures such as click or touch. These URLs are fetched and the response presented on top of the map as a popup. Such queries can return text/html or text/mapml responses. In the latter case, the response may contain more than one feature, in which case a 'paged' popup is generated, allowing the user to cycle through the features' individual metadata.
stylesheetThe link imports a CSS or pmtiles stylesheet from the href value.

type

The type attribute defines the expected MIME media type of the remote resource. Depending on the rel value, the type may play a significant role in determining the polyfill behaviour.

Supported values of type and function

ValueDescription
text/mapmlUse in combination with rel=tile or rel=features, where tref refers to a MapML formated data source, often GeoServer or other spatial content management system.
text/mapmlUse in combination with rel=self, rel=style and rel="self style", where href refers to an alternate or current style of the current MapML document. Supported by GeoServer, but can be readily created in static (remote-only) MapML documents
image/*Use in combination with rel=image and rel=tile to load full-viewport map images and image tiles, respectively, when tref refers to an image-based data source, such as any Web Map Service or Web Map Tile Service. See Mozilla Developer Network for a list of supported types.
application/pmtilesUse in combination with rel=tile, where tref refers to pmtiles format or map resources. *
application/pmtiles+stylesheetUse in combination with rel=stylesheet, where href refers to a JavaScript module structured in a specific way. *
application/vnd.mapbox-vector-tileUse in combination with rel=tile, where tref refers to a Mapbox Vector Tiles-format so-called "{z}{x}{y}" Web Map Tile Service or API. *

* see Using mvt styles for details on how to use these type values


title

The title of the linked resource is usually rendered or presented to the user, for example, the <map-link rel="license" title="Copyright FooBar Inc."> link is rendered as a hyperlink in the attribution control entry for the current layer.


href

The href of a <map-link> must be a URL value of a resource that can be fetched. The URL can be absolute or relative.


hreflang

Advisory language designation about remote resource.


tref

The tref attribute contains a string that, once processed, will be treated as a URL and fetched automatically by the polyfill. The string is known as a URL template. The processing that takes place prior to a URL template becoming a valid URL is variable reference substitution. Variables are created by <map-input name="foo"> elements. The name of the variable can be referenced in the URL template string contained in the tref value, using the {foo} syntax notation. A URL template string can contain 0 or more variable references. Processing will remove variable references that are valid. That is, all variables that have been created by <map-input>s that are referenced in the template will be replaced with the value of the variable at the time of processing.


tms

The tms boolean attribute tells the polyfill that the row (vertical) axis of the remote tile server follows the tms convention of the y (row) axis being reversed (compared with convention), with the positive direction of tile row values being up/north. This convention is not a standard, yet has unfortunately become popular among open source GIS professionals.


projection

The projection attribute identifies the projection of the remote layer resource. This attribute is used in conjunction with the rel=alternate rel value.

Projection values defined by the polyfill include: OSMTILE, WGS84, CBMTILE and APSTILE. Projection values are case-sensitive.


Content categoriesMetadata content
Permitted contentNone. Like the HTML <link> element <map-link> is an empty element.
Tag omissionWhile the HTML <link> element is a void element, the polyfill must have an end tag.
Permitted parentsAny element that accepts metadata element children.
Implicit ARIA rolelink with href attribute.
Permitted ARIA rolesNo roles permitted.
DOM InterfaceHTMLLinkElement

Examples

Tile Mapping Specification (tms)

<mapml-viewer  projection="OSMTILE" zoom="1" lat="0" lon="0" controls>
<map-layer label="OpenStreetMap" src="https://geogratis.gc.ca/mapml/en/osmtile/osm/" checked hidden ></map-layer>
<map-layer label="TMS COG Source" checked>
<map-extent units="OSMTILE" checked>
<map-input name="zoom" type="zoom" min="1" max="12"></map-input>
<map-input name="row" type="location" axis="row" units="tilematrix" ></map-input>
<map-input name="col" type="location" axis="column" units="tilematrix"></map-input>
<!-- use the tms attribute to indicate that remote tile cache follows tms conventions -->
<map-link tms rel="tile" tref="https://s3-eu-west-1.amazonaws.com/vito-lcv/global/2019/cog-grass-colored-fraction_grass/{zoom}/{col}/{row}.png">
</map-link>
</map-extent>
</map-layer>
</mapml-viewer>

Accessibility


Specifications

Specification
MapML link element
HTML link element

Requirements

Report problems with these requirements on GitHub

requirement enhancement impractical undecided under discussion

SpecViewerAPI
Vector features and overlays (5.2)
Display map data attribution and links (5.2.4)
fullfull
User navigation (pan and zoom) (5.4)
Hide or show (and maybe dynamically load) vector features and labels on zoom (5.4.7)
fullfull