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

Open
prushforth wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Document new search control #174

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b48c47b
WIP document new search control
prushforth May 24, 2026
1387642
Update search docs, add demo
prushforth May 24, 2026
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
87 changes: 82 additions & 5 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 @@ -406,6 +408,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 +848,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
55 changes: 52 additions & 3 deletions docs/elements/link.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ maps. Most of the extensions center on proposed new values of the `rel` attribu
- 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 +43,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 +107,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 +168,46 @@ 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>`:

```html
<map-head>
<map-link rel="search"
tref="https://photon.komoot.io/api/?q={searchTerms}&limit=5" />
<map-link rel="suggestions"
tref="https://photon.komoot.io/api/?q={searchTerms}&limit=5" />
</map-head>
```

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

```html
<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 rel="suggestions"
tref="https://photon.komoot.io/api/?q={searchTerms}&limit=5" />
<map-extent units="OSMTILE" checked hidden>
<map-input name="z" type="zoom" min="0" max="18" value="3" />
<map-input name="x" type="location" axis="column" units="tilematrix" />
<map-input name="y" type="location" axis="row" units="tilematrix" />
<map-link rel="tile"
tref="https://tile.openstreetmap.org/{z}/{x}/{y}.png" />
</map-extent>
</map-layer>
</mapml-viewer>
```

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 +253,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
9 changes: 5 additions & 4 deletions docs/elements/mapml-viewer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ The `<mapml-viewer>` element is the main element you can use to put a custom Web
</style>
</head>
<body>
<mapml-viewer projection="OSMTILE" zoom="0" lat="0.0" lon="0.0" controls>
<mapml-viewer projection="OSMTILE" zoom="0" lat="0.0" lon="0.0" controls controlslist="geolocation search">
<map-layer label="OpenStreetMap" src="https://geogratis.gc.ca/mapml/en/osmtile/osm/" checked></map-layer>
</mapml-viewer>
</body>
Expand Down Expand Up @@ -82,7 +82,9 @@ The default projection is `OSMTILE`.

### `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).
`controlslist` - an enumerated attribute, possible values are: "`nofullscreen`", "`nolayer`", "`noreload`", "`noscale`", "`nozoom`", "`geolocation`" and "`search`". The `no*` tokens let you prune the set of controls automatically presented (when you have used the `controls` boolean attribute), while unlike the `no*` tokens (which hide default controls), the `geolocation` and `search` tokens are **opt-in**. `geolocation` and `search` add location and search controls to the map, respectively. The search control is `disabled` by default, and becomes enabled only when at least one `checked` [`<map-layer>`](../layer/) contains a [`<map-link rel="search">`](../link/) element.

For a full guide to configuring and customizing search, see the [Search user guide](../../user-guide/search).

---

Expand Down Expand Up @@ -132,8 +134,7 @@ present. When it is not present or removed, these features are enabled again.
| <div class="requirement">Display a basic map without JavaScript (5.1.5)</div> | full | [limited](https://maps4html.org/experiments/progressive-enhancement/) | |
| <div class="requirement">Display map content in a users preferred language (5.1.6)</div> | [full](https://github.com/Maps4HTML/HTML-Map-Element-UseCases-Requirements/issues/136) | [full](https://github.com/Maps4HTML/mapml-extension) | |
| [**Interpreting locations and map positions (5.3)**](https://maps4html.org/HTML-Map-Element-UseCases-Requirements/#map-viewers-capabilities-locations) | | | |
| <div class="requirement">Select map view from latitude and longitude point (5.3.1)</div> | full | full | [full](https://maps4html.org/web-map-doc/docs/api/mapml-viewer-api#zoomtolat-lon-zoom) |
| <div class="undecided">Display map tiles defined in various common coordinate systems (5.3.3)</div> | [full](https://github.com/Maps4HTML/HTML-Map-Element-UseCases-Requirements/issues/14) | full | [full](https://maps4html.org/web-map-doc/docs/api/custom-projections) |
| <div class="requirement">Select map view from latitude and longitude point (5.3.1)</div> | full | full | [full](https://maps4html.org/web-map-doc/docs/api/mapml-viewer-api#zoomtolat-lon-zoom) || <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) || <div class="undecided">Display map tiles defined in various common coordinate systems (5.3.3)</div> | [full](https://github.com/Maps4HTML/HTML-Map-Element-UseCases-Requirements/issues/14) | full | [full](https://maps4html.org/web-map-doc/docs/api/custom-projections) |
| <div class="undecided">Reproject map tile data into a new projection or globe view (5.3.4)</div> | [under discussion](https://github.com/Maps4HTML/HTML-Map-Element-UseCases-Requirements/issues/3) | none | |
| <div class="undecided">Save the location or export to other application (5.3.5)</div> | limited | limited | |
| [**User navigation (pan and zoom) (5.4)**](https://maps4html.org/HTML-Map-Element-UseCases-Requirements/#map-viewers-capabilities-user-navigation) | | | |
Expand Down
Loading
Loading