map-extent documentation + API + update links (#136)

* sync attribute changes of map-extent pr to web-map-doc, including adding full element ending i.e. </map-extent> and also adding missing checked/hidden attributes where applicable * update mapml doc (eng+fr) + update map-extent doc (ENG ONLY) * Tweaks to map-extent * document map-change + loadedmetadata events and remove extentload event * Remove geogratis layer from homepage to get the map working * Revert "sync attribute changes of map-extent pr to web-map-doc, including adding full element ending i.e. </map-extent> and also adding missing checked/hidden attributes where applicable" This reverts commit 49a2c92. * move map-change to the correct place (map-extent -> layer- API) * Add /static/dist to .gitignore Add translations for map-extent hidden,label,opacity and checked * Initial version of HTMLExtentElement in en/fr. Describe map-extent units as initialization only / can't be changed. * Add/Fix broken/incorrect fr links --------- Co-authored-by: Peter Rushforth <[email protected]>
Maps4HTML · Nov 10, 2023 · 705d4a6 · 705d4a6
1 parent 37d0101
commit 705d4a6
Show file tree

Hide file tree

Showing 26 changed files with 416 additions and 49 deletions.
diff --git a/.gitignore b/.gitignore
@@ -21,4 +21,7 @@ yarn-error.log*
 
 examples.md
 
-/.idea
+/.idea
+
+# sync job automatically updates
+/static/dist
diff --git a/docs/api/layer-api.md b/docs/api/layer-api.md
@@ -192,7 +192,8 @@ so the resulting JSON SHOULD (somehow, tbd) be tagged with the datum in use by t
 |--------------	|--------------------------------------------------------	|
 | changestyle     | Fired before the layer changes src due to user selecting alternate style in layer control |
 | changeprojection | Fired before the layer changes projection due to its declared projection being not equal to that of the map |
-| extentload | Fired when the metadata for a layer has loaded, but before loading tiles, features and other content |
+| loadedmetadata | Fired when the metadata for a layer has loaded. The intent is that this event is analagous to the [media element loadedmetadata event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/loadedmetadata_event), but for map layers. |
+|  map-change   | Fired when the `checked` attribute changes state            |
 ---
 
 ## Examples

diff --git a/docs/api/map-extent-api.md b/docs/api/map-extent-api.md
@@ -0,0 +1,168 @@
+---
+id: map-extent-api
+title: "HTMLExtentElement"
+slug: /api/map-extent-api
+---
+
+# HTMLExtentElement
+
+## Properties
+
+### units
+
+The `units` property is read-only, and returns the initial value of the [`units`
+content attribute](../elements/extent/#units).
+
+---
+
+### checked
+
+`HTMLExtentElement.checked` is a boolean read/write value that turns the map-extent 
+on and off, and reflects the `checked` attribute. The `checked` state is 
+reflected in the layer control user interface for the map-extent, if it is not 
+in the `hidden` state, via a checkbox next to the map-extent name.  The checked 
+property can be used to programatically change the checked state of the extent. 
+The checked property can't be changed if the disabled property is set.
+
+To set the checked state of a  map-extent to on:
+
+```js
+let extent = document.querySelector('map-extent');
+extent.checked = true; // valid values are true | false
+```
+
+To read the checked state of the map-extent:
+
+```js
+let extent = document.querySelector('map-extent');
+let isChecked = extent.checked;
+```
+---
+
+### hidden
+
+`HTMLExtentElement.hidden` is a boolean  read/write value that hides or unhides the
+map-extent in the layer control only.  The `hidden` state has no bearing on the presence
+of map-extent content on the map, it only affects the map-extent presence in the
+layer control. This can be useful for simplifying the layer control representation
+of a single- map-extent containing parent layer without cluttering the user 
+interface.
+
+To set/update whether the map-extent is hidden in the layer control:
+
+```js
+let extent = document.querySelector('map-extent');
+extent.hidden = true; // valid values are true | false
+```
+
+To get the `<map-extent>`'s hidden value:
+
+```js
+let extent = document.querySelector('map-extent');
+let isHidden = extent.hidden;
+```
+---
+
+### disabled
+
+`HTMLExtentElement.disabled` provides READ-ONLY access to the disabled state of the
+map-extent.  A map-extent becomes disabled if its contents are not rendered, 
+either by being completely outside the current map-extent's bounds or by having 
+an error associated to the map-extent processing, such as being in a projection 
+that is incompatible with the projection of the map. When a map-extent is 
+disabled, the user can still interact with it in some ways in the layer control, but it will 
+not be visible in the map viewport.  If a map-extent becomes enabled, through 
+manipulation of the map, for example, the map-extent will become fully interactive
+in the layer control, and should be visible in the map viewport (although 
+possibly hard to see, depending on `opacity` and feature size, among other 
+considerations).
+
+---
+
+### label
+
+`HTMLExtentElement.label` reflects the `label` content attribute, and specifies
+a fallback accessible name for the map-extent in the layer control.  If the
+`label` content attribute is not supplied, an internationalized variation of
+"Sub-Layer" will be returned as the default value.
+
+To set/update the `<map-extent>`'s label:
+
+```js
+let extent = document.querySelector('map-extent');
+extent.label = "New Accessible Name";
+```
+
+To get the `<map-extent>`'s label value:
+
+```js
+let extent = document.querySelector('map-extent');
+let label = extent.label;
+```
+---
+
+### opacity
+`HTMLExtentElement.opacity` provides read/write access to the `opacity` value, 
+and is reflected in the layer control for each map-extent, under "Opacity". If no
+`opacity` content attribute is set, setting the `opacity` property will not 
+create the attribute, though the opacity of the map-extent on the map and in
+the layer control representation (slider input) will be changed.
+
+To set/update the `<map-extent>`'s opacity:
+
+```js
+let extent = document.querySelector('map-extent');
+extent.opacity = 0.5; // valid values from 0 to 1
+```
+
+To get the `<map-extent>`'s opacity value:
+
+```js
+let extent = document.querySelector('map-extent');
+let opacity = extent.opacity;
+```
+
+---
+## Methods
+
+---
+
+## Events
+
+| Event name      	| Description                                          	|
+|--------------	|--------------------------------------------------------	|
+|  |  |
+---
+
+## Examples
+
+---
+
+## Specifications
+
+| Specification                                                |
+|--------------------------------------------------------------|
+| [HTMLExtentElement](https://maps4html.org/MapML/spec/#dom-htmlextentelement) |
+
+---
+
+## Requirements
+
+[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-)
+
+<p><b><span class="requirement">requirement</span>
+<span class="enhancement">enhancement</span>
+<span class="impractical">impractical</span>
+<span class="undecided">undecided</span>
+<span class="discussion">under discussion</span></b></p>
+
+|  | Spec | Viewer | API |
+|:---------------------------------------------------------------------------------|:------: |:-----: |:---: |
+| [**Properties**](#properties) | full | full | full |
+| [**Methods**](#methods) | n/a | n/a | n/a |
+| [**Events**](#events) | n/a | n/a | n/a |
+
+---
+
+> - [Edit this page on **Github**](https://github.com/Maps4HTML/web-map-doc/edit/main/docs/api/extent-api.md)
+> - [Chat with us on **Gitter**](https://gitter.im/Maps4HTML/chat)
diff --git a/docs/elements/extent.md b/docs/elements/extent.md
@@ -38,8 +38,8 @@ URL template.
 ### `units`
 
 Specifies the projection of the tiles and other content that is expected from the
-server.  If the projection value is not a case-sensitive match of the `<mapml-viewer>` 
-`projection` attribute, the layer will be disabled in the layer control, and will
+server.  If the projection value is a case-insensitive match of the `<mapml-viewer>`
+`projection` attribute, the extent will be disabled in the layer control, and will
 not be displayed on the map, nor content fetched.
 
 Defined values of `units` include:
@@ -52,27 +52,33 @@ Defined values of `units` include:
 
 Author-defined values of `units` are possible, using the [Custom projections API](../../api/mapml-viewer-api/#definecustomprojectionoptions)
 
+The `units` attribute is required and can't be changed.
+
 ---
 
 ### `label`
 
-Specifies a label for an extent which is displayed in the layer control. When a `label` is not provided, the extent is hidden by default in the layer control.
+Specifies a label for an extent which is displayed in the layer control. When a `label` value is not provided, the `label` value defaults to 'Sub-Layer' in the layer control.
 
 ---
 
-### `opacity`
+### `checked`
 
-The `opacity` attribute is used to set the initial opacity of the `<map-extent>` element.
-Valid `opacity` values range from from "0.0" to "1.0" with strictly one demical place and are reflected in the extent settings
-opacity input slider control. When the `opacity` attribute is not present, the opacity is set to "1.0" by default.
+The `checked` attribute and property is boolean. When present, the checked property value is taken to be 'true'; when not present, the property value is 'false'. The map-extent content will be fetched and rendered according to the `checked` state. Beware that it is the *presence* of the attribute that makes it true, not the value of the attribute. For example, the attribute `checked="false"` actually turns out to be checked, [as described by MDN Web docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes#boolean_attributes).
 
 ---
 
-## Events
+### `hidden`
 
-| Event name    | Description                                             |
-|--------------	|--------------------------------------------------------	|
-| extentload    | Fires when a layer's extent is loaded and parsed. The intent is that this event is analagous to the [media element loadedmetadata event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/loadedmetadata_event), but for map layers.              |
+The `hidden` attribute and property is boolean. When present, the extent is hidden (not present) in the layer control.  Regardless of `hidden` state, the layer is rendered or not depending on the `checked` attribute state. 
+
+---
+
+### `opacity`
+
+The `opacity` attribute is used to set the initial opacity of the `<map-extent>` element.
+Valid `opacity` values range from from "0.0" to "1.0" with strictly one demical place and are reflected in the extent settings
+opacity input slider control. When the `opacity` attribute is not present, the opacity is set to "1.0" by default.
 
 ---
 

diff --git a/docs/elements/mapml.md b/docs/elements/mapml.md
@@ -27,6 +27,7 @@ must contain one `<map-head>` element, followed by one `<map-body>` element.
     <map-link rel="license" href="https://www.openstreetmap.org/copyright" title="© OpenStreetMap contributors CC BY-SA"></map-link>
   </map-head>
   <map-body>
+    <!-- When 'boolean' attributes such as 'checked' or 'hidden' are used in a mapml file, they must have a string value. i.e 'checked="checked"' -->
     <map-extent units="OSMTILE" checked="checked" hidden="hidden">
       <map-input name="z" type="zoom"  value="18" min="0" max="18"></map-input>
       <map-input name="x" type="location" units="tilematrix" axis="column" min="0"  max="262144" ></map-input>

diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/api/layer-api.md b/i18n/fr/docusaurus-plugin-content-docs/current/api/layer-api.md
@@ -166,7 +166,8 @@ Au besoin, `mapml2geojson` transforme des coordonnées en `gcrs` par défaut ava
 |--------------	|--------------------------------------------------------	|
 | changestyle     | Déclenché avant que la couche ne change de src parce que l’utilisateur a sélectionné un autre style au niveau du contrôle de la couche |
 | changeprojection | Déclenché avant que la couche ne change de projection parce que la projection déclarée n’est pas égale à celle de la carte |
-| extentload | Déclenché lorsque les métadonnées d’une couche ont été chargées, mais avant le chargement des pavés, des caractéristiques et de tout autre contenu |
+| loadedmetadata | 	Déclenché lorsque les métadonnées d'une couche ont été chargées. L’intention est que cet événement soit analogue à l’événement [loadedmetadata de l’élément média](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/loadedmetadata_event), mais avec les couches d’une carte. |
+| map-change    | Déclenché lorsque l'attribut `checked` change d'état              |
 ---
 
 ## Exemples