Skip to content

Commit 0407380

Browse files
prushforprushforth
prushfor
authored and
prushforth
committed
Update MapML.HTMLMapmlViewerElement.matchMedia(mq) en documentation
Update extension content preference section and links to/from Added French translations Update images of extension to show multiple preferred content selection
1 parent 1c8f57f commit 0407380

File tree

7 files changed

+220
-3
lines changed

7 files changed

+220
-3
lines changed

‎docs/api/mapml-viewer-api.mdx

+100-1
Original file line numberDiff line numberDiff line change
@@ -222,6 +222,7 @@ let zoom = map.zoom;
222222
| [defineCustomProjection(options)](#definecustomprojectionoptions) | Define a custom projection for use by the page. |
223223
| [zoomTo(lat, lon, zoom)](#zoomtolat-lon-zoom) | Fly or pan the map to a (new) location and zoom level.|
224224
| [geojson2mapml(json, options)](#zoomtolat-lon-zoom) | Add a GeoJSON Layer to the map. |
225+
| [matchMedia(mediaQueryString)](#matchmediamediaquerystring) | Returns a [MediaQueryList](https://developer.mozilla.org/en-US/docs/Web/API/MediaQueryList)-like object.
225226

226227

227228
### back()
@@ -358,6 +359,32 @@ Check out [this application](https://maps4html.org/experiments/api/custom-map-ui
358359

359360
---
360361

362+
### matchMedia(mediaQueryString)
363+
364+
While not strictly 'media' features, some dynamic map properties can be combined in queries with standard media features, for example the 'prefers-color-scheme' feature,
365+
to enable a map container / media-query-like interface.
366+
367+
`matchMedia(mediaQueryString)` returns a [MediaQueryList-like object](https://developer.mozilla.org/en-US/docs/Web/API/MediaQueryList).
368+
The `matches` boolean-valued property of the object can be used for an immediate determination of whether the map meets the queried feature conditions. To react to changes in
369+
the map state / media conditions, use MediaQueryList.addEventListener('change', callbackFn) to add an event listener for `change` events that are triggered by changes in the
370+
state of the queried map properties (projection, zoom, extent); any change to the map that results in a change in state of the [MediaQueryListEvent `matches` boolean property](https://developer.mozilla.org/en-US/docs/Web/API/MediaQueryList/change_event)triggers the `change` event and calls the callbackFn.
371+
372+
## Supported map 'media' query features
373+
374+
| Feature name | Description |
375+
|------------------|-------------|
376+
| map-zoom | Range of integers Used to evaluate if map-zoom is of a certain value or within a range |
377+
| map-projection | Discrete string values - known values include `OSMTILE`, `CBMTILE`, `WGS84`, `APSTILE`. Can be extended with [custom projections](#definecustomprojectionoptions). |
378+
| map-top-left-easting | Range of integers - **Decimal values are not supported.** |
379+
| map-top-left-northing | Range of integers - **Decimal values are not supported.** |
380+
| map-bottom-right-easting | Range of integers - **Decimal values are not supported.** |
381+
| map-bottom-right-northing | Range of integers - **Decimal values are not supported.** |
382+
| prefers-map-content | Discrete string values - supported values include: `image`, `tile`, `feature`, `table`. Preferences can be established via multi-select in the [MapML browser extension](../extension/features#select-map-content-preferences) |
383+
| prefers-color-scheme | Discrete string values - supported values are `light` and `dark` |
384+
| prefers-lang | 2-character language code returned by `navigator.language`, based on user's browser display language setting |
385+
386+
---
387+
361388
## Events
362389

363390
| Event name | Description |
@@ -617,7 +644,7 @@ let output = map.geojson2mapml(json);
617644
<meta charset="utf-8">
618645
<meta name="viewport" content="width=device-width, initial-scale=1">
619646
<title>Example Custom Projection</title>
620-
<script type="module" src="web-map/mapml.js"></script>
647+
<script type="module" src="./mapml.js"></script>
621648
<script type="module">
622649
let customProjectionDefinition = `{
623650
"projection": "ATLAS_POLAR_MAP",
@@ -649,6 +676,78 @@ let output = map.geojson2mapml(json);
649676
</html>
650677
```
651678

679+
### matchMedia
680+
681+
```html
682+
<!doctype html>
683+
<html lang="en">
684+
<head>
685+
<meta charset="utf-8">
686+
<title>Example map media query</title>
687+
// adjust the path to where you can find the distributed mapml.js artifact
688+
<script type="module" src="./mapml.js"></script>
689+
<script>
690+
document.addEventListener('DOMContentLoaded', () => {
691+
const map = document.querySelector('mapml-viewer');
692+
map.whenReady().then(() => {
693+
const extent = map.extent;
694+
695+
const topLeftEasting = Math.trunc(extent.topLeft.pcrs.horizontal);
696+
const topLeftNorthing = Math.trunc(extent.topLeft.pcrs.vertical);
697+
const bottomRightEasting = Math.trunc(extent.bottomRight.pcrs.horizontal);
698+
const bottomRightNorthing = Math.trunc(extent.bottomRight.pcrs.vertical);
699+
700+
// Format the media query string to detect overlap:
701+
// (xminm < xmaxq) and (xmaxm > xminq) and (yminm < ymaxq) and (ymaxm > yminq)
702+
const query = `(map-projection: OSMTILE) and (7 < map-zoom < 14) and (map-top-left-easting < ${bottomRightEasting}) and (map-bottom-right-easting > ${topLeftEasting}) and (map-bottom-right-northing < ${topLeftNorthing}) and (map-top-left-northing > ${bottomRightNorthing})`;
703+
704+
const matcher = map.matchMedia(query);
705+
706+
// create a layer to visually represent the query as the map moves
707+
const f = `<map-layer checked label="test media query"><map-meta name="projection" content="OSMTILE"></map-meta>
708+
<map-meta name="cs" content="pcrs"></map-meta><map-feature><map-properties>${query}</map-properties>
709+
<map-geometry><map-polygon><map-coordinates>${topLeftEasting} ${topLeftNorthing}
710+
${bottomRightEasting} ${topLeftNorthing} ${bottomRightEasting} ${bottomRightNorthing} ${topLeftEasting} ${bottomRightNorthing}
711+
${topLeftEasting} ${topLeftNorthing}</map-coordinates</map-polygon></map-geometry></map-feature></map-layer>`;
712+
713+
const parser = new DOMParser();
714+
const layer = parser
715+
.parseFromString(f, 'text/html')
716+
.querySelector('map-layer');
717+
map.appendChild(layer);
718+
const changeDisplayLayer = () => {
719+
if (matcher.matches) {
720+
layer.checked = true;
721+
layer.hidden = false;
722+
alert('Feature overlaps the map');
723+
} else {
724+
layer.checked = false;
725+
layer.hidden = true;
726+
alert('Feature does not overlap the map');
727+
}
728+
};
729+
changeDisplayLayer();
730+
matcher.addEventListener('change', changeDisplayLayer);
731+
});
732+
});
733+
</script>
734+
</head>
735+
<body>
736+
<mapml-viewer projection="OSMTILE" zoom="14" lat="45.406314" lon="-75.6883335" controls>
737+
<map-layer label="OpenStreetMap" checked>
738+
<map-link rel="license" title="© OpenStreetMap contributors CC BY-SA"
739+
href="https://www.openstreetmap.org/copyright"></map-link>
740+
<map-extent units="OSMTILE" checked hidden>
741+
<map-input name="z" type="zoom" value="18" min="0" max="18"></map-input>
742+
<map-input name="x" type="location" units="tilematrix" axis="column" min="0" max="262144"></map-input>
743+
<map-input name="y" type="location" units="tilematrix" axis="row" min="0" max="262144"></map-input>
744+
<map-link rel="tile" tref="https://tile.openstreetmap.org/{z}/{x}/{y}.png"></map-link>
745+
</map-extent>
746+
</map-layer>
747+
</mapml-viewer>
748+
</body>
749+
</html>
750+
```
652751

653752
---
654753

‎docs/assets/img/render-mapml.png

12 KB
Loading

‎docs/elements/layer.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -113,4 +113,4 @@ The following example sets the initial `opacity` for a `<map-layer>`.
113113
---
114114

115115
> - [Edit this page on **Github**](https://github.com/Maps4HTML/web-map-doc/edit/main/docs/elements/layer.md)
116-
> - [Chat with us on **Gitter**](https://gitter.im/Maps4HTML/chat)
116+
> - [Chat with us on **Gitter**](https://gitter.im/Maps4HTML/chat)

‎docs/extension/features.md

+16
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,22 @@ context menu is projected coordinates (PCRS), and that for copying locations is
3737
by default geodetic (GCRS). When changed to another through the extension
3838
user interface, the selected cs will be used for subsequent copy operations.
3939

40+
### Select map content preferences
41+
42+
By default, no preference is expressed by the user as to what their preferred
43+
content type for maps may be. Some users may prefer focusable feature
44+
data in the map where possible; others may opt for image-based or tiled-image
45+
based map content. Others may wish to experience only textual feature data in
46+
the form of an accessibility technology (AT)-friendly table that is by default
47+
sorted in ascending order of distance from map center, but that may be
48+
sorted by different column headings selected by the user. To establish a set of
49+
preferences, select the applicable combination of entries from the "Content Preferences"
50+
list (select more than one entry by holding Ctrl or Shift while selecting).
51+
52+
Such preferences may be honoured by a map author via inclusion in [map 'media' queries](../api/mapml-viewer-api#matchmediamediaquerystring).
53+
54+
![Content Preferences](../assets/img/render-mapml.png)
55+
4056
## Requirements
4157

4258
[Report problems with these requirements on GitHub](https://github.com/Maps4HTML/HTML-Map-Element-UseCases-Requirements/issues/new?title=-SUMMARIZE+THE+PROBLEM-&body=-DESCRIBE+THE+PROBLEM-)

‎i18n/fr/docusaurus-plugin-content-docs/current/api/mapml-viewer-api.mdx

+93-1
Original file line numberDiff line numberDiff line change
@@ -225,6 +225,7 @@ let zoom = map.zoom;
225225
| [defineCustomProjection(options)](#definecustomprojectionoptions) | Définir une projection personnalisée à utiliser par la page. |
226226
| [zoomTo(lat, lon, zoom)](#zoomtolat-lon-zoom) | Survole la carte ou effectue un mouvement panoramique vers un (nouvel) emplacement et à un autre niveau de zoom.|
227227
| [geojson2mapml(json, options)](#zoomtolat-lon-zoom) | Convertit une caractéristique GeoJSON ou une chaîne ou un objet de collection de caractéristiques en élément MapML `<map-layer>` contenant un ou plusieurs éléments `<map-feature>`. |
228+
| [matchMedia(mediaQueryString)](#matchmediamediaquerystring) | Renvoie un objet similaire à [MediaQueryList](https://developer.mozilla.org/en-US/docs/Web/API/MediaQueryList). |
228229

229230

230231
### back()
@@ -360,6 +361,28 @@ Jetez un coup d’œil à [cette application](https://maps4html.org/experiments/
360361
| <span id="option-properties">`properties`</span> | \<Function \| String \| HTMLElement\> | _Les propriétés seront mappées à un [table](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table) HTML._ | Précise la façon dont les propriétés sont mappées. \<Function\> - Fonction qui accepte un argument – l’objet GeoJSON feature – et qui doit retourner un HTMLElement qui devient l’unique élément-enfant de \<properties\>. \<String\> - Chaîne qui sera analysée syntaxiquement et utilisée comme unique élément-enfant de `<properties>` avec toutes les caractéristiques. \<HTMLElement\> - Élément qui servira d’unique élément- enfant de `<properties>` avec toutes les caractéristiques. Voir la section [utilisation des options de base](#utilisation-des-options-de-base) pour un exemple.|
361362
| `geometryFunction` | \<Function\> | La géométrie _MapML reproduit la valeur géométrique GeoJSON_ | \<Function\> Fonction pour modifier les [descendants générés](https://maps4html.org/web-map-doc/docs/elements/geometry/#child-elements) de `<map-geometry>` qui peut ajouter des classes, [hyperlinks](https://maps4html.org/web-map-doc/docs/elements/map-a/) et des [spans](https://maps4html.org/web-map-doc/docs/elements/span/) à l’instance. Un élément `<map-geometry>` simple est créé par défaut. La fonction accepte deux arguments : l’[élément-enfant généré](https://maps4html.org/web-map-doc/docs/elements/geometry/#child-elements) de `<map-geometry>` et [l’objet de la caractéristique JSON](https://www.rfc-editor.org/rfc/rfc7946#section-3.2) pour retourner un élément-enfant modifié de `<map-geometry>`. Voir la section [Utilisation des options de base](#utilisation-des-options-de-base) pour un exemple. |
362363

364+
---
365+
366+
### matchMedia(mediaQueryString)
367+
368+
Bien que cela ne soit pas strictement des fonctionnalités "média", certaines propriétés dynamiques de la carte peuvent être combinées dans des requêtes avec des fonctionnalités média standard, comme la fonctionnalité 'prefers-color-scheme', pour permettre une interface de type conteneur de carte / requête média.
369+
370+
`matchMedia(mediaQueryString)` renvoie un [objet similaire à MediaQueryList](https://developer.mozilla.org/en-US/docs/Web/API/MediaQueryList). La propriété booléenne `matches` de l'objet peut être utilisée pour déterminer immédiatement si la carte répond aux conditions des fonctionnalités requises. Pour réagir aux changements dans l'état de la carte ou des conditions média, utilisez `MediaQueryList.addEventListener('change', callbackFn)` pour ajouter un écouteur d'événements aux événements `change` déclenchés par les modifications de l'état des propriétés de la carte interrogées (projection, zoom, étendue). Tout changement de la carte qui entraîne une modification de l'état de la propriété booléenne `matches` de [MediaQueryListEvent](https://developer.mozilla.org/en-US/docs/Web/API/MediaQueryList/change_event) déclenche l'événement `change` et appelle la fonction `callbackFn`.
371+
372+
## Fonctionnalités de requête "média" prises en charge pour la carte
373+
374+
| Nom de la fonctionnalité | Description |
375+
|-----------------------------|-----------------------------------------------------------------------------|
376+
| map-zoom | Gamme d'entiers utilisée pour évaluer si `map-zoom` a une certaine valeur ou se situe dans une plage |
377+
| map-projection | Valeurs discrètes de chaîne - les valeurs connues incluent `OSMTILE`, `CBMTILE`, `WGS84`, `APSTILE`. Peut être étendu avec des [projections personnalisées](#definecustomprojectionoptions). |
378+
| map-top-left-easting | Gamme d'entiers - **Les valeurs décimales ne sont pas prises en charge.** |
379+
| map-top-left-northing | Gamme d'entiers - **Les valeurs décimales ne sont pas prises en charge.** |
380+
| map-bottom-right-easting | Gamme d'entiers - **Les valeurs décimales ne sont pas prises en charge.** |
381+
| map-bottom-right-northing | Gamme d'entiers - **Les valeurs décimales ne sont pas prises en charge.** |
382+
| prefers-map-content | Valeurs discrètes de chaîne - les valeurs prises en charge incluent : `image`, `tile`, `feature`, `table`. Les préférences peuvent être définies via une multi-sélection dans [l'extension navigateur MapML](../extension/features#sélectionner-les-préférences-de-contenu-de-la-carte). |
383+
| prefers-color-scheme | Valeurs discrètes de chaîne - les valeurs prises en charge sont `light` et `dark`. |
384+
| prefers-lang | Code de langue à 2 caractères renvoyé par `navigator.language`, basé sur le paramètre de langue d'affichage du navigateur de l'utilisateur |
385+
363386
---
364387
## Événements
365388

@@ -619,7 +642,7 @@ let output = map.geojson2mapml(json);
619642
<meta charset="utf-8">
620643
<meta name="viewport" content="width=device-width, initial-scale=1">
621644
<title>Exemple d'un projection personnalisée</title>
622-
<script type="module" src="web-map/mapml.js"></script>
645+
<script type="module" src="./mapml.js"></script>
623646
<script type="module">
624647
let customProjectionDefinition = `{
625648
"projection": "ATLAS_POLAR_MAP",
@@ -650,6 +673,75 @@ let output = map.geojson2mapml(json);
650673
</body>
651674
</html>
652675
```
676+
677+
### matchMedia
678+
679+
```html
680+
<!doctype html>
681+
<html lang="fr">
682+
<head>
683+
<meta charset="utf-8">
684+
<title>Exemple de requête média pour une carte</title>
685+
// ajustez le chemin vers l'endroit où se trouve l'artéfact distribué mapml.js
686+
<script type="module" src="./mapml.js"></script>
687+
<script>
688+
document.addEventListener('DOMContentLoaded', () => {
689+
const map = document.querySelector('mapml-viewer');
690+
map.whenReady().then(() => {
691+
const extent = map.extent;
692+
const topLeftEasting = Math.trunc(extent.topLeft.pcrs.horizontal);
693+
const topLeftNorthing = Math.trunc(extent.topLeft.pcrs.vertical);
694+
const bottomRightEasting = Math.trunc(extent.bottomRight.pcrs.horizontal);
695+
const bottomRightNorthing = Math.trunc(extent.bottomRight.pcrs.vertical);
696+
// Formater la chaîne de requête média pour détecter les chevauchements :
697+
// (xminm < xmaxq) et (xmaxm > xminq) et (yminm < ymaxq) et (ymaxm > yminq)
698+
const query = `(map-projection: OSMTILE) and (7 < map-zoom < 14) and (map-top-left-easting < ${bottomRightEasting}) and (map-bottom-right-easting > ${topLeftEasting}) and (map-bottom-right-northing < ${topLeftNorthing}) and (map-top-left-northing > ${bottomRightNorthing})`;
699+
const matcher = map.matchMedia(query);
700+
// créer une couche pour représenter visuellement la requête lorsque la carte se déplace
701+
const f = `<map-layer checked label="test media query"><map-meta name="projection" content="OSMTILE"></map-meta>
702+
<map-meta name="cs" content="pcrs"></map-meta><map-feature><map-properties>${query}</map-properties>
703+
<map-geometry><map-polygon><map-coordinates>${topLeftEasting} ${topLeftNorthing}
704+
${bottomRightEasting} ${topLeftNorthing} ${bottomRightEasting} ${bottomRightNorthing} ${topLeftEasting} ${bottomRightNorthing}
705+
${topLeftEasting} ${topLeftNorthing}</map-coordinates</map-polygon></map-geometry></map-feature></map-layer>`;
706+
const parser = new DOMParser();
707+
const layer = parser
708+
.parseFromString(f, 'text/html')
709+
.querySelector('map-layer');
710+
map.appendChild(layer);
711+
const changeDisplayLayer = () => {
712+
if (matcher.matches) {
713+
layer.checked = true;
714+
layer.hidden = false;
715+
alert('La fonctionnalité chevauche la carte');
716+
} else {
717+
layer.checked = false;
718+
layer.hidden = true;
719+
alert('La fonctionnalité ne chevauche pas la carte');
720+
}
721+
};
722+
changeDisplayLayer();
723+
matcher.addEventListener('change', changeDisplayLayer);
724+
});
725+
});
726+
</script>
727+
</head>
728+
<body>
729+
<mapml-viewer projection="OSMTILE" zoom="14" lat="45.406314" lon="-75.6883335" controls>
730+
<map-layer label="OpenStreetMap" checked>
731+
<map-link rel="license" title="© Contributeurs OpenStreetMap CC BY-SA"
732+
href="https://www.openstreetmap.org/copyright"></map-link>
733+
<map-extent units="OSMTILE" checked hidden>
734+
<map-input name="z" type="zoom" value="18" min="0" max="18"></map-input>
735+
<map-input name="x" type="location" units="tilematrix" axis="column" min="0" max="262144"></map-input>
736+
<map-input name="y" type="location" units="tilematrix" axis="row" min="0" max="262144"></map-input>
737+
<map-link rel="tile" tref="https://tile.openstreetmap.org/{z}/{x}/{y}.png"></map-link>
738+
</map-extent>
739+
</map-layer>
740+
</mapml-viewer>
741+
</body>
742+
</html>
743+
```
744+
653745
---
654746

655747
## Spécifications

‎i18n/fr/docusaurus-plugin-content-docs/current/assets/img/render-mapml.png

12 KB
Loading

0 commit comments

Comments
 (0)