webmaps update

Author: alex-cit

src/.vitepress/sidebar/en.js

@@ -31,14 +31,18 @@ export default {
         { text: 'Member Roles and Permissions', link: '/manage/permissions/' },
         { text: 'Synchronisation', link: '/manage/synchronisation/' },
         { text: 'Mergin Maps Project', link: '/manage/project/' },
+        { text: 'Webmaps', link: '/manage/dashboard-maps/',
+        items: [
+           { text: 'Sharing and Embedding', link: '/manage/webmaps-sharing/' },
+           { 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/' }
       ] },

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,5 +1,6 @@
 ---
 description: Webmaps display the map overview of your project's spatial data directly in your web browser, on Mergin Maps dashboard.
+outline: deep
 ---
 
 # Webmaps
@@ -17,6 +18,7 @@ Webmaps are **not** available for <CommunityPlatformNameLink />.
 
 ## 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. 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 /> use [<MainPlatformName /> vector tile service](../../gis/settingup_background_map/#online-services-1) as a background map.
@@ -29,26 +31,38 @@ Click on a feature on the map to display its properties.
 
 ![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.
+### Adding background maps
+By default, the online background maps from your project are not displayed on the webmaps. However, they can be added to your webmaps using a JavaScript file with the map definition to your project through  <DashboardLink />.
 
-Try out this <AppDomainNameLink id="maps/grDTleg8yCdSracIxs-hmFIGdDs" desc="example link"/> to see how shared maps work.
+:::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.
 :::
 
-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).
+1. Create a file named `map-script.js` with the following structure:
+   
+```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'
 
-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
+const layer = new TileLayer({
+  name: 'Map Name',
+  source: new XYZ({
+    url: 'https://server.my-maps.com/tile/{z}/{y}/{x}',
+    attributions:
+      'Tiles © copyright'
+  })
+})
 
-To disable the map sharing, click on the **Revoke sharing** button.
+MerginMaps.getMap().addLayer(layer)
+```
+   This is a JavaScript file that defines background maps or other customisations that should be added to your webmap.
 
-![Sharing maps via URL](./map-sharing-url.webp "Sharing maps via URL")
+2. Add the `map-script.js` to your project through <AppDomainNameLink /> 
 
-::: 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"/>.
-:::
+After syncing the project, the background map will be added to your webmap.
+   
+### Customisations
+Other customisations can be done. The `map-script.js` file 
 
 ## Webmaps extent
 
@@ -64,13 +78,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-sharing/index.md

@@ -0,0 +1,40 @@
+---
+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"/>
+[[toc]]
+
+::: warning 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.
+:::
+
+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).
+
+
+:::tip Usage details
+Webmaps are available for <MainPlatformNameLink /> cloud and <EnterprisePlatformNameLink /> users.
+
+Webmaps are **not** available for <CommunityPlatformNameLink />.
+:::
+
+
+## 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 into  <MainPlatformNameLink /> or making 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 disable the map sharing, click on the **Revoke sharing** button.
+
+![Sharing maps via URL](./map-sharing-url.webp "Sharing maps via URL")
+
+::: 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"/>.
+:::
+
+## Embedding webmaps using iframe
+
+

src/manage/webmaps-sharing/map-sharing-url.webp

@@ -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 to create a new version of the project: synchronisation of the project will activate the map content.
+