Skip to content

Commit 0e458f2

Browse files
matthewhall78matthewhall78
authored
Create Adding-new-base-layers-to-map-component.md
1 parent 4365f31 commit 0e458f2

1 file changed

Lines changed: 125 additions & 0 deletions

File tree

‎docs/Components/Custom/Adding-new-base-layers-to-map-component.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# Custom Base Maps for the Map Component
2+
3+
**Last updated:** 2025-08-28\
4+
**Audience:** Form designers using the CHEFS Map Component\
5+
**Purpose:** Show how to add **custom base map layers** via `availableBaseLayersCustom`, with tested examples and troubleshooting.
6+
7+
---
8+
9+
## Overview
10+
11+
The Map Component supports adding custom base map layers so you can use OpenStreetMap, ESRI imagery, or the BC Government basemap in your forms. Custom layers are defined in the JSON property `availableBaseLayersCustom`.
12+
13+
---
14+
15+
## Configuration Schema
16+
17+
Add entries to the `availableBaseLayersCustom` array. Each entry controls one base layer.
18+
19+
```json
20+
"availableBaseLayersCustom": [
21+
{
22+
"label": "",
23+
"url": "",
24+
"attribution": "",
25+
"enabled": true
26+
}
27+
]
28+
```
29+
30+
### Field Definitions
31+
32+
| Field | Description | Requirements / Examples |
33+
| --------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
34+
| **label** | Name shown in the base map selector dropdown. | Keep it short and descriptive. Examples: `"ESRI World Imagery"`, `"BC Gov Basemap"` |
35+
| **url** | XYZ tile URL template for fetching tiles. Must include `{z}/{x}/{y}` (or `{z}/{y}/{x}` for some services). | Examples:` ``https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}``https://maps.gov.bc.ca/arcgis/rest/services/province/web_mercator_cache/MapServer/tile/{z}/{y}/{x} ` |
36+
| **attribution** | Required provider credit shown on the map. | Examples ESRI: `Tiles © Esri — Source: Esri, Maxar, Earthstar Geographics, and others`BC Gov: `© GeoBC, DataBC, TomTom, © OpenStreetMap contributors` |
37+
| **enabled** | Whether the base map appears by default on load. | Set the layers to `true` that you wish for your users to be able to switch to or set to `false` if you want to have the configuration available but hide it from the users. |
38+
39+
---
40+
41+
## Ready‑to‑Use Examples
42+
43+
> You can copy these directly into your form's configuration. Adjust the `enabled` flag (true or false) to show or hide it for the people using your form.
44+
45+
```json
46+
"availableBaseLayersCustom": [
47+
{
48+
"label": "ESRI World Imagery",
49+
"url": "https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}",
50+
"attribution": "Tiles © Esri — Source: Esri, Maxar, Earthstar Geographics, and the GIS User Community",
51+
"enabled": true
52+
},
53+
{
54+
"label": "BC Gov Basemap",
55+
"url": "https://maps.gov.bc.ca/arcgis/rest/services/province/web_mercator_cache/MapServer/tile/{z}/{y}/{x}",
56+
"attribution": "© GeoBC, DataBC, TomTom, © OpenStreetMap contributors",
57+
"enabled": true
58+
}
59+
]
60+
```
61+
62+
---
63+
64+
## Provider Catalogue (Quick Reference)
65+
66+
| Provider | URL Template (XYZ) | Attribution | Notes |
67+
| --------------------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
68+
| **ESRI World Imagery** | `https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}` | `Tiles © Esri — Source: Esri, Maxar, Earthstar Geographics, and others` | High‑quality satellite imagery. Check Esri terms for usage limits. |
69+
| **BC Gov Basemap (Web Mercator Cache)** | `https://maps.gov.bc.ca/arcgis/rest/services/province/web_mercator_cache/MapServer/tile/{z}/{y}/{x}` | `© GeoBC, DataBC, TomTom, © OpenStreetMap contributors` | Production endpoint; good coverage for BC. |
70+
71+
> If you add other providers (e.g., Mapbox, Google), they may require API keys and different URLs. Ensure licensing and attributions are compliant.
72+
73+
---
74+
75+
## Best Practices
76+
77+
- **Always include attribution.** Many providers legally require it.
78+
- **Use official/production endpoints.** Avoid third‑party mirrors that may break or violate terms.
79+
- **Keep labels concise.** Long labels clutter the selector.
80+
- **Enable one default.** Only one `enabled: true` layer is recommended at a time.
81+
- **Test across zoom levels.** Verify at low (z≈3–5), mid (z≈8–12), and high (z≈15–18) zooms.
82+
83+
### Performance & Cost Tips
84+
85+
- Prefer **raster caches** (like the BC Web Mercator Cache) for fast loads and fewer tile requests.
86+
- Consider **tile request throttling** or client‑side caching if embedding on high‑traffic forms.
87+
- If you anticipate heavy traffic, evaluate a **paid/hosted tile service** with SLAs to avoid downtime and rate‑limits.
88+
- For OSM, be a good citizen: keep requests modest; consider a **self‑hosted tile cache** if volume grows (saves money vs. per‑request vendors over time).
89+
90+
---
91+
92+
## Troubleshooting
93+
94+
**Blank map**
95+
96+
- The URL might not be an XYZ tile endpoint. Ensure the path ends with `/tile/{z}/{y}/{x}` (ArcGIS) or includes `{z}/{x}/{y}` (OSM‑style).
97+
- For BC Gov, use the `province/web_mercator_cache` service path on the **production** domain.
98+
99+
**Tiles fail only at certain zoom levels**
100+
101+
- The service may not support those zooms. Try zooms known to be available (e.g., z=0–19 for many caches).
102+
- Check for typos in `{x}/{y}` ordering.
103+
104+
**Slow loading**
105+
106+
- Network/CDN hiccups or rate limits. Try again, or pick a closer endpoint/CDN‑backed service.
107+
108+
**Attribution not showing**
109+
110+
- Ensure the `attribution` field has text and the Map Component is configured to display attributions (it is by default in CHEFS).
111+
112+
---
113+
114+
## Appendix: Custom Base Map Template Syntax
115+
116+
```json
117+
"availableBaseLayersCustom": [
118+
{
119+
"label": "<Your Label>",
120+
"url": "<https://.../{z}/{x}/{y} or /{z}/{y}/{x}>",
121+
"attribution": "<Required provider credit>",
122+
"enabled": true
123+
}
124+
]
125+
```

0 commit comments

Comments
 (0)