Skip to main content

<map-input>

The <map-input> element is an extended HTML input by type for use in Web map <map-extent> elements. The attributes that apply to the input depend on the type attribute. There are several types of <map-input> that can be used.

The <map-input> declares a variable that will be set and used by the polyfill according to its attributes, as the map changes viewport extent in response to user gestures.

Attributes​

name​

Sets the name of the variable created by the input. The variable can then be referenced by the URL template <map-link> tref attribute, using the {name} variable reference notation.


type​

Sets the type of the input.

TypeDescription
zoomInteger value that ranges from 0 to some fixed number of values, depending on the projection, less than or equal to 25.
locationA location input captures one axis value of a two-dimensional point ( represented by a coordinate pair) from the map extent, e.g. top-right, or, for server queries, the location in the map where the user clicks or touches.
widthA width input captures the width of the map viewport's extent in standardized pixels
heightA height input captures the height of the map viewport's extent in standardized pixels
hiddenEstablishes a variable that may be used to pass a fixed or fixed domain of values to the server when requesting map resources.

value​

In general, the value is set and used by the polyfill when generating URLs from URL templates, for fetching server resources such as tiles, images and map documents.

In particular, value is used by authors to specify values for inputs of type="zoom". In the case of type="zoom", value defines the zoom level of associated sibling <map-input type="location"> elements' min and max attribute values. Allows authors to establish native / server resource bounds, on a per-<map-link tref="..."> basis.

Inputs are associated by their variables being referenced by a <map-link tref="https://example.org/{z}/{col}/{row}/" ...> value. The {z}, {row}, and {col} variable references in the above example associate the variables (<map-input>'s) named z, row and col.


axis​

This attribute applies only to inputs of type="location". It establishes the axis of the coordinate to be serialized as a named variable. This value also identifies the axis that the min and max attributes apply to, so that the polyfill will not make requests for spatial resources (tiles etc) outside the native axis bounds. Possible values of axis are:

Axis nameCRSDescription
rowtilematrixVertical axis, positive down the screen. The origin is at the upper left. Units are tiles. Each zoom level is a distinct tilematrix crs, so coordinate values apply only to that zoom level.
columntilematrixHorizontal axis, positive to the right. The origin is at the upper left. Units are tiles. Each zoom level is a distinct tilematrix crs, so coordinate values apply only to that zoom level.
eastingpcrsHorizontal axis, positive to the right. The origin is defined a geographic location. Units are ususally meters, although for some projections (specifically WGS84), the transformation from geographic CRS, i.e. from longitude to easting is the identity transformation, in which case the easting values could be said to be in decimal degrees. pcrs stands for "projected coordinate reference system". Note that because pcrs is an 'infinite canvas', there exist locations for which a transformation from pcrs coordinates to gcrs coordinates is undefined.
northingpcrsVertical axis, positive to the right. The origin is defined a geographic location. Units are ususally meters, although for some projections (specifically WGS84), the transformation from geographic CRS, i.e. from latitude to northing is the identity transformation, in which case the northing values could be said to be decimal degrees. Note that because pcrs is an 'infinite canvas', there exist locations for which a transformation from pcrs coordinates to gcrs coordinates is undefined.
latitudegcrsThe latitude of a point on an ellipsoid is the angle between a line perpendicular to the surface of the ellipsoid at the given point and the plane of the equator. gcrs stands for "geographic coordinate reference system".
longitudegcrsThe longitude of a point specifies its east–west position on the reference body's (Earth's) surface.
xtcrsHorizontal axis, positive to the right. The origin is at the upper left. Units are defined-size pixels. Each zoom level is a distinct tcrs, so coordinate values apply only to that zoom level. tcrs stands for "tiled coordinate reference system". The tiles of each tilematrix crs are defined as aggregations of pixels in the corresponding zoom level tcrs.
ytcrsVertical axis, positive down the screen. The origin is at the upper left. Units are defined-size pixels. The origin is at the upper left. Units are scaled pixels. Each zoom level is a distinct tcrs, so coordinate values apply only to that zoom level.
itile, mapHorizontal axis, positive to the right. Each tile, and the map viewport, has a defined-size pixel-based crs that has its origin at the upper left (of each tile in the case of the tile crs, and of the map viewport, in the case of the map crs).
jtile, mapVertical axis, positive down the screen. Each individual tile, and the map viewport has a defined-size pixel-based crs that has its origin at the upper left (of each tile in the case of the tile crs, and of the map viewport, in the case of the map crs).

When requesting a the coordinate axis of whole tile in the OSMTILE projection, a location input might use a <map-input name="y" type="location" units="tilematrix" axis="row"> input to establish a variable named y, referenced by {y} in an associated URL template, which would serialize the tilematrix crs row axis values. A series of location events is genereated by the polyfill as required by the map to cover the viewport in tiles.


units​

Identifies the associated specific coordinate reference system that a location input event is referred to. The term "projection" in MapML is synonymous with the set of CRS that are related together by the projection name. In all cases for any projection, there exist a set of CRS that are related mathematically. These CRS are known and identified within the namespace of the projection name by the following table of keyword values:

CRSDescription
tcrsFor each zoom level (i.e. at a pre-defined scale denominator value), locations are expressed in terms of scaled pixels, with the origin of pixel space at the upper left corner. The pixel coordinates of a location at a single zoom level are independent of the pixel coordinates of a location any other zoom level. In other words, you need to know the zoom level of a tcrs coordinate in order to locate it on a map or otherwise process it.
tilematrixEach zoom level has an array of tiles, called a tilematrix. The individual tiles constitute the coordinates in this CRS, and the axes are know as row and column. The tiles are defined as squares of 256 pixels in the associated tcrs of the particular zoom level.
pcrsProjected CRS (pcrs) are defined by a mathematical relationship with an underlying gcrs, using a technique called "projection". pcrs coordinates are scale- and zoom level-independent, and are designed to represent geographic coordinates on a planar surface, such as a device screen. The measurement units of pcrs coordinates is usually meters (a notable exception being pcrs coordinates in the WGS84 projection).
gcrsGeographic coordinates are referenced to various ellipsoids, and are not necessarily comparable across projections. A common ellipsoid today is WGS 84, which is defined and used by the global positioning satellite (GPS) constellation.
mapThe map CRS is dynamic, in the sense that it has its origin at the upper left of the user's viewport, with scaled pixels as units. This is used to identify image coordinates for use, typically by WMS and similar services which use a virtual image to enable query of map feature property information, without necessarily transferring the features over the network.
tileEach tile in any zoom level has an implicit scaled-pixel coordinate system ranging from 0 to 255 in both horizontal and vertical directions. These coordinates are used by WMTS and similar services to identify a pixel for query of feature property values, without transferring the feature geometry over the network.

Sometimes, location inputs are used to generate "brownie-cutter" (square) requests for tiles from WMS and similar un-tiled services. In such a case, it is possible for the units to be specified as tilematrix, implying that the location event expected is that of a tile, and the position keyword is then used to describe the corner of the tile for which the coordinate should be serialized. In such a case, the axis value may be specified as easting or other axis name
associated with the projection, to obtain coordinate of the corner of the tile that is being processed by the polyfill:

<map-input name="xmin" type="location" units="tilematrix" position="top-left" axis="easting">

Internally, the crs of the requested coordinate is deduced from the axis name, instead of requiring the author to explicitly specify the axis' crs as an additional attribute of the <map-input>.


position​

Allows the author to specify a predefined corner of the viewport or tile to be used as the location value to be serialized. If position is not present, the input location coordinates will be generated by user click or touch on the map, which is used to generate interactive server queries.

position keywordkeyword description
top-leftIdentifies the location at the top left corner of the tile or viewport
top-rightIdentifies the location at the top right corner of the tile or viewport
bottom-leftIdentifies the location at the bottom left corner of the tile or viewport
bottom-rightIdentifies the location at the bottom right corner of the tile or viewport

Other values of position are possible, but are not implemented yet.


rel​

Specifies the entity to which the position applies. Possible values are tile and image. The default value, if unspecified, is image. It is used to help identify what crs the coordinate serialized by the input exists in.


min​

Establishes the minimum of the axis on the server . Requests for coordinates less than this value will not be created by the polyfill.


max​

Establishes the maximum of the axis on the server. Requests for coordinates greater than this value will not be created by the polyfill.


step​

Sets the zoom interval according to which resources will be requested within the zoom range. The step is always calculated from a base value of 0. At zoom values that fall within a step interval, resources will be requested as required, and scaled to the current zoom level. For example, with a min=0 and a max=7 for a given zoom input with a step=4, tiles will be requested at only zoom=0 and scaled to zoom values of 1, 2 and 3 as the map is rendered at those levels. Use of this attribute can conserve user bandwidth while having little visual effect, depending on the nature of the content.


shard​

The boolean shard attribute is used with a hidden variable.

A <map-input shard list="datalist-id> indicates that a set of values specified by an associated map-datalist element will be used in a round-robin fashion for template variable substitution and submission in map requests. This is useful for domain sharding, implemented by OpenStreetMap (for example), to increase parallelism of tile requests and thereby to improve performance.

When specifying a boolean attribute such as shard in MapML, care must be taken to encode the attribute according to the document / media type in which the element is being used. In XML documents, boolean attributes must be encoded as shard="anything", so as to respect XML parsing rules. In the HTML document, i.e. as inline layer content, the attribute should be encoded per HTML's boolean attribute rules.


list​

The <map-input list="..."> attribute associates a <map-datalist> element that provides the values to be used (via the <map-datalist>'s child <map-option> elements). See shard for more details.


Examples​

Input step​

<mapml-viewer projection="OSMTILE" zoom="0" lat="45.409071" lon="-75.703411" controls>
<layer- label="OpenStreetMap" checked>
<map-extent units="OSMTILE" >
<map-input name="z" type="zoom" value="18" min="0" max="18" step="3"></map-input>
<map-input name="s" type="hidden" shard="true" list="servers"></map-input>
<map-datalist id="servers">
<map-option value="a"></map-option>
<map-option value="b"></map-option>
<map-option value="c"></map-option>
</map-datalist>
<map-input name="x" type="location" units="tilematrix" axis="column" min="0" max="262144" ></map-input>
<map-input name="y" type="location" units="tilematrix" axis="row" min="0" max="262144" ></map-input>
<map-link rel="tile" tref="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png" />
</map-extent>
</layer->
</mapml-viewer>

Input rel=tile to generate WMS requests for tiles​

WMS behaviour can seem slow, even when it is fast. Painting the map using tiles generated by individual WMS GetMap requests can improve users' impression of your map, although it is not advisable when the layer being requested contains text labels, which may be duplicated on adjacent tiles many times over.

<mapml-viewer projection="CBMTILE" lat="60" lon="-95" zoom="2" controls>
<layer- label="Tiled WMS GetMap" checked>
<map-extent units="CBMTILE">
<!-- the units and axis attributes here appear at odds -->
<!-- however for rel="tile" and units="tilematrix" together tell the map that
the event being serialized is relative to a tile in a tilematrix coordinate
system (tcrs) -->
<map-input name="txmin" type="location" rel="tile" position="top-left" axis="easting" units="tilematrix" ></map-input>
<!-- in this case, position refers to a position on the tile that is to be fetched -->
<map-input name="tymin" type="location" rel="tile" position="bottom-left" axis="northing" units="tilematrix" ></map-input>
<map-input name="txmax" type="location" rel="tile" position="top-right" axis="easting" units="tilematrix" ></map-input>
<map-input name="tymax" type="location" rel="tile" position="top-left" axis="northing" units="tilematrix" ></map-input>
<map-link rel="tile" tref="https://datacube.services.geo.ca/ows/msi?SERVICE=WMS&REQUEST=GetMap&FORMAT=image/png&TRANSPARENT=TRUE&STYLES=msi-color&VERSION=1.3.0&LAYERS=msi&WIDTH=256&HEIGHT=256&CRS=EPSG:3978&BBOX={txmin},{tymin},{txmax},{tymax}" ></map-link>
<!-- a zoom input is necessary, but that's a bug:
https://github.com/Maps4HTML/Web-Map-Custom-Element/issues/669 -->
<map-input name="z" type="zoom" value="25" min="0" max="25"/>
</map-extent>
</layer->
</mapml-viewer>

Specifications​

Specification
MapML input element
HTML input element