diff --git a/.gitignore b/.gitignore index 1c288c88..8a60f749 100644 --- a/.gitignore +++ b/.gitignore @@ -21,4 +21,7 @@ yarn-error.log* examples.md -/.idea \ No newline at end of file +/.idea + +# sync job automatically updates +/static/dist \ No newline at end of file diff --git a/docs/api/layer-api.md b/docs/api/layer-api.md index abe77535..3ae9f43a 100644 --- 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 new file mode 100644 index 00000000..768497dd --- /dev/null +++ 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 ``'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 ``'s label: + +```js +let extent = document.querySelector('map-extent'); +extent.label = "New Accessible Name"; +``` + +To get the ``'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 ``'s opacity: + +```js +let extent = document.querySelector('map-extent'); +extent.opacity = 0.5; // valid values from 0 to 1 +``` + +To get the ``'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-) + +

requirement +enhancement +impractical +undecided +under discussion

+ +| | 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 index 29eee2b4..b684152a 100644 --- 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 `` -`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 `` +`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 `` 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 `` 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 index 4d2f5ffe..edf15838 100644 --- a/docs/elements/mapml.md +++ b/docs/elements/mapml.md @@ -27,6 +27,7 @@ must contain one `` element, followed by one `` element. +