Skip to content

feat(web-forms#517): add support to map layers with Google Maps - #1993

Merged
latin-panda merged 13 commits into
masterfrom
map-layers-wf
Nov 18, 2026
Merged

latin-panda merged 13 commits into
masterfrom
map-layers-wf

Conversation

@latin-panda

@latin-panda latin-panda commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator

Closes getodk/web-forms#517

What has been done to verify that this works as intended?

Unit tests and manual tests

Screen.Recording.2026-11-12.at.10.26.39.PM.mov

Why is this the best possible solution? Were any other approaches considered?

Central already serves a client-config.json to the frontend, so the key is included. The map component reads it and selects the provider, keeping the rest of Web Forms independent of maps. For the tiles, I used OpenLayers' built-in Google source, which handles session tokens and attribution without adding a dependency. I also didn’t reuse Enketo's layer list, since we decided that Web Forms should always offer the same three layers.

How does this change impact users? Describe intentional behavior changes from code updates. What are the regression risks?

If there is no key, nothing changes for users except that the "how to use this map" help dialog is gone. If there is a key, map questions show Google Maps with a layer picker, the Google logo with attribution, and a small privacy notice. If the key is invalid or over its quota, users see an error banner and the map stays usable. There is no fallback to OpenStreetMap on purpose since the system admin wants the user to use Google Maps.

Does this change require updates to user documentation? If so, please file an issue here and include the link below.

Yes, it's a work in progress here getodk/docs#2128

@changeset-bot

changeset-bot Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: dffe11c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages
Name Type
@getodk/web-forms Minor
@getodk/forms Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

openFullScreen: 'mdiArrowExpand',
closeFullScreen: 'mdiArrowCollapse',
openInfo: 'mdiInformationSlabCircleOutline',
baseLayers: 'mdiLayersOutline',

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We replaced the info button with the layers button instead of adding one more. The controls bar is already at its limit, with the advanced panel open, or on a phone in landscape, there is no room for another button. In landscape the layers button is hidden for the same reason (just like info button was)

attachmentMaxSize: props.attachmentMaxSize,
});
provide(FORM_OPTIONS, formOptions);
provide(CLIENT_OPTIONS, readonly<ClientOptions>({ googleMapsKey: props.googleMapsKey }));

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FORM_OPTIONS belongs to the engine, it is defined and used there. CLIENT_OPTIONS is a separate bag because it is only read by the Vue client. So the engine does need to know about client-only settings like the Google Maps key.

@latin-panda
latin-panda marked this pull request as ready for review November 13, 2026 23:06
@latin-panda

Copy link
Copy Markdown
Collaborator Author

@garethbowen There's a follow-up PR that Matthew is reviewing, where I add the Google Maps key variable getodk/central#2326

I'm planning to add a visual test for this in another PR, where I’ll try to mock the Google tiles for all three layers.

@garethbowen garethbowen left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Initial thoughts inline. I'd like to run this locally - how are you getting a maps key? It looks like I need a personal gmail account to generate a dev one. Is that what you did?

Comment thread .changeset/clever-points-clap.md Outdated
"@getodk/forms": minor
---

Add support to map layers with Google Maps [web-forms#517](https://github.com/getodk/web-forms/issues/517)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Add support to map layers with Google Maps [web-forms#517](https://github.com/getodk/web-forms/issues/517)
Added support for map layers with Google Maps [web-forms#517](https://github.com/getodk/web-forms/issues/517)

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done!


<Dialog v-model:visible="isDialogOpen" modal class="map-block-dialog" :draggable="false">
<template #header>
<strong>{{ t('map_privacy_dialog.header.title') }}</strong>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider using h3 or similar?

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done!


readonly lastSavedXml?: string;

readonly googleMapsKey?: string;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure about this as the API because it feels too specific, and not nicely extensible. What about using mapProvider instead, which takes a MapProvider type object, and defaults to osm?

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done!


readonly lastSavedXml?: string;

readonly googleMapsKey?: string;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't forget to document this in the README.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done!

</script>

<template>
<div class="base-layer-options" role="group">

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we use a primevue/select instead of a custom menu? This way the styling will be consistent with the language picker in the header, as well as select1 questions in the form.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I started with PrimeVue's popover and moved to a plain panel, like the canvas color picker, because PrimeVue renders its overlays at the end of body with their own z-index, outside our z-index scale. PrimeVue's select does the same. It's also a text trigger with a chevron, so making it an icon button means hiding its parts with :deep overrides, which feels like a hack and easy to regress.

I agree on consistency. I'll match the option styles!

@garethbowen
garethbowen self-requested a review November 16, 2026 00:23
garethbowen

This comment was marked as outdated.

@garethbowen
garethbowen self-requested a review November 16, 2026 00:25
@lognaturel

Copy link
Copy Markdown
Member

need a personal gmail account to generate a dev one.

Happy to create a dev key for use to share if that's helpful. Do we need one for CI?

@garethbowen

Copy link
Copy Markdown
Contributor

For CI it'd be better to mock google maps out for stability and performance, so any string could be made to work!

@latin-panda

Copy link
Copy Markdown
Collaborator Author

how are you getting a maps key? It looks like I need a personal gmail account to generate a dev one. Is that what you did?

Yes, I created a API key using my GCP

@latin-panda

Copy link
Copy Markdown
Collaborator Author

@garethbowen I've applied your feedback. When you have a chance, could you please take another look?

@garethbowen garethbowen left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Very nice. Works smoothly, and can swap between providers easily.

"string": "Map data privacy",
"developer_comment": "Header of the dialog explaining what data Google receives when the map is displayed."
},
"map_privacy_dialog.body.text": {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This key doesn't match what's in the .i18n.json file. Remember to npm run build:translation before merging.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed

Comment on lines +32 to +35
const response = await super
.fetchSessionToken(url, config)
.catch(() => failedSessionResponse());
return this.disposed ? failedSessionResponse() : response;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the non-catch case could go in a then to avoid double handling...

Suggested change
const response = await super
.fetchSessionToken(url, config)
.catch(() => failedSessionResponse());
return this.disposed ? failedSessionResponse() : response;
return super
.fetchSessionToken(url, config)
.then(response => this.disposed ? failedSessionResponse() : response)
.catch(() => failedSessionResponse());

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed

[BASE_LAYER_IDS.TERRAIN]: { mapType: 'terrain', layerTypes: ['layerRoadmap'] },
};

const FAILED_SESSION_STATUS = 410;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why a 410? That doesn't seem right. Is it used internally in OL?

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, I was checking that status in another place, then removed that code and forgot about this. Removed!

/**
* Base map provider for map questions. The host builds it from its own config.
*/
export type MapProvider = { kind: 'google'; apiKey: string } | { kind: 'osm' };

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think kind is right. How about name?

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Renamed

border-radius: var(--odk-radius);
}

.base-layer-option {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we remove this class and just have button {...} nested inside the base-layer-options block above?

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done!


<template>
<div class="base-layer-options" role="group">
<button

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this should be a button. Can we use ul and li instead? I don't think we're getting anything for free by having a button, and a list is more semantic (we're not submitting the form!) and probably easier to make consistent with the select menus we use in other places.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the button is still fine here because it triggers an action (switching the layer), it's focusable, the Enter key works out of the box, and screen readers pick it up. But it seems I used the incorrect aria (aria-pressed).

I'll replace it with ul/li to match other dropdowns, since it still fits because it's a list of options. The only difference is that it requires more setup: role="listbox"/role="option", aria-selected, and tabindex plus Enter handling for the keyboard.

.base-layer-panel {
position: absolute;
top: 0;
right: calc(100% + var(--odk-spacing-m));

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the --odk-spacing-m is too much... the panel looks disconnected from the button. You could almost just do 100% but 100% + 1px looks best too me.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good eye! I kept the same gap as the canvas colour picker on purpose, so the two panels follow the same line. Here's the canvas today and the concept from Figma (not very detailed, but it shows the idea):

Canva:

Figma:

https://www.figma.com/design/6v0NnvayfDlaQhYpjv37Bn/ODK-Web-Forms?node-id=5649-5717&t=58I5uUCTcC4OIL59-4


<template>
<div class="map-privacy-badge">
<button

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think a link (a) would be more semantic.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the button is right here, it's not a hyperlink and it doesn't navigate anywhere, it just opens the dialog. The actual link to Google's policy is inside the dialog.

@latin-panda

Copy link
Copy Markdown
Collaborator Author

@garethbowen could you please have a look again?

@garethbowen garethbowen left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Very nice!

…nto map-layers-wf

# Conflicts:
#	.image-hashes
#	apps/forms/src/components/web-form-renderer.vue
#	packages/web-forms/e2e/test-cases/visual/all-question-types.test.ts-snapshots/select-map-point-selected-chromium.png
@latin-panda
latin-panda merged commit 28ca11f into master Nov 18, 2026
80 of 81 checks passed
@latin-panda
latin-panda deleted the map-layers-wf branch November 18, 2026 17:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support map layer customization (Google Maps, MapBox, terrain, satellite)

3 participants