Criação de aplicações de mapas web – Experimental 🧪

Funcionalidade experimental 🧪

As aplicações do Webmap encontram-se numa fase experimental e a sua disponibilidade e funcionalidades poderão sofrer alterações no futuro. Estamos a trabalhar ativamente para tornar estas funcionalidades mais fáceis de utilizar.

O comportamento do mapa do site pode ser personalizado de acordo com as necessidades específicas da sua organização através de um map-script.js ficheiro para criar uma aplicação de mapa web. Trata-se de um ficheiro JavaScript que funciona em conjunto com o seu mapa e permite adicionar controlos e comportamentos personalizados ao mapa integrado do OpenLayers. O script funciona tanto na vista do mapa do projeto como em mapas públicos partilhados ou incorporados.

Inclui referências ao próprio mapa, à API e a outros componentes para permitir uma maior personalização, incluindo WMS e WFS da API OGC (apenas para leitura).

O código pode fazer referência a MerginMaps objeto global como:

• MerginMaps.getMap() - o OpenLayers Mapa instância
• MerginMaps.getMapElement() - o elemento DOM que contém o mapa

Se o seu projeto for partilhado através de um URL, pode utilizar esse URL para aceder aos pontos finais WFS e WMS no script da seguinte forma:

• WFS - https://app.merginmaps.com/app/ogc/<map_link>?SERVICE=WFS...
• WMS - https://app.merginmaps.com/app/ogc/<map_link>?SERVICE=WMS...

O script do mapa deve ser colocado na pasta raiz do seu projeto e ter o nome map-script.js. Os membros com permissão de escrita ou superior podem atualizar o script.

Trechos de código úteis

Importações de submódulos do OpenLayers a partir de um CDN

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'

Adicionar camada XYZ personalizada (por exemplo, um mapa de base)

const layer = new TileLayer({
  name: 'My layer name',
  source: new XYZ({
    url: '...',
    attributions: '...',
  })
})

MerginMaps.getMap().addLayer(layer)

Exemplos

A disponibilidade da API do OpenLayers abre um vasto leque de possibilidades. Aqui apresentamos alguns exemplos do que é possível fazer.

Exemplo de projeto	Visualização do mapa	Ficheiro de script de mapa
Exemplo de mapa de base simples	Ver mapa	map-script.js
Exemplo com ferramentas de medição, pesquisa de endereços e localização	Ver mapa	map-script.js

Aplicação personalizada de mapas web com agente de programação baseado em IA

Se estiver a utilizar algum agente de programação baseado em IA, eis um exemplo de prompt que o pode ajudar a dar início ao desenvolvimento de uma aplicação personalizada. Preencha a secção «O que pretendo ».

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.

Estamos ansiosos por ver o que criaram! Não hesitem em partilhar os vossos resultados connosco na nossa comunidade!