Webmaps update

scripts/markdown_style.bash

@@ -23,7 +23,7 @@ for i in \
 do
   echo "Checking for $i"
   # exclude HTML tags inside QGIS expressions in documentation
-  A1=`grep --line-number -r -e "$i"  $SCRIPT_DIR/../src/ --include \*.md | grep -v 'expression.evaluate'`
+  A1=`grep --line-number -r -e "$i"  $SCRIPT_DIR/../src/ --include \*.md | grep -v 'expression.evaluate' | grep -v 'app.merginmaps.com/maps/'` | grep -v 'app.merginmaps.com/app/ogc'
   if [ ! -z "$A1" ]
   then
    echo $A1

scripts/wordlist.txt

@@ -104,6 +104,7 @@ OSM
 OSTN
 OGR
 Ok
+OpenLayers
 OpenMapTiles
 OpenStreetMap
 onboarding
@@ -208,6 +209,7 @@ hotline
 html
 http
 https
+iframe
 interoperable
 integration
 integrations
@@ -293,6 +295,8 @@ vCPUS
 xcf
 xyz
 yml
+webmap
+WebMap
 webmaps
 WebMaps
 webp
@@ -313,3 +317,8 @@ pre
 env
 IDP
 enum
+OGC
+DOM
+CDN
+submodules
+JavaScript

src/.vitepress/sidebar/en.js

@@ -31,14 +31,20 @@ export default {
         { text: 'Member Roles and Permissions', link: '/manage/permissions/' },
         { text: 'Synchronisation', link: '/manage/synchronisation/' },
         { text: 'Mergin Maps Project', link: '/manage/project/' },
+        { text: 'Webmaps',
+        items: [
+           { text: 'Overview', link: '/manage/dashboard-maps/' },
+           { text: 'Sharing and Embedding', link: '/manage/webmaps-sharing/' },
+           { text: 'Custom Applications (with AI) 🧪', link: '/manage/webmaps-applications/' },
+           { text: 'Troubleshooting', link: '/manage/webmaps-troubleshooting/' }
+        ] },
         { text: 'How to Create a New Project', link: '/manage/create-project/' },
         { text: 'How to Share, Transfer or Delete Projects', link: '/manage/project-advanced/' },
         { text: 'How to Delete Files', link: '/manage/delete-files/' },
         { text: 'How to Deploy Revised Projects', link: '/manage/deploy-new-project/' },
         { text: 'How to Recover Missing Data', link: '/manage/missing-data/' },
         { text: 'Mergin Maps QGIS Plugin Overview', link: '/manage/plugin/' },
         { text: 'Mergin Maps Dashboard', link: '/manage/dashboard/' },
-        { text: 'Webmaps', link: '/manage/dashboard-maps/' },
         { text: 'Project History and Versions', link: '/manage/project-history/' },
         { text: 'Selective Synchronisation', link: '/manage/selective_sync/' }
       ] },
@@ -94,8 +100,8 @@ export default {
         collapsed: true,
         items: [
            { text: 'Use Cases Overview', link: '/layer/use-cases/' },
-	   { text: 'How to Open a File', link: '/layer/open-file/' },
-	   { text: 'How to Use Hyperlinks', link: '/layer/external-link/' },
+           { text: 'How to Open a File', link: '/layer/open-file/' },
+           { text: 'How to Use Hyperlinks', link: '/layer/external-link/' },
            { text: 'How to Open a Link to a Navigation App', link: '/layer/link-to-navigation/' },
            { text: 'How to Use a Phone Call Link', link: '/layer/phone-call-link/' },
            { text: 'How to Link Multiple Records to One Feature (1-N Relations)', link: '/layer/one-to-n-relations/' },

src/index.md

@@ -45,14 +45,16 @@ The ecosystem consist of various components:
 - [Member Roles and Permissions](./manage/permissions/)
 - [Synchronisation](./manage/synchronisation/)
 - [Mergin Maps Project](./manage/project/)
+- [Webmaps](./manage/dashboard-maps/)
+   - [Sharing and Embedding](./manage/webmaps-sharing/)
+   - [Troubleshooting](./manage/webmaps-troubleshooting/)
 - [How to Create a New Project](./manage/create-project/)
 - [How to Share, Transfer or Delete Projects](./manage/project-advanced/)
 - [How to Delete Files](./manage/delete-files)
 - [How to Deploy Revised Projects](./manage/deploy-new-project/)
 - [How to Recover Missing Data](./manage/missing-data/)
 - [<QGISPluginName /> Overview](./manage/plugin/)
 - [Mergin Maps Dashboard](./manage/dashboard/)
-- [Webmaps](./manage/dashboard-maps/)
 - [Project History and Versions](./manage/project-history/)
 - [Selective Synchronisation](./manage/selective_sync/)
 

src/manage/dashboard-maps/index.md

@@ -1,9 +1,9 @@
 ---
 description: Webmaps display the map overview of your project's spatial data directly in your web browser, on Mergin Maps dashboard.
+outline: deep
 ---
 
-# Webmaps
-[[toc]]
+# Webmaps Overview
 
 The spatial data of your project can be displayed and explored in the **Map** tab of the project on the <DashboardShortLink />. As an early access feature, they can also be [shared via URL](#sharing-maps-via-url).
 
@@ -12,45 +12,46 @@ The spatial data of your project can be displayed and explored in the **Map** ta
 :::tip Usage details
 Webmaps are available for <MainPlatformNameLink /> cloud and <EnterprisePlatformNameLink /> users.
 
-Webmaps are **not** available for <CommunityPlatformNameLink />.
+Webmaps are **not** available for <CommunityPlatformNameLink /> at this point.
 :::
 
-## Webmaps content
+## Project layers
+On the webmaps, you will see your survey layers or raster layers that are [packaged](../project/#packaging-qgis-project) with the project. The default extent of maps is defined by the [extent set in the QGIS project](../../gis/features/#project-extent).
 
-On the webmaps, you will see your survey layers or raster layers that are [packaged](../project/#packaging-qgis-project) with the project. Other layers, such as online [background maps](../../gis/settingup_background_map/#background-maps) or PostgreSQL layers are not displayed. The extent of maps is defined by the [extent set in the QGIS project](../../gis/features/#project-extent).
+All maps on the <DashboardShortLink /> by default use [<MainPlatformName /> vector tile service](../../gis/settingup_background_map/#online-services-1) as a background map.
 
-All maps on the <DashboardShortLink /> use [<MainPlatformName /> vector tile service](../../gis/settingup_background_map/#online-services-1) as a background map.
+The webmap is refreshed automatically, you will see the latest version of your project all the time, even without refreshing the web page.
 
-The content of the maps and of the **Layers** panel is refreshed after every synchronisation of the project. This means you should always see your current spatial data here.
+The **Layers** panel lists all available layers displayed on the map, together with their legend as defined in QGIS. The eye button next to the layer name controls the visibility of layers. If you have defined map themes in your project, these are visible on top of the layers panel.
 
-The **Layers** panel lists all layers displayed on the map. The check button :white_check_mark: controls the visibility of layers.
+![Mergin Maps webmaps toggle layer visibility](./webmaps-toggle-layer-visibility.webp "Mergin Maps webmaps toggle layer visibility")
 
-Click on a feature on the map to display its properties.
+You can also switch [Map themes](../../gis/setup_themes/) defined in the project:
+![Mergin Maps webmaps toggle layer visibility](./webmaps-map-themes.webp "Mergin Maps webmaps toggle layer visibility")
 
-![Mergin Maps dashboard maps](./dashboard-map-properties.webp "Mergin Maps dashboard maps")
-
-## Sharing maps via URL <Badge text="early access" type="warning"/>
-::: tip Early access feature
-Map sharing is in early access. If you would like to try it out, fill in [this form](https://wishlist.merginmaps.com/f/share-maps-via-url) to gain access to this feature.
+Click on a feature on the map to display its attributes.
 
-Try out this <AppDomainNameLink id="maps/grDTleg8yCdSracIxs-hmFIGdDs" desc="example link"/> to see how shared maps work.
-:::
+![Mergin Maps dashboard maps](./dashboard-map-properties.webp "Mergin Maps dashboard maps")
 
-Webmaps can be shared via URL. [Admins or owners](../permissions/) can enable map sharing for a project, so that anyone with the link can display and explore your project in a web browser, without the need to log into  <MainPlatformNameLink /> or making the project [public](../project-advanced/#make-your-project-public-private).
+## Available layers
+Webmaps by default show layers that are packaged with the project. These are layers that are loaded from project files. These are usually GeoPackage layers, shapefile layers and background maps that are made available for offline use (e.g. mbtiles, GeoTIFF, ...).
 
-1. Navigate to your project on the <DashboardShortLink />.
-2. In the **Map** tab, click on the **Share map** button to generate a shareable link
-3. Send the link to anyone to share your project
+Layers requiring network connection (e.g. PostgreSQL layers or online background maps) are by default not included on the webmap due to potential performance and connectivity problems. However, certain network layers (such as satellite background map) can be added manually, read more in the [following section](#add-custom-background-maps).
 
-To disable the map sharing, click on the **Revoke sharing** button.
+### Add custom background maps
+If you prefer a different background map than the official one provided by default, there are currently two ways to add a custom background map:
 
-![Sharing maps via URL](./map-sharing-url.webp "Sharing maps via URL")
+1. **Map-script** - Map-script allows you to programmatically update and customise the webmap to your specific needs. Read more about `map-script` [here](../webmaps-applications/). 
+2. **Package your background map** - Make your background map available offline in QGIS. This step packages the layer into a file and it will be visible on the webmap afterwards
 
-::: tip Blog about shared maps
-You can read about this functionality in our blog post <MainDomainNameLink id="blog/a-final-surprise-for-the-year---shared-maps-via-url" desc="A final surprise for the year - shared maps via URL"/>.
+:::warning Background maps licensing
+Keep in mind that background maps services and data sources come with their own terms of use, especially if they are to be publicly shared. You should comply with any terms and conditions of the services of your choice.
 :::
+
+## Custom webmap applications <Badge text="Experimental 🧪" />
+As described in the previous section, webmaps can be further programmatically customised via `map-script` to build a custom webmap application. Read more about it [here](../webmaps-applications/).
 
-## Webmaps extent
+## Extent
 
 The extent of webmaps is defined in QGIS in the **Project Properties**. 
 
@@ -64,13 +65,9 @@ If this parameter is not defined, the map extent will be set as the *Advertised
 
 If there are no extent settings in the QGIS project, <MainPlatformName /> will calculate the extent from layers in the project.
 
-## Troubleshooting
-
-### Map config does not exist
-The **Map** tab of a project on the <DashboardShortLink /> may display this error message:
-`Map config does not exist, please try update the project`
-
-![Mergin Maps webmap Map config does not exist](./webmap-map-config-issue.webp "Mergin Maps webmap Map config does not exist")
+## Sharing maps via URL <Badge text="early access" type="warning"/>
 
-This usually happens when the map was not initiated. All you need to do is to create a new version of the project: synchronisation of the project will activate the map content.
+Webmaps can be shared via URL or embedded on a website. You can find more details about this early access feature in [Sharing and Embedding Webmaps](../webmaps-sharing/).
 
+## Troubleshooting
+Troubleshooting tips for webmaps can be found [here](../webmaps-troubleshooting/).

src/manage/webmaps-applications/index.md

@@ -0,0 +1,113 @@
+---
+description: Mergin Maps webmaps can be customised by integrating map-script to build custom applications, as an experimental feature.
+---
+
+# Building Webmap Applications <Badge text="Experimental 🧪" />
+
+::: warning Experimental feature 🧪
+Webmap applications is in experimental phase and its availability and functionality might change in the future. We are actively working on making these features easier to use.
+:::
+
+Webmap behaviour can be customised to your organisation's specific needs via a `map-script.js` file to build a webmap application.
+This is a JavaScript file that runs with your map and lets you add custom controls and behaviour on top of the built-in OpenLayers map. The script runs in both the project map view and in shared/embedded public maps. 
+
+It has reference to the map itself, API and other components to allow further customisation, including WMS and WFS OGC API (read-only).
+
+The code can reference `MerginMaps` global object as:
+ - `MerginMaps.getMap()` - the OpenLayers `Map` instance
+ - `MerginMaps.getMapElement()` - the map container DOM element
+
+If your project is shared via URL, you can use the URL to access WFS and WMS endpoints in the script like this:
+ - WFS - `https://app.merginmaps.com/app/ogc/<map_link>?SERVICE=WFS...`
+ - WMS - `https://app.merginmaps.com/app/ogc/<map_link>?SERVICE=WMS...`
+
+Map script must be placed in your project root folder and named `map-script.js`. Members with writer and higher permission can update the script.
+
+## Helpful code snippets
+
+OpenLayers submodules imports from CDN
+```js
+import TileLayer from 'https://esm.sh/ol@10.8.0/layer/Tile'
+import { fromLonLat } from 'https://esm.sh/ol@10.8.0/proj'
+import XYZ from 'https://esm.sh/ol@10.8.0/source/XYZ'
+```
+
+Add custom XYZ layer (e.g. a basemap)
+```js
+const layer = new TileLayer({
+  name: 'My layer name',
+  source: new XYZ({
+    url: '...',
+    attributions: '...',
+  })
+})
+
+MerginMaps.getMap().addLayer(layer)
+```
+
+## Examples
+
+OpenLayers API availability opens a wide range of possibilities. Here we list a couple of examples of what you can achieve.
+
+
+| Example project | Map view | Map-script file |
+|-------|------|-------| 
+| Light basemap example | [View map](https://app.merginmaps.com/maps/2kkKbiNZNPqd2_rogueUJMvRItE?cx=-1.795099776978127&cy=51.78119919095403&cz=13) | [map-script.js](https://app.merginmaps.com/projects/MerginMaps-Showcase/AS%20w%20light/tree?file_path=map-script.js) |
+| Example with measurement tools, address search and location | [View map](https://app.merginmaps.com/maps/abPOz6uw9A7DeOeq2OTqIbJMtpg) | [map-script.js](https://app.merginmaps.com/projects/MerginMaps-Showcase/AS%20w%20measure/tree?file_path=map-script.js) |
+
+
+
+## Custom webmap app with AI coding agent
+
+If you are using any AI coding agent, this is an example prompt that can help you start off the development of custom application. Fill in the **"What I want"** section.
+
+```
+You are building a custom **map script** for a Mergin Maps web map project: a
+standalone JavaScript ES module that runs on top of the project's OpenLayers map.
+
+## What I want
+[DESCRIBE YOUR FEATURE — e.g. "a button that centres the map on my GPS location
+and drops a marker", "a panel listing every feature in layer X", "a tool to
+measure distance and area".]
+
+## Runtime environment
+- The script runs inside a sandboxed `srcdoc` iframe embedded in the Mergin Maps
+  map page. A global `MerginMaps` object gives you the map:
+    - `MerginMaps.getMap()`        → the OpenLayers `Map` instance
+    - `MerginMaps.getMapElement()` → the map container DOM element
+- Import OpenLayers submodules from a CDN, e.g.
+  `import Overlay from 'https://esm.sh/ol@10.8.0/Overlay'`. Pin the OpenLayers
+  version your Mergin Maps uses (10.8.0 at the time of writing). No build step.
+
+Project's layers are served over OGC here:
+- WFS: `${parent.location.origin}/app/ogc/<map_link>?SERVICE=WFS...`
+- WMS: `${parent.location.origin}/app/ogc/<map_link>?SERVICE=WMS...`
+Tip: `<map_link>` is generated only once the map is made public ("Share map" in the UI). If there is no map link, ask me to publish the map first. Read the map-link from the `GET app/projects/<project-id>/map-links` API endpoint.
+
+## Guidelines for this environment
+- Build UI with `document.createElement` and set styles via
+  `Object.assign(el.style, {...})`. Append it to the map element with
+  `position: absolute` and a high `z-index`.
+- Do not inject `<style>` tags or rely on a stylesheet (`document.head` may be null) — use inline styles, and the Web Animations API (`el.animate(...)`) for animation.
+- `document.getElementById` and `display:flex/grid` set via `innerHTML` are
+  unreliable here — always create nodes imperatively and keep direct references.
+- To draw geometry reliably above the map's existing layers, append your own
+  `<canvas>` to the map element and redraw it on `map.on('postrender', ...)`.
+- Attach keyboard listeners to the map element (not `document`) and call
+  `mapElement.focus()` when your tool needs key input.
+- If the built-in click-to-identify popup interferes with a click-based tool,
+  suppress `singleclick`/`click` while your tool is active.
+
+## Deliverable & deployment
+- Deliver ONE self-contained file named exactly `map-script.js` — the map only loads a file with that name. Place it in the Mergin project's root folder.
+- Deploy by syncing the project with the `mergin-client` Python library (CLI).
+
+## Verify before finishing
+1. Deploy the script (sync the project).
+2. If you have browser access, open the project map in at
+   `https://<your-mergin-server>/projects/<workspace>/<project>/map`.
+3. Confirm your control appears and behaves as described, and check the browser console for errors. Iterate until it works and the console is clean.
+
+```
+
+We are keen to see what you've built! Please do not hesitate to share your results with us on our [community](https://merginmaps.com/community/join)!

src/manage/webmaps-sharing/index.md

@@ -0,0 +1,38 @@
+---
+description: Mergin Maps webmaps can be shared using a URL link. You can also embed them directly on your website with a simple HTML code for seamless integration.
+---
+
+# Sharing and Embedding Webmaps <Badge text="Early access" type="warning"/>
+
+::: warning Early access feature
+Map sharing is in early access. If you would like to try it out, ask your workspace admin or owner to enable map sharing early access program in your [workspace settings](https://app.merginmaps.com/settings). The availability of the feature might change in the future.
+:::
+
+## Sharing maps via URL 
+
+Webmaps can be shared via URL. [Admins or owners](../permissions/) can enable map sharing for a project, so that anyone with the link can display and explore your project in a web browser, without the need to log in to <MainPlatformNameLink /> or make the project [public](../project-advanced/#make-your-project-public-private).
+
+1. Navigate to your project on the <DashboardShortLink />.
+2. In the **Map** tab, click on the **Share map** button to generate a shareable link
+3. Send the link to anyone to share your project
+
+To see how this works, you can try a link to our [sample webmap](https://app.merginmaps.com/maps/grDTleg8yCdSracIxs-hmFIGdDs).
+
+To disable the map sharing, click on the **Revoke sharing** button.
+
+![Sharing maps via URL](./map-sharing-url.webp "Sharing maps via URL")
+
+
+## Embedding webmaps using HTML
+
+Webmaps that are shared can also be embedded on a website using the HTML `iframe` element with the [URL link](#sharing-maps-via-url) of the webmap.
+
+For example, this code
+
+```
+<iframe src="https://app.merginmaps.com/maps/grDTleg8yCdSracIxs-hmFIGdDs" height="500" width="700" title="Mergin Maps Webmaps Iframe Example"></iframe>
+```
+
+produces this map:
+
+<iframe src="https://app.merginmaps.com/maps/grDTleg8yCdSracIxs-hmFIGdDs" height="500" width="700" title="Mergin Maps Webmaps Iframe Example"></iframe>

src/manage/webmaps-troubleshooting/index.md

@@ -0,0 +1,14 @@
+---
+description: Troubleshooting tips for Mergin Maps dashboard maps.
+---
+
+# Troubleshooting Webmaps
+
+## Map config does not exist
+The **Map** tab of a project on the <DashboardShortLink /> may display this error message:
+`Map config does not exist, please try update the project`
+
+![Mergin Maps webmap Map config does not exist](./webmap-map-config-issue.webp "Mergin Maps webmap Map config does not exist")
+
+This usually happens when the map was not initiated. All you need to do is create a new version of the project: synchronisation of the project will activate the map content.
+