The <web-map> HTML Element proposal

This version:
https://maps4html.github.io/HTML-Map-Element/spec/2015/
Latest version:
https://maps4html.github.io/HTML-Map-Element/spec/
Previous version:
n/a
Editors:
Peter Rushforth, Natural Resources Canada
Authors:
Maps for HTML Community Group.

This document is licensed under a W3C Software and Document License..

Abstract

The standard HTML <map> element allows the HTML author to designate sub-areas of an image to be used as hyperlinks, creating an "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 equally simple and declarative for an HTML author to include on their Web page. This specification proposes the syntax and semantics of such an 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 <web-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 is a sibling to another related specification proposal, that of Map Markup Language [MapML].

Status of This Document

This specification is a work in progress. As updates to the HTML Map Custom Type Extension Element prototype 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 <web-map> element.

Implementation Experience

A Custom Type Extension Element has been developed which implements this specification using the MapML-Leaflet-Client, Leaflet and Polymer JavaScript libraries.

Changes Since the Previous Draft

n/a

Level of Endorsement by the Community

Please join the W3C Maps for HTML Community Group if you would like to participate in the development and implementation of this specification.

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
  9. 9. Acknowledgments

1. Introduction

This section is informative.

This specification introduces the proposed <web-map> element for HTML. The semantics of the standard <map> element allow the HTML author to create areas over a static HTML image which act as hyperlinks. The <web-map> element standardizes the core functionality of cartographic Web applications. The intention of this specification is to describe the <web-map> element independent of underlying technology - whether that be native browser or Web Components. Details specific to how to author a Web page using the Polymer Custom Element implementation can be found in the HTML Web Map Custom Element project

2. Conformance

This section is normative.

This document contains explicit conformance criteria that overlap with some RNG definitions in requirements. If there is any conflict between the two, the explicit conformance criteria are the definitive reference.

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 <web-map> element might be used in Web mapping applications:

3.2. Requirements

Implementation commitments:

The web-map Custom Element implementation has access to and uses the facilities provided by browsers (for example SVG support) to simulate the behavior of a potential native implementation, and to the extent that those facilities work similarly / are standard across browser implementations, the web-map Custom Element is functional. However, as the web-map Custom Element implementation is intended to provide a proof of concept, efforts to polyfill browser-provided facilities such as SVG have not been made to date. It is unclear whether such effort would be worthwhile.

Ease of authoring:

The <web-map> element is primarily intended to simplify the authoring of dynamic Web maps, eliminating the hard requirement for script or allowing progressive enhancement of the element with script. Additionally, the use of declarative markup enables the use of standard CSS techniques for cartographic and other user experience criteria.

4. Features

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

4.1 Web mapping elements and API

This section is normative.

4.1.1 The web-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:
Zero or more map-layer 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 string identifier of the MapML coordinate reference system used by the map. Default is 'OSMTILE'.
controls - Show user agent 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=WebMap(unsigned long width, unsigned long height, double lat, double lon, unsigned short zoom, optional string projection, boolean controls)]
interface HTMLWebMapElement : 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 web-map element, in conjunction with child map-layer and optionally map-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.

web-map . areas

Returns an HTMLCollection of the map-area elements in the web-map.

web-map . layers

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

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

The layers attribute must return an HTMLCollection rooted at the web-map node, whose filter matches only map-layer child elements of this web-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 subject to user agent implementation. 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 map-layer element children, with the exception of map-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, map-layer children do not have a projection attribute, in that they are verified to share the projection declared by their parent web-map element. Once established, the projection of the web-map is read-only.

The required width and height attributes of the web-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, their values can be set via CSS width and height properties. The map can be re-sized via changes to those properties.

The location and zoom level of the map created with the web-map element can be changed via the zoomTo() API method.

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 map-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 web-map element
Content model:
Empty
Content attributes:
Global attributes
src - Address of the resource
label - User-visible label
checked - Layer on/off status
hidden - Visibility status of the layer in the layer control
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 HTMLMapLayerElement : HTMLElement {
   readonly attribute DOMString src;
            attribute DOMString label;
            attribute boolean checked;
   readonly attribute boolean disabled;
            attribute boolean hidden;
   readonly attribute LegendLink[] legendLinks;
};

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

Unlike the HTML media elements' source child element where a single source element is selected by the user agent for play, the map-layer element can be combined with sibling map-layer elements via the map presented by the parent web-map element. The display of the map-layer is controlled by the checked boolean attribute. If checked, the map-layer is drawn on the map in the sequence it is found in the parent element.

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 map-layer from the map layer control, but it will remain displayed on the map. In order to remove the map-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 for reasons including projection, zoom or extent mismatch, the property will be true and if present in the layer control, it will be disabled in that control i.e. not checkable.

4.1.3 The map-area element
Categories:
Flow content.
Phrasing content.
Contexts in which this element can be used:
As a child of the web-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 HTMLMapAreaElement : HTMLElement {
  attribute DOMString href;
  attribute DOMString alt;
  attribute DOMString coords;
  attribute boolean shape;
};

The map-area element allows the HTML author to encode and style a limited set of spatial feature types on its parent web-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 map-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, map-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, map-area elements must not have a coords attribute. (The area is the whole area of the map on the page.)

In the polygon state, map-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, map-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, map-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, map-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 map-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 <web-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:

Paris

This map can be created with the following markup:

<web-map zoom="11" lat="48.85591" lon="2.3469543" width="640" height="300">
   <map-layer label="Open Street Map" src="http://example.com/mapml/osm/" checked></map-layer>
</web-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:

This map can be created with the following markup:

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

5. Security Considerations

This section is informative.

Provide security considerations for the implementation and authoring of this technology here.

6. Glossary of Terms and Datatypes

This section is normative.

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

7. Syntax

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

8. References

8.1. Normative References

[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels, S. Bradner, March 1997.
Available at http://tools.ietf.org/html/rfc2119.
[Web-Map-Custom-Element]
web-map Custom Element project, Maps For HTML Community Group, August 2015.
Available at https://github.com/Maps4HTML/Web-Map-Custom-Element.
[MapML]
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 http://www.y12.doe.gov/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 http://www.w3.org/TR/2008/WD-WebIDL-20081219/.
The latest edition of WebIDL is available at http://dev.w3.org/2006/webapi/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 http://www.w3.org/TR/html5/

10. Acknowledgments

The editors would like to acknowledge and thank the following people for substantive aid with this specification: list of names.