Skip to main content

<mapml-viewer>

The <mapml-viewer> element is the main element you can use to put a custom Web map on your page. To create a (really) simple Web map, you might use it like this:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>A Simple Web Map[tm]</title>
  <script type="module" src="web-map/mapml.js"></script>
  <style>
    html, body {
    height: 100%; /* These styles are required if you wish to use a % based
                     height value on the mapml-viewer element. */
    }
  </style>
</head>
<body>
  <mapml-viewer projection="OSMTILE" zoom="0" lat="0.0" lon="0.0" controls>
    <map-layer label="OpenStreetMap" src="https://geogratis.gc.ca/mapml/en/osmtile/osm/" checked></map-layer>
  </mapml-viewer>
</body>
</html>

Note that for the above example to run properly on your own site, you need to get a built copy of the <mapml-viewer> project in your site's folder. In the example, the <mapml-viewer> files are copied into the folder named "web-map" in your site root folder. Your own site's path to these files will depend on how you structure your folders.

<mapml-viewer> is an "autonomous custom element" in HTML. You can distinguish an autonomous custom element from a "native" HTML element by the "-" anywhere in the element name. Autonomous custom elements are supported by all modern browsers, but don't work in old browsers (e.g. Internet Explorer and old Edge).

The <mapml-viewer> element has several attributes to control the presentation and initial location of the map.

Attributes​

projection​

projection - an enumerated attribute. Case-sensitive values are: "OSMTILE", "WGS84", "CBMTILE" and "APSTILE".
The default projection is OSMTILE.

  • OSMTILE corresponds to the widely-used "Web Mercator" projected coordinate reference system, implying a "tile pyramid" zoom range from 0 to 23 (minimum tile size ~2.4m).

  • WGS84 provides an implementation of the "pseudo plate carrée" projected coordinate reference system, wherein the easting and northing axis units are decimal degrees (not meters). In WGS84, zoom level 0 contains two tiles that each cover a hemisphere of Earth's surface. WGS84 is defined with 21 zoom levels (0 to 20).

  • CBMTILE is the de facto standard grid layout for the Canadian Geospatial Data Infrastructure (CGDI), defined by Natural Resources Canada, and is based on the Lambert Conformal Conic projection (EPSG:3978). Zoom levels are based on a numeric map scale denominator (e.g. 10000 corresponding to a map scale of 1:10,000), with a particular pixel resolution selected, and as a result, successive zoom levels' tiles do not nest exactly (as they do in OSMTILE, WGS84 and APSTILE).

  • APSTILE is based on the Alaska Polar Stereographic (EPSG:5936) projected coordinate reference system, and has 20 zoom levels (0 to 19).

  • other projections are possible, using the Custom Projections API.

zoom​

zoom - a non-negative integer. The value establishes the initial zoom level of the map, and is required. The value is updated when the map stops moving. For a smaller scale view of the world, use a lower value. Use larger values for larger scales (smaller area maps). The maximum value depends on the particular projection and data source. Many map data sources have limited zoom levels available.

lat​

lat - a real number latitude. The value establishes the initial latitude of the of the center of the map, and is required. The value is updated when the map stops moving. Latitudes on Earth range from -90.0 (south) to 90.0 (north). Many projections are not able to display all latitudes, and most projections have a limited range of locations where distortion is controlled or limited. In particular, OSMTILE (Web Mercator) can only display content between the latitude range -84 to 84.

lon​

lon - a real number longitude. The value establishes the initial longitude of the of the center of the map, and is required. The value is updated when the map stops moving. Longitudes on Earth range from -180.0 (west) to 180.0 (east). Similar comments related to distortion apply to those for latitude. Be careful, this attribute is named "lon" NOT "long", and if you use "long" your map won't work properly.

controls​

controls - a "boolean" attribute. Turns map controls on (if present) or off (if omitted). In HTML "boolean" attributes don't have values of "true" or "false" per se - they have the implied value of "true" if the attribute exists, and an implied value of "false" if the attribute is not present. Sometimes the default map controls may not be useful for your map, so you may turn them off and design your own.

controlslist​

controlslist - an enumerated attribute, possible values are: "nofullscreen", "nolayer", "noreload", "noscale" and "nozoom". Occasionally, you may not want your users to have access to a particular control, so you may prune the set of controls automatically presented (when you have used the controls boolean attribute).

height​

height - the height of the map, in pixels. Must be an integer without a unit.

width​

width - the width of the map, in pixels. Must be an integer without a unit.

static​

static - a "boolean" attribute. It disables the keyboard interaction, and the zooming and dragging features with the map when it is present. When it is not present or removed, these features are enabled again.

Specifications​

Specification
MapML map element
HTML map element

Requirements​

Report problems with these requirements on GitHub

requirement enhancement impractical undecided under discussion

SpecViewerAPI
Rendering base layers (5.1)
Embed an interactive map viewer, using HTML markup (5.1.1)
fullfullfull
Generate a default map for a given area (5.1.2)
Not PlannedNot PlannedNot Planned
Display a basic map without JavaScript (5.1.5)
fulllimited
Display map content in a users preferred language (5.1.6)
fullfull
Interpreting locations and map positions (5.3)
Select map view from latitude and longitude point (5.3.1)
fullfullfull
Display map tiles defined in various common coordinate systems (5.3.3)
fullfullfull
Reproject map tile data into a new projection or globe view (5.3.4)
under discussionnone
Save the location or export to other application (5.3.5)
limitedlimited
User navigation (pan and zoom) (5.4)
Zoom the map independently from the rest of the page (5.4.1)
fullfull
Pan the map display (5.4.2)
fullfull
Wrap/duplicate data tiles when panning around the globe (5.4.4)
nonepartial
Custom styling (5.5)
Apply custom styling to map controls (5.5.2)
nonenone
Toggle whether default controls are displayed (5.5.3)
fullfull
Controlling the displayed map view and responding to user actions (6.2)
Subscribe to notifications of map events (6.2.3)
pendinglimitedfull
Move the map to display a given location (6.2.5)
fullfull