Skip to content

Document new search control #174

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
prushforth merged 1 commit into from
May 27, 2026
Merged

Document new search control #174

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 97 additions & 6 deletions docs/api/mapml-viewer-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,13 @@ The HTMLMapmlViewerElement interface represents the `<mapml-viewer>` element.

| Property name | Description |
|-------------- |-------------------------------------------------------- |
| [controls](#controls) | Turns native map controls on or off. Reflects the controls attribute. |
| [controlsList](#controlslist) | Allows to change the set of native controls. Reflects the controlslist attribute. |
| [controls](#controls) | Turns native map controls on or off. Reflects the `controls` attribute. |
| [controlsList](#controlslist) | Allows to change the set of native controls with script. Note use of camelCase of the property name vs lowercase attribute name. Reflects the `controlslist` attribute. |
| [extent](#extent) | Returns the extent of the current map view. Read only. |
| [lat](#lat) | Get or set the map's latitude. Reflects to the lat content attribute. No effect on map dynamic state. |
| [lon](#lon) | Get or set the map's longitude. Reflects to the lon content attribute. No effect on map dynamic state. |
| [projection](#projection) | The map's projection. Reflects the projection attribute. |
| [zoom](#zoom) | Get or set the map's zoom level. Reflects to the zoom content attribute. No effect on map dynamic state. |
| [projection](#projection) | The map's projection. Reflects the `projection` attribute. |
| [zoom](#zoom) | Get or set the map's zoom level. Reflects to the `zoom` content attribute. No effect on map dynamic state. |

### controls

Expand All @@ -45,8 +45,10 @@ that helps the user select what controls to display on the `mapml-viewer` elemen
To set the controlslist attribute:
```js
let map = document.querySelector('mapml-viewer');
map.controlsList.value = "noreload nozoom"; // values can be noreload | nofullscreen | nozoom | nolayer
map.controlsList.value = "noreload nozoom"; // values can be noreload | nofullscreen | nozoom | nolayer | search | geolocation
map.controlsList.add("nofullscreen"); // can also add using the 'add' method
map.controlsList.add("geolocation"); // adds the locate control
map.controlsList.add("search"); // adds the search control, disabled until a search URL template link is defined
map.controlsList.toggle("nolayer"); // can also toggle using the 'toggle' method
// view all methods here - https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList
```
Expand Down Expand Up @@ -221,7 +223,8 @@ let zoom = map.zoom;
| [viewSource()](#viewsource) | View the source of the map. |
| [defineCustomProjection(options)](#definecustomprojectionoptions) | Define a custom projection for use by the page. |
| [zoomTo(lat, lon, zoom)](#zoomtolat-lon-zoom) | Fly or pan the map to a (new) location and zoom level.|
| [geojson2mapml(json, options)](#zoomtolat-lon-zoom) | Add a GeoJSON Layer to the map. |
| [zoomToExtent(west, south, east, north)](#zoomtoextentwest-south-east-north) | Fit the map view to a geographic extent. |
| [geojson2mapml(json, options)](#geojson2mapml) | Add a GeoJSON Layer to the map. |
| [matchMedia(mediaQueryString)](#matchmediamediaquerystring) | Returns a [MediaQueryList](https://developer.mozilla.org/en-US/docs/Web/API/MediaQueryList)-like object.


Expand Down Expand Up @@ -328,6 +331,19 @@ navigator.geolocation.getCurrentPosition(success, error, options);

---

### zoomToExtent(west, south, east, north)

Fit the map view to the geographic extent defined by the four coordinate values,
automatically choosing the appropriate maximum zoom level.

```js
let map = document.querySelector('mapml-viewer');
// Fit the map to show southern Ontario
map.zoomToExtent(-80, 43, -70, 48);
```

---

### geojson2mapml(json, options)

Convert a GeoJSON feature or feature collection string or object to MapML [`<map-layer>`](/web-map-doc/docs/elements/layer/) containing one or more [`<map-feature>`](/web-map-doc/docs/elements/feature/) elements. Returns and adds the converted layer element to the map.
Expand Down Expand Up @@ -406,6 +422,79 @@ state of the queried map properties (projection, zoom, extent); any change to th
| zoomend | Fired after the map has changed zoom level |
| preclick | Fired before a click on the map is triggered. May not be a primitive. |
| contextmenu | Fired when user right-clicks or long presses on map. May not be a primitive.|
| [mapsearch](#mapsearch) | Fired after search responses arrive from all search-enabled layers. |
| [mapsuggestions](#mapsuggestions) | Fired after typeahead suggestion responses arrive from all search-enabled layers. |

### mapsearch

Fired on the `<mapml-viewer>` element after search responses have been received
from all checked layers that contain a
[`<map-link rel="search">`](../elements/link/#rel). Triggered when the user
presses **Enter** in the search input **or selects a suggestion** from the
typeahead dropdown (selecting a suggestion uses the suggestion's display text as
a search query). The event bubbles and is cancelable.

The `e.detail` structure is identical to [`mapsuggestions`](#mapsuggestions).

By default, the built-in `mapsearch` event handler renders a list of clickable
results in the search panel, navigates to the first result, and keeps focus on
the search input. For each feature it expects `e.detail.responses[].data` to be
a **GeoJSON FeatureCollection** and looks for:

- **Display name** — uses `properties.display_name` if present; otherwise
builds a comma-separated string from `properties.name`, `city`, `county`,
`state`, and `country` (skipping duplicates of `name`). Falls back to
`"Unnamed"`.
- **Map navigation** — zooms and pans to fit `feature.bbox`
(`[west, south, east, north]`), falling back to `properties.extent` (same
format). If neither is available, centers the map on the first
`geometry.coordinates` (`[lon, lat]`) value at `properties.zoom` (default `14`).

Call `e.preventDefault()` to suppress the default navigation and handle results
yourself.

```js
let map = document.querySelector('mapml-viewer');
map.addEventListener('mapsearch', (e) => {
e.preventDefault(); // take over result handling
const { query, responses } = e.detail;
for (const { data, layer } of responses) {
// data is the JSON returned by the search endpoint
for (const feature of data.features) {
console.log(feature.properties.display_name, feature.bbox);
}
}
});
```

---

### mapsuggestions

Fired on the `<mapml-viewer>` element after suggestions responses have been
received from all checked layers that contain a
[`<map-link rel="suggestions">`](../elements/link/#rel). The event bubbles and
is cancelable.

| `e.detail` property | Description |
|---------------------|-------------|
| `query` | The search string the user typed. |
| `responses` | An array of `{ data, link, layer }` objects — one per responding layer. `data` is the parsed JSON response, `link` is the originating `<map-link>` element, and `layer` is the `<map-layer>` element. |

Call `e.preventDefault()` to suppress the built-in suggestion dropdown and
handle results yourself.

```js
let map = document.querySelector('mapml-viewer');
map.addEventListener('mapsuggestions', (e) => {
e.preventDefault(); // take over rendering
const { query, responses } = e.detail;
for (const { data, layer } of responses) {
// data is the JSON returned by the suggestions endpoint
console.log(layer.label, data);
}
});
```

---

Expand Down Expand Up @@ -773,6 +862,8 @@ let output = map.geojson2mapml(json);
|:---------------------------------------------------------------------------------|:------: |:-----: |:---: |
| [**Properties**](#properties) | full | full | full |
| [**Methods**](#methods) | partial * | full | partial * |
| [**Interpreting locations and map positions (5.3)**](https://maps4html.org/HTML-Map-Element-UseCases-Requirements/#map-viewers-capabilities-locations) | | | |
| <div class="undecided">[Select map view from street address or place name (5.3.2)](https://github.com/Maps4HTML/HTML-Map-Element-UseCases-Requirements/issues/145)</div> | full | [full](https://maps4html.org/web-map-doc/docs/user-guide/search) | [full](#events) |

<details>
<summary>Exceptions *</summary>
Expand Down
73 changes: 69 additions & 4 deletions docs/elements/link.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ maps. Most of the extensions center on proposed new values of the `rel` attribu
- provide a URL template that is processed and converted to a URL and fetched by the polyfill, each time the map requires new content to render, such as a tile, via the `tile`, `image`, `feature` and `query` rel values, in conjunction with the `tref="..."` attribute. Such links are automatically created and followed / imported when appropriate.
- include links to legend graphics for a layer. Currently such links are rendered as hyperlinks, not as graphics.
- provide links to CSS and pmtiles stylesheets via the `stylesheet` rel value, which are imported by the polyfill automatically.
- provide links to layers at next native zoom level via `zoomin`, `zoomout` rel values. Such links are automatically followed by the polyfill when appropriate.
- links provide URL templates (in the `tref` attribute) for georeferenced search endpoints via the `search` rel value, and for typeahead/autocomplete via the `suggestions` rel value. These links power the [search control](../../user-guide/search) when it is [enabled](../mapml-viewer/#controlslist) on the viewer.

<!-- demo / example -->
<iframe src="../../../demo/map-link-demo/" title="MapML Demo" height="410" width="100%" scrolling="no" frameBorder="0"></iframe>
Expand All @@ -42,6 +42,8 @@ defines several uses of existing and new `rel` keyword values.
| `legend` | The `legend` link relation designates a link to metadata, typically an image, describing the symbology used by the current layer. Currently, the polyfill creates a hyperlink for the label of the layer in the layer control, which opens in a new browsing context. |
| `query` | The `query` link relation is used in combination with the `tref="..."` attribute to establish a URL template that composes a map query URL based on user map gestures such as click or touch. These URLs are fetched and the response presented on top of the map as a popup. Such queries can return text/html or text/mapml responses. In the latter case, the response may contain more than one feature, in which case a 'paged' popup is generated, allowing the user to cycle through the features' individual metadata. |
| `stylesheet` | The link imports a CSS or [pmtiles](../../user-guide/creating-styles) stylesheet from the `href` value. |
| `search` | The `tref` attribute contains a URL template for a georeferenced search endpoint. The `tref` attribute must contain a `{searchTerms}` variable reference that is substituted with the user's query. Only the first `search` link per layer is used. A layer must provide a `search` link for the search control to become enabled. See [Search](../../user-guide/search). |
| `suggestions` | The `tref` attribute contains a URL template for a typeahead / autocomplete endpoint. Uses the same `{searchTerms}` substitution as `search`. A suggestions link is optional but recommended: when present, results appear as the user types (debounced). Only the first `suggestions` link per layer is used. See [Search](../../user-guide/search). |


---
Expand Down Expand Up @@ -104,14 +106,18 @@ Advisory [language designation](https://datatracker.ietf.org/doc/html/rfc5646) a
The `tref` attribute contains a string that, once processed, will be treated as
a URL and fetched automatically by the polyfill. The string is known as a URL
template. The processing that takes place prior to a URL template becoming a
valid URL is _variable reference substitution_. Variables are created by
`<map-input name="foo">` elements. The name of the variable can be
valid URL is _variable reference substitution_. Variables are usually created
and named by `<map-input name="foo">` elements. The name of the variable can be
referenced in the URL template string contained in the `tref` value, using the
`{foo}` syntax notation. A URL template string can contain 0 or more variable
references. Processing will remove variable references that are valid. That is,
references. Processing will resolve variable references that are valid. That is,
all variables that have been created by `<map-input>`s that are referenced in the
template will be replaced with the value of the variable at the time of processing.

For link `rel` values `search` or `suggestions`, the variable `searchTerms` is **predefined**
and bound to user text input from the search control form. The variable should be
used in the `tref` attribute URL template, via the `{searchTerms}` variable reference.

---
### `tms`

Expand Down Expand Up @@ -161,6 +167,63 @@ and [extent](../../api/mapml-viewer-api#extent).

## Examples

### Search and suggestions

In a remote MapML document, `search` and `suggestions` links are children of `<map-head>`:

```xml
<mapml- xmlns="http://www.w3.org/1999/xhtml">
<map-head>
<map-title>OpenStreetMap</map-title>
<map-link rel="search"
tref="https://photon.komoot.io/api/?q={searchTerms}&amp;limit=5"></map-link>
<map-link rel="suggestions"
tref="https://photon.komoot.io/api/?q={searchTerms}&amp;limit=5"></map-link>
</map-head>
<map-body>
<map-extent units="OSMTILE" checked="checked" hidden="hidden">
<map-input name="z" type="zoom" min="0" max="18" value="3"></map-input>
<map-input name="x" type="location" axis="column" units="tilematrix"></map-input>
<map-input name="y" type="location" axis="row" units="tilematrix"></map-input>
<map-link rel="tile"
tref="https://tile.openstreetmap.org/{z}/{x}/{y}.png"></map-link>
</map-extent>
</map-body>
</mapml->
```

Within inline in HTML, the `search` and `suggestions` links are direct children of the `<map-layer>` element:

```html
<html lang="en">
<head>...</head>
<body>
<mapml-viewer projection="OSMTILE" zoom="3" lat="45" lon="-75"
controls controlslist="search">
<map-layer label="OpenStreetMap" checked>
<map-link rel="search"
tref="https://photon.komoot.io/api/?q={searchTerms}&limit=5"></map-link>
<map-link rel="suggestions"
tref="https://photon.komoot.io/api/?q={searchTerms}&limit=5"></map-link>
<map-extent units="OSMTILE" checked hidden>
<map-input name="z" type="zoom" min="0" max="18" value="3"></map-input>
<map-input name="x" type="location" axis="column" units="tilematrix"></map-input>
<map-input name="y" type="location" axis="row" units="tilematrix"></map-input>
<map-link rel="tile"
tref="https://tile.openstreetmap.org/{z}/{x}/{y}.png"></map-link>
</map-extent>
</map-layer>
</mapml-viewer>
</body>
</html>
```

The search control is disabled until at least one `checked` layer provides
a `<map-link rel="search">`. The `suggestions` link is optional — without it the
control still works but only returns results on submission.

---

### Tile Mapping Specification (tms)

```html
Expand Down Expand Up @@ -206,6 +269,8 @@ and [extent](../../api/mapml-viewer-api#extent).

| | Spec | Viewer | API |
|:---------------------------------------------------------------------------------|:------: |:-----: |:---: |
| [**Interpreting locations and map positions (5.3)**](https://maps4html.org/HTML-Map-Element-UseCases-Requirements/#map-viewers-capabilities-locations) | | | |
| <div class="undecided">[Select map view from street address or place name (5.3.2)](https://github.com/Maps4HTML/HTML-Map-Element-UseCases-Requirements/issues/145)</div> | full | [full](https://maps4html.org/web-map-doc/docs/user-guide/search) | [full](https://maps4html.org/web-map-doc/docs/api/mapml-viewer-api#events) |
| [**Vector features and overlays (5.2)**](https://maps4html.org/HTML-Map-Element-UseCases-Requirements/#map-viewers-capabilities-vectors) | | | |
| <div class="requirement">Display map data attribution and links (5.2.4)</div> | full | full | |
| [**User navigation (pan and zoom) (5.4)**](https://maps4html.org/HTML-Map-Element-UseCases-Requirements/#map-viewers-capabilities-user-navigation) | | | |
Expand Down
Loading
Loading