Skip to content

Commit 876a208

Browse files
prushforthprushfor
prushforth
and
prushfor
authored
Add initial description of pmtilesRules new required structure (#165)
* Add initial description of pmtilesRules new required structure * Update the pmtiles stylesheet description to add the pmtilesRulesReady promise-valued export which is now required due to adding icon sheets support * Add fr translation of changes for pmtiles style structure --------- Co-authored-by: prushfor <[email protected]>
1 parent 0407380 commit 876a208

File tree

2 files changed

+114
-29
lines changed

2 files changed

+114
-29
lines changed

‎docs/user-guide/creating-styles.md

+61-15
Original file line numberDiff line numberDiff line change
@@ -25,25 +25,65 @@ Working examples of `<mapml-viewer>` usage of themes and styles are [available o
2525

2626
## How to create a stylesheet module
2727

28-
A pmtiles stylesheet used in the MapML polyfill is a JavaScript module source file which exports a
29-
single symbol, which **must be** named `pmtilesRules`:
28+
A pmtiles stylesheet used in the MapML polyfill is a JavaScript module source file which exports
29+
two symbols, a `pmtilesRules` Map instance, and a Promise-valued `pmtilesRulesReady`, which is resolved when
30+
the required Sheet is loaded, per the following example:
3031

3132
```javascript
33+
const sheet = new protomapsL.Sheet(`
34+
<html>
35+
<body>
36+
<svg id="icon_0" width="99px" height="97px" xmlns="http://www.w3.org/2000/svg">
37+
<image href="data:image/svg+xml;base64,PHN2ZyBpZD0iaWNvbl82NCIgd2lkdGg9IjE2cHgiIGhlaWdodD0iMTZweCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KICAgICAgPGltYWdlIGhyZWY9ImRhdGE6aW1hZ2UvcG5nO2Jhc2U2NCxpVkJPUncwS0dnb0FBQUFOU1VoRVVnQUFBQkFBQUFBUUNBWUFBQUFmOC85aEFBQUFDWEJJV1hNQUFBN0VBQUFPeEFHVkt3NGJBQUFBMlVsRVFWUjRuTldQTVdvQ1lSQ0Z2MElDZ2xZaFZnRUwzZmNyZGlsczBteVJUdkFLa2xaSXdKM2ZpTjE2aGhoeUFCRkVjZ2J2WUtFbmtCUkpiNWtFSlRheXNNdFd5WVBYRFBPOW1RZC9YcjVHSlRkc1Rhb21wdm12TzBZbVB1T1FRcjRQeE5yRXR3L29wQzdITFM1TVRFd3NEdmFPdHdOOERCRGIwenh5eklkMWJoSkQraTFLWHN4T1lJSjN2a0dZM2ozZ1BnRmVqUnRjWnVvK2ROeWVCM2l4Skt0TXZQeUNtMGc4bS9neXNYOXlsRlBoT0tUZ3hZYzVYZ2ZYRkkrVnhKMkpkeE85MUlDQmFFZU83dm44b2M2VkQzak1YT1AvNkFmS0Ywd3dXeU9Oc3dBQUFBQkpSVTVFcmtKZ2dnPT0iIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIvPgogICAgPC9zdmc+" width="99" height="97" />
38+
</svg>
39+
</body>
40+
</html>
41+
`);
3242
const pmtilesRules = new Map();
33-
...
34-
pmtilesRules.set(
35-
'https://maps4html.org/experiments/vector-tiles/pmtiles/spearfish.pmtiles?theme=light',
36-
{ theme: { theme: 'light' } }
37-
);
38-
...
39-
export { pmtilesRules };
43+
const pmtilesRulesReady = sheet.load().then(() => {
44+
...
45+
pmtilesRules.set(
46+
'https://maps4html.org/experiments/vector-tiles/pmtiles/spearfish.pmtiles?theme=light',
47+
{ theme: { theme: 'light' } }
48+
);
49+
...
50+
return pmtilesRules;
51+
});
52+
export { pmtilesRules, pmtilesRulesReady };
4053
```
4154
:::tip
4255

4356
Pre-defined themes that you can use include: `light`, `dark`, `white`, `grayscale` and `black`. You should include the theme name in the URL template as a parameter (even though it is not required by the pmtiles or mvt resource), so that the URL template can be made unique and distinct from other pmtilesRules keys' use of the same pmtiles or mvt resource.
4457

4558
:::
4659

60+
## The required structure of the pmtiles 'stylesheet'
61+
62+
The stylesheet module must export two symbols: `pmtilesRulesReady` and `pmtilesRules`.
63+
64+
The `pmtilesRulesReady` export must be a Promise that signals to the MapML library that
65+
the pmttilesRules export is fully defined and ready for rendering. If your stylesheet
66+
uses IconSymbolizer, it may be convenient to perform resource loading and processing
67+
via the asynchronous Sheet.load() function, which itself returns a Promise object that
68+
may be returned by your stylesheet as the pmtilesRulesReady value, as
69+
shown in the example above. If your stylesheet does not require icons, it should
70+
be possible to assign an already-resolved promise as the value of pmtilesRulesReady,
71+
via Promise.resolve(), and return that.
72+
73+
```javascript
74+
const pmtilesRules = new Map();
75+
// a Map requires a key, in this case the absolute URL of the data source (but,
76+
// can also be the absolute value of the URL _template_ for the data source),
77+
// and an object to be mapped by the key, in this case, an object with a `theme`
78+
// member, whose value is itself an object with a `theme` member.
79+
pmtilesRules.set(
80+
'https://maps4html.org/experiments/vector-tiles/pmtiles/spearfish.pmtiles?theme=light',
81+
{ theme: { theme: 'light' } }
82+
);
83+
const pmtilesRulesReady = Promise.resolve();
84+
export { pmtilesRules, pmtilesRulesReady };
85+
```
86+
4787
The `pmtilesRules` export must be a [JavaScript Map-type object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map), structured as follows:
4888

4989
- must have a unique URL template string key that will be used on the web to identify a set of rules
@@ -77,30 +117,36 @@ class SpearfishSymbolizer {
77117
context.fill();
78118
}
79119
}
120+
// the only other pmtilesRules keyed value besides `theme` that is supported is
121+
// an object with a `rules` member. The value of the `rules` member is an object
122+
// that has two optional array-valued members, `PAINT_RULES` and `LABEL_RULES`.
80123
const pmtilesRules = new Map();
81124
pmtilesRules.set(
82125
'http://localhost:8080/geoserver/gwc/service/wmts/rest/spearfish/OSMTILE/{z}/{y}/{x}?format=application/vnd.mapbox-vector-tile',
83126
{
127+
// PAINT_RULES and LABEL_RULES are each an array of dataLayer/symbolizer objects, with optional
128+
// function-valued `filter` member (filter is a member of the same object as
129+
// dataLayer and symbolizer, not a property of those objects).
84130
rules: {
85131
PAINT_RULES: [
86132
{
87133
dataLayer: 'streams',
88-
symbolizer: new M.protomapsL.LineSymbolizer({ color: 'steelblue', width: 2 })
134+
symbolizer: new protomapsL.LineSymbolizer({ color: 'steelblue', width: 2 })
89135
},
90136
{
91137
dataLayer: 'roads',
92-
symbolizer: new M.protomapsL.LineSymbolizer({ color: 'maroon', width: 2 })
138+
symbolizer: new protomapsL.LineSymbolizer({ color: 'maroon', width: 2 })
93139
},
94140
{
95141
dataLayer: 'restricted',
96-
symbolizer: new M.protomapsL.PolygonSymbolizer({
142+
symbolizer: new protomapsL.PolygonSymbolizer({
97143
fill: 'red',
98144
opacity: 0.5
99145
})
100146
},
101147
{
102148
dataLayer: 'restricted',
103-
symbolizer: new M.protomapsL.LineSymbolizer({ color: 'red', width: 2 })
149+
symbolizer: new protomapsL.LineSymbolizer({ color: 'red', width: 2 })
104150
},
105151
{
106152
dataLayer: 'archsites',
@@ -120,7 +166,7 @@ pmtilesRules.set(
120166
LABEL_RULES: [
121167
{
122168
dataLayer: 'archsites',
123-
symbolizer: new M.protomapsL.CenteredTextSymbolizer({
169+
symbolizer: new protomapsL.CenteredTextSymbolizer({
124170
labelProps: ['str1'],
125171
fill:'white',
126172
width:2,
@@ -139,7 +185,7 @@ export { pmtilesRules };
139185

140186
## Available imported symbols from protomaps-leaflet
141187

142-
The following imports from protomaps-leaflet are available on the `M.protomapsL` global variable e.g. `M.protomapsL.CenteredSymbolizer`, for use by your stylesheets:
188+
The following imports from protomaps-leaflet are available on the `protomapsL` import, for use by your stylesheets:
143189

144190
```javascript
145191
/*

‎i18n/fr/docusaurus-plugin-content-docs/current/user-guide/creating-styles.md

+53-14
Original file line numberDiff line numberDiff line change
@@ -34,17 +34,29 @@ Des exemples pratiques de l'utilisation des thèmes et des styles par `<mapml-vi
3434

3535
## Comment créer un module de feuille de style
3636

37-
Une feuille de style pmtiles utilisée dans le polyfill MapML est un fichier source de module JavaScript qui exporte un seul symbole, qui doit être nommé `pmtilesRules` :
37+
Une feuille de style pmtiles utilisée dans le polyfill MapML est un fichier source de module JavaScript qui exporte deux symboles, une instance de « Map “ `pmtilesRules`, et une promesse `pmtilesRulesReady`, qui est résolue lorsque le « Sheet » requis est chargé, selon l'exemple suivant :
3838

3939
```javascript
40+
const sheet = new protomapsL.Sheet(`
41+
<html>
42+
<body>
43+
<svg id="icon_0" width="99px" height="97px" xmlns="http://www.w3.org/2000/svg">
44+
<image href="data:image/svg+xml;base64,PHN2ZyBpZD0iaWNvbl82NCIgd2lkdGg9IjE2cHgiIGhlaWdodD0iMTZweCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KICAgICAgPGltYWdlIGhyZWY9ImRhdGE6aW1hZ2UvcG5nO2Jhc2U2NCxpVkJPUncwS0dnb0FBQUFOU1VoRVVnQUFBQkFBQUFBUUNBWUFBQUFmOC85aEFBQUFDWEJJV1hNQUFBN0VBQUFPeEFHVkt3NGJBQUFBMlVsRVFWUjRuTldQTVdvQ1lSQ0Z2MElDZ2xZaFZnRUwzZmNyZGlsczBteVJUdkFLa2xaSXdKM2ZpTjE2aGhoeUFCRkVjZ2J2WUtFbmtCUkpiNWtFSlRheXNNdFd5WVBYRFBPOW1RZC9YcjVHSlRkc1Rhb21wdm12TzBZbVB1T1FRcjRQeE5yRXR3L29wQzdITFM1TVRFd3NEdmFPdHdOOERCRGIwenh5eklkMWJoSkQraTFLWHN4T1lJSjN2a0dZM2ozZ1BnRmVqUnRjWnVvK2ROeWVCM2l4Skt0TXZQeUNtMGc4bS9neXNYOXlsRlBoT0tUZ3hZYzVYZ2ZYRkkrVnhKMkpkeE85MUlDQmFFZU83dm44b2M2VkQzak1YT1AvNkFmS0Ywd3dXeU9Oc3dBQUFBQkpSVTVFcmtKZ2dnPT0iIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIvPgogICAgPC9zdmc+" width="99" height="97" />
45+
</svg>
46+
</body>
47+
</html>
48+
`);
4049
const pmtilesRules = new Map();
41-
...
42-
pmtilesRules.set(
43-
'https://maps4html.org/experiments/vector-tiles/pmtiles/spearfish.pmtiles?theme=light',
44-
{ theme: { theme: 'light' } }
45-
);
46-
...
47-
export { pmtilesRules };
50+
const pmtilesRulesReady = sheet.load().then(() => {
51+
...
52+
pmtilesRules.set(
53+
'https://maps4html.org/experiments/vector-tiles/pmtiles/spearfish.pmtiles?theme=light',
54+
{ theme: { theme: 'light' } }
55+
);
56+
...
57+
return pmtilesRules;
58+
});
59+
export { pmtilesRules, pmtilesRulesReady };
4860
```
4961
:::tip
5062

@@ -54,6 +66,26 @@ rendu unique et distinct des autres clés `pmtilesRules` utilisant la même ress
5466

5567
:::
5668

69+
## La structure requise de la « feuille de style » de pmtiles
70+
71+
Le module de feuille de style doit exporter deux symboles : `pmtilesRulesReady` et `pmtilesRules`.
72+
73+
L'export `pmtilesRulesReady` doit être une promesse qui signale à la bibliothèque MapML que l'export pmttilesRules est entièrement défini et prêt pour le rendu. Si votre feuille de style utilise IconSymbolizer, il peut être pratique d'effectuer le chargement et le traitement des ressources via la fonction asynchrone Sheet.load(), qui renvoie elle-même un objet Promise qui peut être renvoyé par votre feuille de style en tant que valeur pmtilesRulesReady, comme dans l'exemple ci-dessus. Si votre feuille de style ne nécessite pas d'icônes, il devrait être possible d'assigner un objet Promise déjà résolue comme valeur de pmtilesRulesReady, via Promise.resolve(), et de la retourner.
74+
75+
```javascript
76+
const pmtilesRules = new Map() ;
77+
// une Map nécessite une clé, dans ce cas l'URL absolue de la source de données (mais,
78+
// peut aussi être la valeur absolue de l'URL _template_ de la source de données),
79+
// et un objet à mapper par la clé, dans ce cas, un objet avec un membre `theme`
80+
// dont la valeur est elle-même un objet avec un membre `theme`.
81+
pmtilesRules.set(
82+
'https://maps4html.org/experiments/vector-tiles/pmtiles/spearfish.pmtiles?theme=light',
83+
{ theme : { theme : 'light' } }
84+
) ;
85+
const pmtilesRulesReady = Promise.resolve() ;
86+
export { pmtilesRules, pmtilesRulesReady } ;
87+
```
88+
5789
L'export `pmtilesRules` doit être un [JavaScript Map-type object](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Global_Objects/Map), structuré comme suit :
5890

5991
- doit avoir une clé unique de type « URL template string » qui sera utilisée sur le web pour identifier un ensemble de règles
@@ -87,30 +119,37 @@ class SpearfishSymbolizer {
87119
context.fill();
88120
}
89121
}
122+
// la seule autre valeur de clé pmtilesRules en plus de `theme` qui est supportée est
123+
// un objet avec un membre `rules`. La valeur du membre `rules` est un objet
124+
// qui a deux membres optionnels de type tableau, `PAINT_RULES` et `LABEL_RULES`.
90125
const pmtilesRules = new Map();
91126
pmtilesRules.set(
92127
'http://localhost:8080/geoserver/gwc/service/wmts/rest/spearfish/OSMTILE/{z}/{y}/{x}?format=application/vnd.mapbox-vector-tile',
93128
{
129+
// PAINT_RULES et LABEL_RULES sont chacun un tableau d'objets dataLayer/symbolizer,
130+
// avec un membre facultatif `filter` à valeur de fonction (le filtre est
131+
// membre du même objet que celui de l'objet dataLayer et symbolizer, et non pas
132+
// une propriété de ces objets).
94133
rules: {
95134
PAINT_RULES: [
96135
{
97136
dataLayer: 'streams',
98-
symbolizer: new M.protomapsL.LineSymbolizer({ color: 'steelblue', width: 2 })
137+
symbolizer: new protomapsL.LineSymbolizer({ color: 'steelblue', width: 2 })
99138
},
100139
{
101140
dataLayer: 'roads',
102-
symbolizer: new M.protomapsL.LineSymbolizer({ color: 'maroon', width: 2 })
141+
symbolizer: new protomapsL.LineSymbolizer({ color: 'maroon', width: 2 })
103142
},
104143
{
105144
dataLayer: 'restricted',
106-
symbolizer: new M.protomapsL.PolygonSymbolizer({
145+
symbolizer: new protomapsL.PolygonSymbolizer({
107146
fill: 'red',
108147
opacity: 0.5
109148
})
110149
},
111150
{
112151
dataLayer: 'restricted',
113-
symbolizer: new M.protomapsL.LineSymbolizer({ color: 'red', width: 2 })
152+
symbolizer: new protomapsL.LineSymbolizer({ color: 'red', width: 2 })
114153
},
115154
{
116155
dataLayer: 'archsites',
@@ -130,7 +169,7 @@ pmtilesRules.set(
130169
LABEL_RULES: [
131170
{
132171
dataLayer: 'archsites',
133-
symbolizer: new M.protomapsL.CenteredTextSymbolizer({
172+
symbolizer: new protomapsL.CenteredTextSymbolizer({
134173
labelProps: ['str1'],
135174
fill:'white',
136175
width:2,
@@ -149,7 +188,7 @@ export { pmtilesRules };
149188

150189
## Symboles importés disponibles à partir de protomaps-leaflet
151190

152-
Les importations suivantes de protomaps-leaflet sont disponibles sur la variable globale `M.protomapsL`, par exemple `M.protomapsL.CenteredSymbolizer`, pour être utilisées par vos feuilles de style :
191+
Les importations suivantes de protomaps-leaflet sont disponibles dans l'importation `protomapsL`, pour être utilisées par vos feuilles de style :
153192

154193
```javascript
155194
/*

0 commit comments

Comments
 (0)