The HTML <map> Element proposal

This version:
https://maps4html.github.io/HTML-Map-Element/spec/
Latest version:
https://github.com/Maps4HTML/HTML-Map-Element/tree/gh-pages
Previous version:
https://github.com/Maps4HTML/HTML-Map-Element/spec/2015/
Editors:
Peter Rushforth, Natural Resources Canada
Authors:
Maps for HTML Community Group.
Participate:
File an issue (open issues)
Feedback:
public-maps4html@w3.org (archives)

Copyright © 2015-2019 the Contributors to the HTML <map> Element proposal, published by the Maps for HTML Community Group under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.

Obsoletion Notice

The Web Mapping Elements are now defined in the MapML specification.

This document is no longer actively maintained, and should not be used as a guide for implementations.

Abstract

The standard HTML map element allows the HTML author to designate sub-areas of an image to be used as hyperlinks, creating a two-dimensional "image map". This functionality, while useful, is limited to the simplest of mapping applications. A more generally useful map element would enable (functions like) zooming and panning of the map in a traditional Web mapping way, while simultaneously being simple and declarative for an HTML author to include on their Web page. This specification proposes the syntax and semantics of an extended map element.

The applications of Web maps are diverse. The wide scope of use of Web maps appears similarly broad to that of other Web media types, such as video or audio. In other words, there are a multitude of reasons for wanting to include a map on your Web page. The HTML map element proposed by this document should be provider-agnostic, and should only depend on Web standards, including Uniform Resource Identifiers, Document Object Model, Cascading Style Sheets and media types. To that end, the present specification proposal is related to Map Markup Language [MapML].

Status of This Document

This specification is a work in progress. As updates to the Customized Built-In HTML map Element implementation are prioritized, worked on and finished, documentation of how to access those features through markup and script will be added here.

Although W3C has provided the template for this document for community use, the document is not affiliated with W3C in any way, and is not endorsed or approved by W3C.

This document is a draft of this specification, produced by an independent party. It is inappropriate to cite this specification as as a publication of the World Wide Web Consortium (W3C), or anything other than a work in progress by an independent entity.

Intent of this Specification

This specification is intended as a proposal to the HTML Working Group to extend the semantics of the standard HTML map element. A related specification describes Map Markup Language, which is a hypertext document format for maps.

Implementation Experience

A Customized built-in HTML map Element has been developed which implements this specification using the Leaflet and Polymer JavaScript libraries.

Changes Since the Previous Draft

Changed references from <web-map> to map, since the implementation is a customized built-in element, and in consideration of the fact that this is a proposal to extend the standard HTML map element.

Level of Endorsement by the Community

Map Markup Language is essential to this proposal, in that it implements the semantics required to provide a URL-based access to map documents in the the style of the Web. MapML is the subject of Open Geospatial Consortium innovation testbed activities, where it is being actively and collaboratively developed by members of the Consortium.

Please join the W3C Maps for HTML Community Group if you would like to contribute to the development and implementation of this specification, or that of Map Markup Language.

Patent Information

Development of this specification together with implementations is done under the terms of the W3C Software Notice and License, in accordance with the rules of the W3C Community Groups program

How to provide feedback

Please send comments on this specification to public-maps4html@w3.org. Even better: join the group and submit a pull request or open an issue.

Contents

  1. 1. Introduction
  2. 2. Conformance
  3. 3. Use Cases and Requirements
  4. 4. Features
  5. 5. Security Considerations
  6. 6. Glossary of Terms and Datatypes
  7. 7. Syntax
  8. 8. References

1. Introduction

This section is informative.

This specification describes a proposed enhancement to the map element syntax and processing model. The semantics of the existing standard map element allow an HTML author to create area elements over a standard HTML img, which then act as hyperlinks. The existing standard map element is a perfect extension point in HTML for modern Web maps, since it shares common (ancestor) abstract semantics (2D area on which authors can draw hyperlinks), which can be relied on as widely implemented and stable fallback markup processing by HTML authors targeting newer or future user agents which implement this proposal. This proposal to update the map element enhances the core functionality of the map element to include cartographic Web applications. The intention of this specification is to describe the map element independent of underlying implementation - whether that be native browser or custom elements. Details specific to how to author a Web page using the Custom Elements implementation can be found in the HTML Map Custom Element project.

2. Conformance

This section is normative.

Within this specification, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in RFC 2119 [RFC2119]. However, for readability, these words do not necessarily appear in uppercase in this specification.

3. Use Cases and Requirements

This section is informative.

3.1. Use Cases

The following use cases illustrate some of the ways in which the map element might be used in Web mapping applications:

3.2. Requirements

Implementation commitments:

The customized built-in map element was built and is maintained by the Maps for HTML Community Group.

Map Markup Language services are provided by Natural Resources Canada as part of the Canadian Geospatial Data Infrastructure.

The reader is requested to contact the editor with any known implementations of Map Markup Language or other implemented support for this proposal.

4. Features

The map element, in conjunction with any layer and area element descendants, defines an interactive map media element.

4.1 Web mapping elements and API

This section is normative.

4.1.1 The map element
Categories:
Flow content.
Phrasing content.
Palpable content.
Embedded content.
Interactive content.
Contexts in which this element can be used:
Where embedded content is expected.
Content model:
If lat, lon, and zoom are NOT present: Transparent; otherwise: Zero or more layer or area elements.
Content attributes:
Global attributes
zoom - a positive integer zoom (scale) value
lat - a decimal WGS84 latitude value for the map center
lon - a decimal WGS84 longitude value for the map center
projection - a case-sensitive string identifier of the MapML coordinate reference system used by the map. Default is 'OSMTILE'.
controls - Show user agent map controls
width - Horizontal dimension
height - Vertical dimension
Tag omission in text/html:
Neither tag is omissible
Allowed ARIA role attribute values:
application
Allowed ARIA state and property attributes:
Global aria-* attributes
DOM interface:
[NamedConstructor=Map(unsigned long width, unsigned long height, double lat, double lon, unsigned short zoom, optional string projection, boolean controls)]
interface HTMLMapElement : HTMLElement {
   readonly attribute HTMLCollection layers;
   readonly attribute HTMLCollection areas;
   readonly attribute unsigned short zoom;
   readonly attribute double lat;
   readonly attribute double lon;
   readonly attribute string projection;
   attribute boolean controls;
   attribute unsigned long width;
   attribute unsigned long height;
   void zoomTo(double latitude, double longitude, optional unsigned short zoom);
};

The map element, in conjunction with child layer and optionally area elements, allows authors to embed an interactive web mapping application in a rectangular area of a web page. The lat, lon attributes locate the initial center of the map. The zoom attribute indirectly identifies an initial scale of the map. After initialization, the lat,lon and zoom IDL properties reflect the location and scale of the map respectively, based on changes initiated by the user or by script.

map . areas

Returns an HTMLCollection of the area elements in the map.

map . layers

Returns an HTMLCollection of the layer element children of the map.

The areas attribute must return an HTMLCollection rooted at the map element, whose filter matches only area child elements.

The layers attribute must return an HTMLCollection rooted at the map node, whose filter matches only layer child elements of this map element.

The controls boolean attribute indicates whether default map controls should be displayed on the map. The nature and position of the controls is user agent implementation-defined. The controls can be added or removed by toggling the controls property of the element.

The projection attribute value identifies the coordinate system for the map and all the layer element children, with the exception of layer children in the WGS84 projection. WGS84 serves as a "wild-card" projection; features encoded in longitude, latitude values according to this projection can often be re-projected for use on maps encoded in other projections. As such, layer children do not have a projection attribute, in that they are verified to share the projection declared by their parent map element. Once established, the projection of the map is read-only.

The required width and height attributes of the map element allow the HTML author to explicitly set the size of the rectangular area devoted to the map. If the attributes are not set directly by the HTML author, their values must be established via CSS width and height properties or through script. In any case, these values must be established in order for the map to process and display its content. The map can be re-sized via changes to those properties.

The location and zoom level of the map created with the map element can be changed via the zoomTo(...) API method, which will change the zoom, lat and lon properties.

4.1.1.1 Projection identifiers

The following table summarizes the projection attribute values that are used by this specification. Unless otherwise specified, units are based on pixels projected and transformed from the units of the underlying projection system. The complete definition of these coordinate reference systems can be found in the Map Markup Language specification.

Projection value Description
OSMTILE Default value of projection if unspecified. Web Mercator-based (EPSG::3857) tiled coordinate reference system.
CBMTILE Lambert Conformal Conic-based tiled coordinate reference system for Canada, EPSG::3978.
APSTILE Alaska Polar Stereographic-based tiled coordinate reference system for the Arctic region, EPSG::5936.
WGS84 World Geodetic System 1984 EPSG::4326, units are based on longitude-latitude decimal degree coordinate pairs.
4.1.2 The layer element
Categories:
Flow content.
Phrasing content.
Palpable content.
Embedded content.
Interactive content.
Contexts in which this element can be used:
As a child of the map element
Content model:
If the src attribute is present: Empty. If no src attribute is present: Metadata content describing nested Map Markup Language content
Content attributes:
Global attributes
src - Address of the resource
label - String label for the layer in the layer control, if displayed
checked - Layer on/off status
disabled - Sets the disabled state of the layer in the layer control
hidden - Visibility status of the layer in the layer control
referrerpolicy - Referrer policy for fetches initiated by the element
crossorigin - A CORS settings attribute, specifies how the element handles crossorigin requests.
Tag omission in text/html:
Neither tag is omissible
Allowed ARIA role attribute values:
None
Allowed ARIA state and property attributes:
Global aria-* attributes
DOM interface:
interface HTMLLayerElement : HTMLElement {
   readonly attribute DOMString src;
            attribute DOMString label;
            attribute boolean checked;
   readonly attribute boolean disabled;
            attribute boolean hidden;
   readonly attribute LegendLink[] legendLinks;
            attribute DOMString referrerPolicy;
            attribute DOMString? crossOrigin;
};

interface LegendLink {
  readonly attribute DOMString type;
  readonly attribute DOMString rel;
  readonly attribute DOMString href;
  readonly attribute DOMString title;
  readonly attribute DOMString lang;
  readonly attribute DOMString hreflang;
  readonly attribute DOMString sizes;
};

The map element displays its child layer elements similarly to "acetate" layers on a (paper) map. The layers follow the painters model, whereby layer elements are displayed on top of earlier siblings according to their document order. layer transparency is controlled by the CSS opacity property.

In contrast to the HTML media elements' source child element where a single source element is selected by the user agent for play, the map element's child layer elements are visually combined with sibling layer elements and presented by the parent map element as a pan-able, zoom-able two-dimensional image. The display state (on / off) of the content represented by the layer element is controlled by the checked boolean attribute and corresponding property. If checked, the layer is drawn on the map in the sequence it is found in the parent element; if not checked the layer is not drawn but should remain visible in the map element's representation of controls in an "unchecked" state.

The src attribute value is the URL of a web resource encoded in Map Markup Language.

The hidden boolean attribute can be set to remove the layer from the map layer control, but it will remain displayed on the map. In order to remove the layer from the map display, it can be have its checked property toggled, or be removed from the DOM.

The disabled property is a read-only boolean indicator of the visibility of the layer on the map. If the layer is not visible due to errors, including projection, zoom or extent mismatch, the property will be true and if the layer is present in the layer control (i.e. hidden is false), it will be disabled in that control i.e. not checkable.

4.1.3 The area element
Categories:
Flow content.
Phrasing content.
Contexts in which this element can be used:
As a child of the map element
Content model:
Empty
Content attributes:
Global attributes
href - Address of the hyperlink
alt - User-visible label
coords - Coordinates for the shape to be created on the map
shape - The kind of shape to be created on the map
Tag omission in text/html:
Neither tag is omissible
Allowed ARIA role attribute values:
link role (default - do not set).
Allowed ARIA state and property attributes:
Global aria-* attributes
Any aria-* attributes applicable to the allowed roles.
DOM interface:
interface HTMLAreaElement : HTMLElement {
  attribute DOMString href;
  attribute DOMString alt;
  attribute DOMString coords;
  attribute DOMString shape;
};

The area element allows the HTML author to encode and style a limited set of spatial feature types on its parent map element, using familiar image map coordinates. Such features can be optionally designated as hyperlinks to be selected by the user.

If present, the href attribute identifies the designated coordinate area as a hyperlink. If no href attribute exists, the area is designated as a non-interactive area. The alt attribute specifies a label which can be used by the user agent for ephemeral and non-visual labelling of the area.

If the area element has no href attribute, then the area represented by the element cannot be selected, and the alt attribute must be omitted.

The coords attribute is a comma-separated list of integer coordinate values which delimit the geometry of the (area) feature. The shape attribute identifies the type of geometry which is encoded as coordinates in the coords attribute.

The shape attribute is an enumerated attribute. The following table lists the keywords defined for this attribute. The states given in the first cell of the rows with keywords give the states to which those keywords map.

StateKeywordsNotes
Circle state circle
Default state default
Polygon state poly
Rectangle state rect
Marker state marker new
Line state line new

The shape attribute may be omitted. The missing value default is the rectangle state.

The coords attribute must, if specified, contain a valid list of integers. This attribute gives the coordinates for the shape described by the shape attribute. The processing for this attribute is described as part of the image map processing model.

In the circle state, area elements must have a coords attribute present, with three integers, the last of which must be non-negative. The first integer must be the distance in CSS pixels from the left edge of the image to the center of the circle, the second integer must be the distance in CSS pixels from the top edge of the image to the center of the circle, and the third integer must be the radius of the circle, again in CSS pixels.

In the default state, area elements must not have a coords attribute. (The area is the whole area of the map on the page.)

In the polygon state, area elements must have a coords attribute with at least six integers, and the number of integers must be even. Each pair of integers must represent a coordinate given as the distances from the left and the top of the map in CSS pixels respectively, and all the coordinates together must represent the points of the polygon, in order.

In the rectangle state, area elements must have a coords attribute with exactly four integers, the first of which must be less than the third, and the second of which must be less than the fourth. The four values must represent, respectively, the distance from the left edge of the map to the left side of the rectangle, the distance from the top edge to the top side, the distance from the left edge to the right side, and the distance from the top edge to the bottom side, all in CSS pixels.

In the marker state, area elements must have a coords attribute with exactly two integers. The first integer must be the distance in CSS pixels from the left edge of the map to the top left corner of the marker, the second integer must be the distance in CSS pixels from the top edge of the map to the top left corner of the marker.

In the line state, area elements must have a coords attribute with at least four integers, and the number of integers must be even. Each pair of integers must represent a coordinate given as the distances from the left and the top of the map in CSS pixels respectively, and all the coordinates together must represent the points of the line, in order.

The intention of the area element is to extend the behavior of the existing HTML area element. For information pertaining to the processing of various link types created by the area element, please refer to the description of hyperlink processing for the HTML area element.

4.2 Web maps

4.2.1 Authoring

A Web map is an embedded media element which enables dynamic cartographic Web applications in HTML documents.

A Web map is a rectangular page area, represented in HTML in the form of a map element, containing a set of zero or more layer elements. A Web map represents a region of the earth's surface in two dimensions. A map's initial location (lat, lon), extent ( width and height) and scale (zoom) are defined by its attributes.

Consider a map of Paris:

Medium scale image of a street map of Paris, France

This map can be created with the following markup:

<map zoom="11" lat="48.85591" lon="2.3469543" width="640" height="300">
   <layer label="OpenStreetMap" src="https://example.com/mapml/osm/" checked crossorigin></layer>
</map>

A Web map can have zero or more layers. Map layers are drawn in document order of the layer elements, following the painters model. If the user (or author) enables more than one layer, all the layers will be painted, in document order. Features in layers drawn earlier will be painted over by later layers. Opacity of layers can be managed with CSS, if necessary.

Here is a map of Ottawa, with two layers:

Large scale image of a street map of part of Ottawa, Canada

This map can be created with the following markup:

   <style>
     .transparency {
       opacity: 0.2;
     }
   </style>
  <map zoom="15" lat="45.398043" lon="-75.70683" width="640" height="300" projection="CBMTILE">
    <layer label="Canada Base Map" src="https://example.com/mapml/cbmt/" checked crossorigin></layer>
    <layer label="CanVec+ 031G" src="https://example.com/mapml/canvec/50k/features/" crossorigin class="transparency"></layer>
  </map>

5. Security Considerations

This section is informative.

This technology relies on web resources loaded over the internet, which carries security implications. The architecture is not unlike allowing embedded images encoded in SVG format, and it is thought that similar security considerations apply. The author would be grateful if commenters could highlight such implications, so that they could be explicitly made part or the considerations of this draft.

6. Glossary of Terms and Datatypes

This section is normative.

Provide a glossary of terms and datatypes used in this specification.

7. Syntax

The map element has a different content model defined by this specification, compared to that defined by the HTML standard.

At such a moment as is warranted, the standard definition of the map and area elements will be merged into this specification, but it is probably confusing to merge the definitions at this point in time. The intention is, however, that the existing standard map element behaviour and markup can be used by authors as a widely supported fallback mechanism for non-compliant browsers as this specification is incrementally implemented by the platform browsers.

8. References

8.1. Normative References

[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels, S. Bradner, March 1997.
Available at https://tools.ietf.org/html/rfc2119.
[Map-Custom-Element]
map Custom Element project, Maps For HTML Community Group, August 2015.
Source code available at https://github.com/Maps4HTML/Web-Map-Custom-Element.
[Map Markup Language]
Map Markup Language, Maps For HTML Community Group, July 14, 2015.
Available at https://maps4html.github.io/MapML/spec/.
[RELAXNG]
Document Schema Definition Languages (DSDL) — Part 2: Regular grammar-based validation — RELAX NG, ISO/IEC FDIS 19757-2:2002(E), J. Clark, 村田 真 (Murata M.), eds. International Organization for Standardization, 12 December 2002.
Available at https://web.archive.org/web/20120619140335/http://www1.y12.doe.gov/capabilities/sgml/sc34/document/0362_files/relaxng-is.pdf.

8.2. Informative References

[WebIDL]
WebIDL, C. McCormack, ed. World Wide Web Consortium, work in progress, 19 December 2008.
This edition of WebIDL is https://www.w3.org/TR/2008/WD-WebIDL-20081219/.
The latest edition of WebIDL is available at https://www.w3.org/TR/WebIDL/.
[HTML]
HTML, Ian Hickson, Robin Berjon, Steve Faulkner, Travis Leithead, Erika Doyle Navara, Edward O'Connor, Silvia Pfeiffer, eds. HTML5 W3C Recommendation, 28 October 2014.
The latest edition of HTML is available at https://www.w3.org/TR/html5/