Skip to main content

HTMLLayerElement

Properties​

checked​

HTMLLayerElement.checked is a boolean read/write value that turns the layer on and off, and reflects the checked attribute. The checked state is reflected in the layer control user interface for the layer via a checkbox next to the layer name. The checked property can be used to programatically change the checked state of the layer. The checked property can't be changed if the disabled property is set.

To set the checked state of a layer to on:

let layer = document.querySelector('map-layer');
layer.checked = true; // valid values are true | false

To read the checked state of the layer:

let layer = document.querySelector('map-layer');
let isChecked = layer.checked;

hidden​

HTMLLayerElement.hidden is a boolean read/write value that hides or unhides the layer in the layer control only. The hidden state has no bearing on the presence of layer content on the map, it only affects the layer presence layer control. This can be useful for managing short-lived layers, such as search results, to the map without forcing the user to manage the layer state, which is done by your application. It can also be useful for managing a permanent base layer without cluttering the user interface.

To set/update whether the layer is "hidden":

let layer = document.querySelector('map-layer');
layer.hidden = true; // valid values are true | false

To get the <map-layer>'s hidden value:

let layer = document.querySelector('map-layer');
let isHidden = layer.hidden;

disabled​

HTMLLayerElement.disabled provides READ-ONLY access to the disabled state of the layer. A layer becomes disabled if its contents are not rendered, either by being completely outside the current map extent or by having an error associated to the layer processing, such as being in a projection that is incompatible with the projection of the map. When a layer is disabled, the user can't interact with it in the layer control, and it will not be visible in the map viewport. If a layer becomes not-disabled, through manipulation of the map, for example, the layer will become interactable in the layer control, and should be visible in the map viewport.

label​

HTMLLayerElement.label reflects the label content attribute, and specifies a fallback accessible name for the layer, if the accessible name is not provided via a local <map-title> element child of the <map-layer> element, or in the <map-head> of a remote MapML document, loaded via the src URL value, respectively.

To set/update the <map-layer>'s label:

let layer = document.querySelector('map-layer');
layer.label = "New Title";

To get the <map-layer>'s label value:

let layer = document.querySelector('map-layer');
let label = layer.label;

src​

HTMLLayerElement.src reflects the src HTML attribute, and specifies the URL of the MapML document for the layer. The src property may be undefined if the layer contains inline content. If the src property returns a value, any inline content will be ignored. To set/update the <map-layer>'s src:

let layer = document.querySelector('map-layer');
layer.src = "https://example.org";

To get the <map-layer>'s src value (URL):

let layer = document.querySelector('map-layer');
let url = layer.src;

opacity​

HTMLLayerElement.opacity provides read/write access to the opacity value, and is reflected in the layer control for each layer, under "Opacity".

To set/update the <map-layer>'s opacity:

let layer = document.querySelector('map-layer');
layer.opacity = 0.5; // valid values from 0 to 1

To get the <map-layer>'s opacity value:

let layer = document.querySelector('map-layer');
let opacity = layer.opacity;

extent​

HTMLLayerElement.extent provides READ-ONLY access to the top left and bottom right coordinates of the layer's minimum bounding rectangle as an object value.

To get the <map-layer>'s extent value:

let layer = document.querySelector('map-layer');
let extent = layer.extent;

The extent object is structured as follows:

Click to view the extent object
{
    "projection": "CBMTILE",
    "topLeft": {
        "tcrs": [
            {
                "horizontal": 942.662039991251,
                "vertical": 1029.0945982508472
            },
/* an object with "horizontal" and "vertical" properties for each zoom level in the array */
            {
                "horizontal": 546743983.1949257,
                "vertical": 596874866.9854914
            }
        ],
        "tilematrix": [
            {
                "horizontal": 3.6822735937158244,
                "vertical": 4.019900774417372
            },
/* an object with "horizontal" and "vertical" properties for each zoom level in the array */
            {
                "horizontal": 2135718.6843551784,
                "vertical": 2331542.4491620758
            }
        ],
/* gcrs stands for "geographic coordinate reference system" */
        "gcrs": {
            "horizontal": -75.73195696514524,
            "vertical": 45.40761073808424
        },
/* pcrs stands for "projected coordinate reference system" */
        "pcrs": {
            "horizontal": 1509108.7182317898,
            "vertical": -170864.4342066869
        }
    },
    "bottomRight": {
        "tcrs": [
            {
                "horizontal": 942.7503158533199,
                "vertical": 1029.1828741129164
            },
            {
                "horizontal": 546795183.1949255,
                "vertical": 596926066.9854914
            }
        ],
        "tilematrix": [
            {
                "horizontal": 3.6826184213020308,
                "vertical": 4.0202456020035795
            },
            {
                "horizontal": 2135918.684355178,
                "vertical": 2331742.4491620758
            }
        ],
        "gcrs": {
            "horizontal": -75.67858731979081,
            "vertical": 45.387937810298354
        },
        "pcrs": {
            "horizontal": 1512495.3916717991,
            "vertical": -174251.10764670372
        }
    }
}

Methods​

zoomTo()​

HTMLLayerElement.zoomTo() Zoom to the layer's extent in the map, at the maximum zoom level in which the extent fits completely.

let layer = document.querySelector('map-layer');
layer.zoomTo();

mapml2geojson(options)​

HTMLLayerElement.mapml2geojson(options) returns the layer in GeoJSON format.

FunctionReturnsDescription
mapml2geojson(<Object> options)A JavaScript (GeoJSON) feature collection objectThis function transforms the <feature> element children of a <map-layer> element to a GeoJSON FeatureCollection object. You supply options to control the transformation. This function must be used inside a windows.onload event.
caution

mapml2geojson must be called inside a windows.onload event to work properly. i.e.

window.onload = (event) => {
  let layer = document.querySelector('map-layer');
  layer.mapml2geojson();
};

Parameters​

ParameterDescription
<Object> optionsOptional. You supply parameters via an options object with predefined option names.

Options​

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

OptionTypeDefaultDescription
propertyFunction<Function>n/aA function you supply that maps the features' <map-properties> element to a GeoJSON "properties" member, since only you know the markup design in your <map-properties> value. If you don't supply this option, a default function will attempt to reverse a <table> child of the <map-properties> element, as if that table was generated by the default properties option function from geojson2mapml.
transform<Boolean>trueTransform <map-coordinates> values to gcrs (longitude,latitude) values, if they are not already so. GeoJSON recommends using WGS 84 longitude,latitude coordinates, so this is the default behaviour.
Notes​

mapml2geojson, by default, will transform coordinates to gcrs before serialization, if necessary. Note that all geographic CRS are not equivalent, and the interpretation of such coordinates is not guaranteed to conform to WGS 84 / GPS coordinates, and therefore may not conform to the GeoJSON recommendation, which requires longitude,latitude coordinates that are encoded as WGS 84. The projection engine used to implement this conversion is not capable of transforming coordinates from one ellipsoid to another, and so the resulting JSON SHOULD (somehow, tbd) be tagged with the datum in use by the projection of the layer.

Events​

Event nameDescription
changestyleFired before the layer changes src due to user selecting alternate style in layer control
changeprojectionFired before the layer changes projection due to its declared projection being not equal to that of the map
loadedmetadataFired when the metadata for a layer has loaded. The intent is that this event is analagous to the media element loadedmetadata event, but for map layers.
map-changeFired when the layer is checked or unchecked through the layer menu (by clicking or using the keyboard)

Examples​

mapml2geojson​

Default options​

An example showcasing default GeoJSON output when no options are provided.

<map-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>
</map-layer>
<script>
window.onload = (event) => {
   let layer = document.querySelector('map-layer');
   let output = layer.mapml2geojson();
};
</script>
Click to view the output GeoJSON
{
 "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"
     }
 }]
}

Specifications​

Specification
HTMLLayerElement

Requirements​

Report problems with these requirements on GitHub

requirement enhancement impractical undecided under discussion

SpecViewerAPI
Propertiesfullfullfull
Methodsfullfullfull