feat(medic/cht-core#10676): store geolocation when submitting contact forms by cliftonmcintosh · Pull Request #2221 · medic/cht-docs

cliftonmcintosh · 2026-06-09T21:22:27Z

Description

Documents the geolocation widget for household contact forms, introduced in medic/cht-core#10676.

New page — building/forms/configuring/contact-geolocation.md

Full reference for configuring GPS location capture in household contact forms. Covers:

XForm XML changes: model instance field, bind, body group, and translations
XLSForm equivalent (survey sheet row)
Widget behavior:
- GPS acquisition starts automatically on render (no capture button);
- on success, a context question ("I'm at the household" / "I'm somewhere else") appears;
- on failure, a retry button and a self-acting Save without location checkbox appear;
- permission-denied handling;
- a GPS-unavailable state
Edit mode: a 4-option radio group (Keep / Change household location / I am not at the household / Remove household location), gated on a silent background GPS read
What gets stored on the contact document (geolocation, geolocation_log)
Scoped explicitly to household contacts: the widget's UI copy (badge, radio labels) is hardcoded around "household" wording and isn't intended for other contact types

Updated — building/forms/contact.md

New "Capturing GPS Location" section with a link to the configuring page, following the same pattern as the existing "Uploading Binary Attachments" section.

Updated — building/contact-management/contacts.md

New "GPS location capture" subsection under "Creating and Editing Contacts" alongside the existing Duplicate Contact Detection entry.

AI Disclosure

Claude Code was used to draft and revise all documentation in this PR, across multiple sessions (models claude-sonnet-4-6 and claude-sonnet-5). The original draft was based on a technical draft prepared by a separate Claude Code session that worked directly in the cht-core codebase; the revision was verified directly against the feature/10676-contact-form-geolocation-stored branch source (widget, services, and translation files). I reviewed the output for accuracy, style guide compliance, and correct placement within the docs site structure.

License

The software is provided under AGPL-3.0. Contributions to this project are accepted under the same license.

…orms Add reference page for the new geolocation widget that captures GPS coordinates when a contact is created or edited. Documents XForm XML and XLSForm configuration, widget behavior states, stored fields (geolocation, geolocation_log), and context question customization. Cross-reference from the contact forms reference page and the contacts feature overview. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…implementation Correct factual errors introduced before implementation was finalized: remove geo_context XForm field, fix geolocation_log shape (is_home boolean), fix skip value ("skipped"), scope geolocation field to home captures only. Add edit mode and weak-signal failure path. Replace UI string quotes and button labels with functional descriptions. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…igned flow The widget was redesigned since the last docs pass: GPS now starts automatically on render instead of behind a capture button, the context question moves to after a successful capture, "skip" is a single self-acting checkbox rather than a button gated by one, and edit mode is a 4-option radio group (adding "Remove") instead of 2. Also corrects the "what gets stored" table (The capture field is stripped before saving and never persists) and scopes the feature to household contacts throughout, since the widget's UI copy is hardcoded around "household" wording. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

cliftonmcintosh · 2026-08-05T20:55:49Z

@dianabarsan

This is the documentation for medic/cht-core#11136. Would you be able to review this? If not, would you offer a recommendation for a reviewer?

dianabarsan

Very nice, and very thorough, but I fear there it's slightly too technical, and the instructions don't cover the supported way of generating forms, via xlsx and cht-conf.

I added some small requests inline.

dianabarsan · 2026-08-07T06:18:24Z

+_Added in CHT `TBD`._
+
+> [!CAUTION]
+> This widget is designed for household contact forms only. Adding it to a report form is unsupported and may produce unexpected behavior. It's also written specifically for households: the badge and option labels use household-specific wording ("Household location already saved", "Change household location", and so on). Adding it to a form for another contact type shows that same wording, which won't make sense outside a household context.


Can you please strengthen this phrase, such that it is understood that only language is the limitation, since all of the translations can me modified?
I fear that we are overly limiting this, when the feature itself can be used successfully for any contact.

dianabarsan · 2026-08-07T06:19:21Z

+
+## XForm configuration
+
+Three changes are required in the household contact form XML: a model field, a bind, and a body element.


People do not manually create forms XML. They create xlsx that are later transformed with cht-conf to XML. These instructions should cover the XLSX changes, not the XML footprint.

dianabarsan · 2026-08-07T06:20:04Z

+## XLSForm equivalent
+
+> [!WARNING]
+> This section has not been tested against a real cht-conf XLSForm conversion. Verify the output before using it in a deployment.


We should test this, as this is the supported way of generating xforms.

Using Claude Code, I tested the XLSForm example in this PR. It wrote a small Python script to build a test .xlsx file reproducing the docs' survey row inside a contact form structure, then ran it through two tools:

cht-conf's actual XLSForm-to-XForm converter (the same one convert-contact-forms uses in production). It converted cleanly, and the resulting XForm XML matched the hand-written XForm example elsewhere on this page field-for-field.

ODK Validate, the official XForm validator. it passed with zero warnings.

With Claude Code, I also ran a control test with a deliberately invalid field type to confirm the converter actually validates input rather than accepting anything, so the passing results above are meaningful.

dianabarsan · 2026-08-07T06:20:38Z

+
+- The progress bar is replaced by a success message
+- The widget shows a context question with two options: "I'm at the household" and "I'm somewhere else"
+- Selecting either option sets `geo_capture` to `"captured"`, records the choice, and lets the CHW proceed to the next page


Please add a photo capture of every state you describe here.

dianabarsan · 2026-08-07T06:21:30Z

+- If the failure is due to a weak or unreliable signal, a message prompts the CHW to move to an area with better reception
+- A retry button and a checkbox labeled **Save without location** appear
+- Tapping the retry button clears the failure state and starts a new capture attempt
+- Checking **Save without location** immediately sets `geo_capture` to `"skipped"` and cancels the in-progress capture; unchecking it clears the field, and the CHW can then tap Retry to try again


Too much technical implementation detail here.

Reworded to be less technical.

dianabarsan · 2026-08-07T06:21:45Z

+
+- The progress bar is replaced by a success message
+- The widget shows a context question with two options: "I'm at the household" and "I'm somewhere else"
+- Selecting either option sets `geo_capture` to `"captured"`, records the choice, and lets the CHW proceed to the next page


Too much implementation detail here.

Reworded to be less technical.

dianabarsan · 2026-08-07T06:22:56Z

+
+Household contact forms can capture the device's GPS location at the time a household is created or edited. The geolocation widget handles the full capture experience automatically: it starts acquiring a position the instant the form renders, then shows progress, success, and failure states. It stores the result on the contact document.
+
+After a successful capture, the widget asks whether the CHW is at the household or somewhere else, and records the answer alongside the coordinates. This context question is part of the widget and requires no additional XForm fields.


Can you move the section "what gets stored" here? So people don;t need to scroll through so much text to figure out what data they would expect to see.

The widget has no code-level contact-type restriction. "household" wording only comes from the default translation strings, which are overridable. Reword the caution to separate the hard restriction (report forms are unsupported) from the soft one (default copy is household-specific but not a technical ceiling), and revert the title, description, and cross-references in contact.md/contacts.md from "household contact forms" back to generic "contact forms." Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Per review, readers shouldn't have to scroll past the full configuration and behavior walkthrough to find out what data the widget actually writes. Moves the section to right after the intro and caution, ahead of Configuration/Widget behavior/Edit mode. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Replace prose-only descriptions of each widget state with screenshots. Adds 7 images covering GPS acquiring, success, failure, permission denied, GPS unavailable, and both edit-mode states (capture options disabled/enabled), and wires each into contact-geolocation.md via the figure shortcode. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

mrjones-plip · 2026-08-10T15:47:14Z

Dropping a quick note here to day Diana is on holiday for a few weeks and likely wont get back to this PR until her return.

cliftonmcintosh · 2026-08-10T17:53:55Z

Dropping a quick note here to day Diana is on holiday for a few weeks and likely wont get back to this PR until her return.

Thanks, @mrjones-plip. I hope she enjoys her holiday!

dianabarsan

Very nice and thorough, thanks for all the changes.
I added two small requests inline.

dianabarsan · 2026-08-24T12:10:36Z

+> [!CAUTION]
+> This widget is designed for contact forms only. Adding it to a report form is unsupported and may produce unexpected behavior.
+>
+> The widget's default copy is written for households ("Household location already saved", "Change household location"... ). Nothing in the widget restricts it to household contacts specifically. It activates on any form field with `appearance="geolocation-capture"`, regardless of contact type. To use it on another contact type, override the `geolocation.edit.*`, `geolocation.at.household`, and `geolocation.somewhere.else` translation keys with wording appropriate to that contact type. Otherwise the household-specific default text shows through.


Thanks for adding this note.

appearance="geolocation-capture" makes direct reference to how the XML would look like, while in the XLS it will be a column. Can you please change the wording such that we are referring to XLS columns instead of XML attributes?

dianabarsan · 2026-08-24T12:35:03Z

@@ -0,0 +1,189 @@
+---
+title: "Capture GPS Location in Contact Forms"
+linkTitle: "GPS Location Capture"


Please call this "Contact GPS location capture" so it is not confused with a generic GPS capture.

Rename the linkTitle to "Contact GPS Location Capture" so it isn't confused with a generic GPS capture feature. Reword the caution box to describe the geolocation-capture appearance as an XLS column value instead of XML attribute syntax, matching the XLSForm-first configuration path.

dianabarsan

Lovely!

cliftonmcintosh · 2026-08-28T21:27:33Z


+### GPS location capture

+_Added in CHT `TBD`._


@dianabarsan

Should I update the "TBD"s to 5.3 in a new pull request?

mrjones-plip · 2026-08-28T21:32:19Z

already fixed - thanks @cliftonmcintosh !

cliftonmcintosh · 2026-08-28T21:33:59Z

Great! Thanks!

cliftonmcintosh · 2026-08-28T21:34:36Z

+
+After a successful capture, the widget asks whether the CHW is at the household or somewhere else, and records the answer alongside the coordinates.
+
+_Added in CHT `TBD`._


It's here, too, @mrjones-plip. I'll race you

cliftonmcintosh · 2026-08-28T21:34:54Z


+## Capturing GPS Location
+
+_Added in CHT `TBD`._


And here, @mrjones-plip

cliftonmcintosh force-pushed the feature/10676-contact-form-geolocation-stored branch from 934935f to 7bddf7f Compare June 9, 2026 21:33

cliftonmcintosh mentioned this pull request Jun 9, 2026

feat(#10676): store geolocation when submitting contact forms medic/cht-core#11136

Merged

7 tasks done

cliftonmcintosh and others added 3 commits August 4, 2026 13:34

cliftonmcintosh force-pushed the feature/10676-contact-form-geolocation-stored branch from 8830444 to b01f044 Compare August 4, 2026 19:05

Revise explanation of required geocapture

b283a3b

cliftonmcintosh marked this pull request as ready for review August 5, 2026 20:55

dianabarsan self-requested a review August 7, 2026 06:15

dianabarsan suggested changes Aug 7, 2026

View reviewed changes

cliftonmcintosh and others added 4 commits August 7, 2026 10:19

docs(medic/cht-core#10676): lead with XLSForm over raw XForm XML

8edf7ed

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

cliftonmcintosh requested a review from dianabarsan August 10, 2026 15:07

dianabarsan approved these changes Aug 24, 2026

View reviewed changes

cliftonmcintosh requested a review from dianabarsan August 24, 2026 14:14

dianabarsan approved these changes Aug 25, 2026

View reviewed changes

dianabarsan merged commit 7456e73 into medic:main Aug 28, 2026
1 check passed

cliftonmcintosh commented Aug 28, 2026

View reviewed changes


		## XForm configuration

		Three changes are required in the household contact form XML: a model field, a bind, and a body element.


		Household contact forms can capture the device's GPS location at the time a household is created or edited. The geolocation widget handles the full capture experience automatically: it starts acquiring a position the instant the form renders, then shows progress, success, and failure states. It stores the result on the contact document.

		After a successful capture, the widget asks whether the CHW is at the household or somewhere else, and records the answer alongside the coordinates. This context question is part of the widget and requires no additional XForm fields.


		After a successful capture, the widget asks whether the CHW is at the household or somewhere else, and records the answer alongside the coordinates.

		_Added in CHT `TBD`._

Conversation

cliftonmcintosh commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

AI Disclosure

License

Uh oh!

cliftonmcintosh commented Aug 5, 2026

Uh oh!

dianabarsan left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mrjones-plip commented Aug 10, 2026

Uh oh!

cliftonmcintosh commented Aug 10, 2026

Uh oh!

dianabarsan left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dianabarsan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mrjones-plip commented Aug 28, 2026

Uh oh!

cliftonmcintosh commented Aug 28, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

cliftonmcintosh commented Jun 9, 2026 •

edited

Loading