Skip to main content

HTMLMapmlViewerElement

The HTMLMapmlViewerElement interface represents the <mapml-viewer> element.

Properties​

Property nameDescription
controlsTurns native map controls on or off. Reflects the controls attribute.
controlslistAllows to change the set of native controls. Reflects the controlslist attribute.
extentReturns the extent of the current map view. Read only.
latGet the map's latitude. Reflects the lat attribute. Read only.
lonGet the map's longitude. Reflects the lon attribute. Read only.
projectionThe map's projection. Reflects the projection attribute.
zoomThe map's zoom level. Reflects the zoom attribute.

controls​

To add controls to the map:

let map = document.querySelector('mapml-viewer');
map.controls = true; // or false to remove controls

To check whether the map has controls toggled on or off:

let map = document.querySelector('mapml-viewer');
let controlsAdded = map.controls;

controlslist​

To set the controlslist attribute:

let map = document.querySelector('mapml-viewer');
map.controlslist = "noreload"; // values can be noreload | nofullscreen | nozoom | nolayer

To get the value of the controlslist:

let map = document.querySelector('mapml-viewer');
let controlsList = map.controlslist;

extent​

To get the map's extent:

let map = document.querySelector('mapml-viewer');
let extent = map.extent;
View Sample Extent
/**
*extent = 
*  {
*    {
*      "topLeft": {
*        "tcrs": [
*          {
*            "horizontal": 906.7586206896551,
*            "vertical": 981.7241379310345
*          },
*          ...
*        ],
*        "tilematrix": [
*          {
*            "horizontal": 3.5420258620689653,
*            "vertical": 3.8348599137931036
*          },
*          ...
*        ],
*        "gcrs": {
*          "horizontal": -93.05456518322721,
*          "vertical": 63.783997873304855
*        },
*        "pcrs": {
*          "horizontal": 131686.24163915217,
*          "vertical": 1646487.1729743406
*        }
*      },
*      "bottomRight": {
*        "tcrs": [
*          {
*            "horizontal": 914.9655172413793,
*            "vertical": 1015.5172413793102
*          },
*          ...
*        ],
*        "tilematrix": [
*          {
*            "horizontal": 3.574084051724138,
*            "vertical": 3.9668642241379306
*          },
*          ...
*        ],
*        "gcrs": {
*          "horizontal": -85.62509797700041,
*          "vertical": 52.14641630380798
*        },
*        "pcrs": {
*          "horizontal": 446541.0380154103,
*          "vertical": 350026.2467191592
*        }
*      },
*      "projection": "CBMTILE",
*      "zoom": {
*        "minZoom": 0,
*        "maxZoom": 25
*      }
*    }
*  }
*/

lat​

To set the latitude:

caution

Needs to be implemented, currently doesn't pan the map on changes

let map = document.querySelector('mapml-viewer');
map.lat = 21.4; // if it's an invalid value, nothing happens

To get the latitude:

let map = document.querySelector('mapml-viewer');
let latitude = map.lat;

lon​

To set the longitude:

caution

Needs to be implemented, currently doesn't pan the map on changes

let map = document.querySelector('mapml-viewer');
map.lon = 21.4; // if it's an invalid value, nothing happens

To get the longitude:

let map = document.querySelector('mapml-viewer');
let longitude = map.lon;

projection​

To set/update the projection:

let map = document.querySelector('mapml-viewer');
map.projection = "CBMTILE"; // if it's an invalid/undefined projection, nothing happens

To get the projection:

let map = document.querySelector('mapml-viewer');
let projection = map.projection;

zoom​

To set the zoom:

caution

Needs to be implemented, currently doesn't zoom the map on changes

let map = document.querySelector('mapml-viewer');
map.zoom = 3; // if it's an invalid value, nothing happens

To get the longitude:

let map = document.querySelector('mapml-viewer');
let zoom = map.zoom;

Methods​

MethodDescription
back()Navigates back one state in the map's movement history.
forward()Navigates forward in the map's panning history.
reload()Clear the map's panning history and return to the starting location.
toggleDebug()Toggle the debug functionality of the map.
viewSource()View the source of the map.
defineCustomProjection()Define a custom projection for use by the page.
zoomTo(lat, lon, zoom)Fly or pan the map to a (new) location and zoom level.
geojson2mapml(json, options)Add a GeoJSON Layer to the map.

back()​

To go back in the map's history:

let map = document.querySelector('mapml-viewer');
map.back();

forward()​

To go forward in the map's history:

let map = document.querySelector('mapml-viewer');
map.forward();

reload()​

To clear the map's history and return to the initial location:

let map = document.querySelector('mapml-viewer');
map.reload();

toggleDebug()​

To toggle the map's debug mode:

let map = document.querySelector('mapml-viewer');
map.toggleDebug();

viewSource()​

To view the map's view source:

let map = document.querySelector('mapml-viewer');
map.viewSource();

zoomTo(lat, lon, zoom)​

To change the map's center location and zoom level:

var options = {
  enableHighAccuracy: true,
  timeout: 5000,
  maximumAge: 0
};

function success(pos) {
  var crd = pos.coords;

  let map = document.querySelector('mapml-viewer');
  map.zoomTo(crd.latitude,crd.longitude, 17); // hard-coded zoom
  // could calculate a zoom based on accuracy of position
  console.log(`More or less ${crd.accuracy} meters.`);
}

function error(err) {
  console.warn(`ERROR(${err.code}): ${err.message}`);
}

navigator.geolocation.getCurrentPosition(success, error, options);

geojson2mapml(json, options)​

Convert a GeoJSON feature or feature collection string or object to MapML <layer-> containing one or more <map-feature> elements. Returns and adds the converted layer element to the map.

tip

Check out this application using the geojson2mapml API!

Parameters​

ParameterDescription
<String | Object> jsonA GeoJSON string or object.
<Object> optionsOptional. A set of key/value pairs that customize the output MapML layer. All options are optional and described below.

Options​

<Object> A set of key/value pairs that customize the output MapML layer. All options are optional and detailed below.

OptionTypeDefaultDescription
label<String>json.name, json.title or "Layer"Sets the output layer's label.
projection<String>map.projection or OSMTILESets the output layer's projection. Defined values include: OSMTILE, CBMTILE, WGS84, and APSTILE.
caption<String | Function>json.features[i].id or the label valueA function that accepts the feature JSON and returns a string, OR a string that is the name of a property to be mapped to the featurecaption. If a matching property is not found, the string provided will be used as the feature caption value. See basic options usage for an example.
properties<Function | String | HTMLElement>Properties will be mapped to an HTML table.Specifies how the properties are mapped. <Function> - A function that accepts one argument - the GeoJSON feature object - and which must return an HTMLElement that becomes the single child element of the <properties> element. <String> - A string that will be parsed and used as the single child element of the <properties> element for all features. <HTMLElement> - an element that will be used as the single child element of <properties> element for all features. See basic options usage for an example.
geometryFunction<Function>MapML geometry will mirror the GeoJSON geometry value<Function> A function to modify the generated descendants of <map-geometry> which can add classes, hyperlinks and span's to the instance. Plain <map-geometry> element will be created by default. The function accepts two arguments: The generated child element of <map-geometry> and the feature json object to return a modified child element of the <map-geometry> element. See basic options usage for an example.

Events​

Event nameDescription
layerchangeFired when a layer changes src, usually by the user following a link.
loadFired when all layers have finished loading content
clickFired when the map receives both mousedown and mouseup events
dblclickFired when the user double clicks or taps the map
mousemoveFired repeatedly as the mouse cursor traverses the map
mouseoverFired once as the mouse cursor enters the map
mouseoutFired once as the mouse cursor exits the map
mousedownFired when the mouse's primary key is pressed down with cursor over the map
mouseupFired when the mouse's primary key is released with cursor over the map
movestartFired before the map starts to move / viewport changes
moveFired repeatedly as the map moves.
moveendFired after the map stops moving
zoomstartFired before the map changes zoom level
zoomFired repeatedly as the map changes zoom
zoomendFired after the map has changed zoom level
preclickFired before a click on the map is triggered. May not be a primitive.
contextmenuFired when user right-clicks or long presses on map. May not be a primitive.

Examples​

geojson2mapml​

Basic options usage​

Showcasing how use each option.

geojson2mapml label option
geojson2mapml(json, {label: "Downtown Ottawa"});

Options string​

An example showcasing how strings can be used to set label, projection, caption and properties options.

let map = document.querySelector('mapml-viewer');
let json = {
    "name": "Default Name",
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [-75.6916809,45.4186964]
    },
    "properties": {"desc": "This is a Point"}
};

// GeoJSON To MapML
let output = map.geojson2mapml(json, {label: "Example 1", projection: "CBMTILE", caption: "desc", properties: "<h3>This is a property heading</h3>"});
Click to view the output HTMLElement
<layer- label="Example 1" checked="">
   <map-meta name="projection" content="CBMTILE"></map-meta>
   <map-meta name="cs" content="gcrs"></map-meta>
   <map-feature>
      <map-featurecaption>This is a Point</map-featurecaption>
      <map-geometry>
         <map-point>
            <map-coordinates>-75.6916809 45.4186964</map-coordinates>
         </map-point>
      </map-geometry>
      <map-properties>
         <h3>This is a property heading</h3>
      </map-properties>
   </map-feature>
</layer->

Options function​

An example showcasing how functions can be used to set caption and properties options.

let map = document.querySelector('mapml-viewer');
let json = {
    "name": "Default Name",
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [-75.6916809,45.4186964]
    },
    "properties": {"desc": "This is a Point"}
};

// function to set caption
let cap = function c(j) {
  let str = "This point is located at: (" + j.geometry.coordinates[0] + ", " + j.geometry.coordinates[1] + ").";
  return str;
}

// function to set properties
let prop = function f(p) {
  let parser = new DOMParser();
  return parser.parseFromString("<h1>" + p.properties.desc + "'s property</h1>", "text/html").body.firstChild;
}

// GeoJSON To MapML
let output = map.geojson2mapml(json, {label: "Example 2", caption: cap, properties: prop});
Click to view the output HTMLElement
<layer- label="Example 2" checked="">
   <map-meta name="projection" content="OSMTILE"></map-meta>
   <map-meta name="cs" content="gcrs"></map-meta>
   <map-feature>
      <map-featurecaption>This point is located at: (-75.6916809, 45.4186964).</map-featurecaption>
      <map-geometry>
         <map-point>
            <map-coordinates>-75.6916809 45.4186964</map-coordinates>
         </map-point>
      </map-geometry>
      <map-properties>
         <h1>This is a Point's property</h1>
      </map-properties>
   </map-feature>
</layer->

Default options​

An example showcasing default output when no options are provided.

let map = document.querySelector('mapml-viewer');
let json = {
 "title": "Point Geometry",
 "bbox": [-75.916809, 45.886964, -75.516809, 45.26964],
 "type": "FeatureCollection",
 "features": [{
     "type": "Feature",
     "geometry": {
         "type": "Point",
         "coordinates": [-75.6916809, 45.4186964]
     },
     "properties": {
         "prop0": "This is a Point"
     }
 }]
};

// GeoJSON To MapML
let output = map.geojson2mapml(json);
Click to view the output HTMLElement
<layer- label="Point Geometry" checked="">
   <map-meta name="extent" content="top-left-longitude=-75.916809, top-left-latitude=45.886964, bottom-right-longitude=-75.516809,bottom-right-latitude=45.26964"></map-meta>
   <map-meta name="projection" content="OSMTILE"></map-meta>
   <map-meta name="cs" content="gcrs"></map-meta>
   <map-feature>
      <map-featurecaption>Point Geometry</map-featurecaption>
      <map-geometry>
         <map-point>
            <map-coordinates>-75.6916809 45.4186964</map-coordinates>
         </map-point>
      </map-geometry>
      <map-properties>
         <table>
            <thead>
               <tr>
                  <th role="columnheader" scope="col">Property name</th>
                  <th role="columnheader" scope="col">Property value</th>
               </tr>
            </thead>
            <tbody>
               <tr>
                  <th scope="row">prop0</th>
                  <td itemprop="prop0">This is a Point</td>
               </tr>
            </tbody>
         </table>
      </map-properties>
   </map-feature>
</layer->