Skip to content

Commit defc330

Browse files
prushforthprushforth
committed
Add .github/skills folder with how-to-markup instructions, based on web-map-doc
1 parent ddfe5dc commit defc330

15 files changed

Lines changed: 1789 additions & 0 deletions

File tree

‎.github/skills/map-a-markup/SKILLS.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
---
2+
name: mapml-a-markup
3+
description: Tells you how to correctly create and edit the markup for a <map-a> element. Use it when generating MapML output markup in an HTML page, especially to wrap `<map-geometry>` content, either in whole or in part, just like how you might use `<a>` to wrap all or part of a paragraph of text in HTML.
4+
---
5+
6+
The `<map-a>` element is a proposal to extend the Web to include links between maps and locations.
7+
This element allows you to wrap parts of coordinates or entire geometries, making a link out of the location/area that is wrapped. When a feature geometry or geometry part is
8+
wrapped in a `<map-a>` element, it creates a blue outline that is 1 pixel wide around the feature (by default), that lets the user know it's a "linked feature".
9+
10+
## Attributes
11+
12+
### `href`
13+
- The URL that the wrapped location points to. Note - If the `type` of the `<map-a>` is text/mapml
14+
you can provide fragments, more on fragments below.
15+
16+
---
17+
18+
### `target`
19+
- This is where the linked URL will be displayed. See table below for more details.
20+
- Defaults to `_self`, in the absence of a valid value.
21+
22+
---
23+
24+
### `type`
25+
- This is the mime type of the linked URL's format. Options are `text/html` & `text/mapml`.
26+
- Defaults to `text/mapml`, in the absence of a valid type value.
27+
28+
---
29+
30+
### `inplace`
31+
- The `inplace` attribute is a boolean attribute - `<map-a inplace href="..."><map-a>`
32+
- When present, the default view-changing behavior is overridden and the map view does not change.
33+
34+
---
35+
36+
## Target Behavior for `text/mapml`
37+
38+
| Target Value | Behavior |
39+
|-------------- |------------------------------------------------------- |
40+
| _self | Replaces the current layer with the linked URL layer. |
41+
| _blank | Adds the linked URL layer to the map. |
42+
| _parent | Replace all the layers with the linked URL layer. |
43+
| _top | Navigate the webpage to the linked URL. |
44+
45+
---
46+
47+
## Target Behavior for `text/html`
48+
49+
| Target Value | Behavior |
50+
|-------------- |----------------------------------------- |
51+
| _self | Navigate the webpage to the linked URL. |
52+
| _blank | Open the linked URL in a new tab. |
53+
| _parent | Navigate the webpage to the linked URL. |
54+
| _top | Navigate the webpage to the linked URL. |
55+
56+
---
57+
58+
## Location fragments
59+
60+
If the `type` attribute's value is `text/mapml`, you have the ability add a location fragment
61+
to the URL. This will pan & zoom the map to the given location.
62+
63+
Fragments are in the following format `#zoom, longitude, latitude`.
64+
65+
URL's solely defined in terms of location fragments pan and zoom the map to the given location regardless of the target value.
66+
i.e. `<map-a href="#1, 20, 30">...</map-a>` will pan to latitude: 30, longitude: 20 and zoom to level 1.
67+
68+
---
69+
70+
## Examples
71+
72+
### Styling Linked Features
73+
74+
To style linked features simply target the `map-a` class in your CSS, once a link is clicked you can target the
75+
`map-a-visited` class. See the example below:
76+
77+
```html
78+
<map-layer>
79+
<map-style>
80+
.map-a {
81+
stroke: red;
82+
}
83+
.map-a-visited {
84+
stroke: green;
85+
}
86+
</map-style>
87+
<map-feature>
88+
<map-properties>
89+
<h1>Basic</h1>
90+
</map-properties>
91+
<map-geometry>
92+
<map-a href="../externalMapML.mapml#2,-98,37">
93+
<map-polygon>
94+
<map-coordinates>2771 3106 2946 3113 2954 3210 2815 3192 2771 3106</map-coordinates>
95+
</map-polygon>
96+
</map-a>
97+
</map-geometry>
98+
</map-feature>
99+
</map-layer>
100+
```
101+
102+
### Wrapping a Feature Type + Location Fragment
103+
104+
```html
105+
<map-feature>
106+
<map-properties>
107+
<h1>Basic</h1>
108+
</map-properties>
109+
<map-geometry>
110+
<map-a href="../externalMapML.mapml#2,-98,37">
111+
<map-polygon>
112+
<map-coordinates>2771 3106 2946 3113 2954 3210 2815 3192 2771 3106</map-coordinates>
113+
</map-polygon>
114+
</map-a>
115+
</map-geometry>
116+
</map-feature>
117+
```
118+
119+
This will replace the current layer with the layer within externalMapML.mapml, once it's added the map will then goto
120+
zoomlevel: 2, longitude: -98, latitude: 37.
121+
122+
### Wrapping a point coordinate with `target="_blank"`
123+
124+
```html
125+
<map-feature>
126+
<map-properties>
127+
<h1>_blank target</h1>
128+
</map-properties>
129+
<map-geometry>
130+
<map-polygon>
131+
<map-coordinates>2771 3106 2946 3113 <map-a href="file.mapml" target="_blank"> 2954 3210 </map-a> 2815 3192 2771 3106</map-coordinates>
132+
</map-polygon>
133+
</map-geometry>
134+
</map-feature>
135+
```
136+
137+
In this example, a point will be created at (2954, 3210) which, once clicked, adds a new layer to the map.
138+
139+
### Nested `<map-a>` definition and behavior
140+
141+
```html
142+
<map-feature>
143+
<map-properties>
144+
<h1>Advanced Example</h1>
145+
</map-properties>
146+
<map-geometry>
147+
<map-a href="parent.mapml" target="_blank">
148+
<map-multipolygon>
149+
<map-polygon>
150+
<map-coordinates>2771 3106 2946 3113 <map-a href="webpage.html" target="_blank" type="text/mapml"> 2954 3210 </map-a> 2815 3192 2771 3106</map-coordinates>
151+
</map-polygon>
152+
<map-a href="nested.mapml" target="_top">
153+
<map-polygon>
154+
<map-coordinates>11 11 12 11 12 12 11 12</map-coordinates>
155+
</map-polygon>
156+
</map-a>
157+
</map-multipolygon>
158+
</map-a>
159+
</map-geometry>
160+
</map-feature>
161+
```
162+
In this advanced example there are multiple nested `<map-a>`. The simple behavior is, the closest `<map-a>` is the link
163+
behavior that the given location/area will adopt.
164+
165+
---

‎.github/skills/map-caption-markup/SKILLS.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
name: mapml-caption-markup
3+
description: Tells you how to correctly create and edit the markup for a <map-caption> element. Use it when generating MapML output markup in an HTML page, especially when generating a `<mapml-viewer>` element, to describe the map's purpose, if possible and known.
4+
---
5+
6+
This element is especially important for screen reader users to understand the purpose of a map. It is like 'alt-text' for a map.
7+
8+
The `<map-caption>` element is a child of `<mapml-viewer>` and is used to define
9+
a simple text string that is not visually rendered (at this time).
10+
The caption should be read by screen readers when the `<mapml-viewer>` is focused,
11+
as it generates the `<mapml-viewer aria-label="...">` value, if no aria-label
12+
has been specified by the HTML author. `<map-caption>` may be the first or last
13+
element child of `<mapml-viewer>`.

‎.github/skills/map-extent-markup/SKILL.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
---
2+
name: mapml-extent-markup
3+
description: Tells you how to correctly create and edit the markup for a <map-extent> element. Use it when generating MapML output markup in an HTML page.
4+
---
5+
6+
The `<map-extent>` element is a hypertext control that is associated to and represents the
7+
rectangle of the map viewport, from the user's perspective. Map authors use it
8+
to compose server requests for layer content. Requests are composed using
9+
URL templates processed by the browser as the map moves and requires new content
10+
to paint. The URL templates each contain one or more variable references, with each
11+
variable reference denoted by the name of the variable enclosed in braces `{}`.
12+
13+
Variables are created by the map author using the `<map-input>` element. There are
14+
several types of `<map-input>`, allowing the map author to reference the corners
15+
of the extent, its width and height, and its zoom.
16+
17+
An example of a `<map-extent>` element being used to load image tiles for a single
18+
URL template.
19+
20+
```html
21+
<mapml-viewer projection="OSMTILE" lat="10" lon="0" zoom="1">
22+
<map-layer label="OpenStreetMap" checked>
23+
<map-extent units="OSMTILE" checked hidden>
24+
<map-input name="z" type="zoom" value="18" min="0" max="18"></map-input>
25+
<map-input name="x" type="location" units="tilematrix" axis="column" min="0" max="262144"></map-input>
26+
<map-input name="y" type="location" units="tilematrix" axis="row" min="0" max="262144"></map-input>
27+
<map-link rel="tile" tref="https://tile.openstreetmap.org/{z}/{x}/{y}.png"></map-link>
28+
</map-extent>
29+
</map-layer>
30+
</mapml-viewer>
31+
```
32+
33+
## Attributes
34+
35+
### `units`
36+
37+
Specifies the projection of the tiles and other content that is expected from the
38+
server. If the projection value is a case-insensitive match of the `<mapml-viewer>`
39+
`projection` attribute, the extent will be disabled in the layer control, and will
40+
not be displayed on the map, nor content fetched.
41+
42+
Defined values of `units` include:
43+
44+
| Projection | Description |
45+
|-------------- |-------------------------------------------------------- |
46+
| OSMTILE | Web Mercator, with 256px x 256px tiles recursively defined inside a square bounds at zoom = 0|
47+
| WGS84 | Pseudo plate carrée, with 256px x 256px tiles. Zoom = 0 contains two tiles in two columns, with their origin at -180,90. False easting and northing (pcrs) values inside the projection bounds correspond to longitude and latitude, respectively. |
48+
| CBMTILE | Lambert Conformal Conic, with 256px x 256px tiles. Zoom levels chosen by scale denominator, so tiles do not nest.|
49+
50+
Author-defined values of `units` are possible, using the [Custom projections API](../../api/mapml-viewer-api/#definecustomprojectionoptions)
51+
52+
The `units` attribute is required and can't be changed.
53+
54+
---
55+
56+
### `label`
57+
58+
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.
59+
60+
---
61+
62+
### `checked`
63+
64+
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).
65+
66+
---
67+
68+
### `hidden`
69+
70+
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.
71+
72+
---
73+
74+
### `opacity`
75+
76+
The `opacity` attribute is used to set the initial opacity of the `<map-extent>` element.
77+
Valid `opacity` values range from from "0.0" to "1.0" with strictly one demical place and are reflected in the extent settings
78+
opacity input slider control. When the `opacity` attribute is not present, the opacity is set to "1.0" by default.
79+
80+
---
81+
82+
## Examples
83+
84+
### Multiple Extent
85+
86+
The following example shows multiple `<map-extent>` elements in a layer. The different elements can be selected from the three dots menu of the Basemap layer.
87+
88+
```html
89+
<mapml-viewer projection="OSMTILE" zoom="2" lat="53.331" lon="-91.667" controls>
90+
<!-- Change Basemap using the three dots menu of the basemap layer -->
91+
<map-layer label="Basemap" checked="">
92+
<!-- This extent will be hidden in the layer control since no label is provided -->
93+
<map-extent units="OSMTILE" checked>
94+
<map-input name="TileMatrix" type="zoom" value="18" min="0" max="18"></map-input>
95+
<map-input name="TileCol" type="location" units="tilematrix" axis="column" min="0" max="262144"></map-input>
96+
<map-input name="TileRow" type="location" units="tilematrix" axis="row" min="0" max="262144"></map-input>
97+
<map-link rel="tile" tref="https://server.arcgisonline.com/arcgis/rest/services/World_Imagery/MapServer/WMTS/tile/1.0.0/World_Imagery/default/default028mm/{TileMatrix}/{TileRow}/{TileCol}.jpg"></map-link>
98+
</map-extent>
99+
<map-extent label="Nat Geo" units="OSMTILE" checked>
100+
<map-input name="TileMatrix" type="zoom" value="18" min="0" max="18"></map-input>
101+
<map-input name="TileCol" type="location" units="tilematrix" axis="column" min="0" max="262144"></map-input>
102+
<map-input name="TileRow" type="location" units="tilematrix" axis="row" min="0" max="262144"></map-input>
103+
<map-link rel="tile" tref="https://server.arcgisonline.com/arcgis/rest/services/NatGeo_World_Map/MapServer/WMTS/tile/1.0.0/NatGeo_World_Map/default/default028mm/{TileMatrix}/{TileRow}/{TileCol}.jpg"></map-link>
104+
</map-extent>
105+
<map-extent label="Imagery" units="OSMTILE" checked>
106+
<map-input name="TileMatrix" type="zoom" value="18" min="0" max="18"></map-input>
107+
<map-input name="TileCol" type="location" units="tilematrix" axis="column" min="0" max="262144"></map-input>
108+
<map-input name="TileRow" type="location" units="tilematrix" axis="row" min="0" max="262144"></map-input>
109+
<map-link rel="tile" tref="https://server.arcgisonline.com/arcgis/rest/services/World_Imagery/MapServer/WMTS/tile/1.0.0/World_Imagery/default/default028mm/{TileMatrix}/{TileRow}/{TileCol}.jpg"></map-link>
110+
<map-link rel="tile" tref="https://services.arcgisonline.com/arcgis/rest/services/Reference/World_Boundaries_and_Places/MapServer/WMTS/tile/1.0.0/Reference_World_Boundaries_and_Places/default/default028mm/{TileMatrix}/{TileRow}/{TileCol}.png"></map-link>
111+
</map-extent>
112+
</map-layer>
113+
</mapml-viewer>
114+
```
115+
116+
### WMS Request
117+
118+
The following example shows a Web Map Service Request using `<map-link>` to request map images.
119+
120+
```html
121+
<mapml-viewer projection="OSMTILE" zoom="4" lat="53.331" lon="-91.667" controls>
122+
<map-layer label="Toporama" checked="">
123+
<map-extent xmlns="http://www.w3.org/1999/xhtml" units="OSMTILE" checked>
124+
<!-- URL parameters for WMS Request -->
125+
<map-input name="z" type="zoom" value="18" min="4" max="18"></map-input>
126+
<map-input name="w" type="width"></map-input>
127+
<map-input name="h" type="height"></map-input>
128+
<map-input name="xmin" type="location" units="pcrs" position="top-left" axis="easting" min="-2.003750834E7" max="2.003750834E7"></map-input>
129+
<map-input name="ymin" type="location" units="pcrs" position="bottom-left" axis="northing" min="-2.003750834E7" max="2.003750834E7"></map-input>
130+
<map-input name="xmax" type="location" units="pcrs" position="top-right" axis="easting" min="-2.003750834E7" max="2.003750834E7"></map-input>
131+
<map-input name="ymax" type="location" units="pcrs" position="top-left" axis="northing" min="-2.003750834E7" max="2.003750834E7"></map-input>
132+
<!-- Web Map Service requesting image -->
133+
<map-link rel="image" tref="https://wms.ess-ws.nrcan.gc.ca/wms/toporama_en?SERVICE=WMS&amp;REQUEST=GetMap&amp;FORMAT=image/jpeg&amp;TRANSPARENT=FALSE&amp;STYLES=&amp;VERSION=1.3.0&amp;LAYERS=WMS-Toporama&amp;WIDTH={w}&amp;HEIGHT={h}&amp;CRS=EPSG:3857&amp;BBOX={xmin},{ymin},{xmax},{ymax}&amp;m4h=t"></map-link>
134+
</map-extent>
135+
</map-layer>
136+
</mapml-viewer>
137+
```

0 commit comments

Comments
 (0)