Document ODK Web Forms and new way of getting offline-capable Enketo links #1944
Conversation
|
|
||
| By default, web forms in Central are powered by `Enketo <https://enketo.org/>`_, a powerful library that was initially developed outside the ODK project and that the ODK team has contributed to. | ||
|
|
||
| The ODK team is now developing `ODK Web Forms <https://github.com/getodk/web-forms?tab=readme-ov-file#odk-web-forms>`_ which will eventually replace Enketo in ODK Central. ODK Web Forms is designed to align with ODK Collect and provide a modern user experience. This page describes how to opt into trying ODK Web Forms and documents its functionality. |
There was a problem hiding this comment.
and provide a modern user experience
Later, when WF is more complete, we can explain what "modern" means, for example:
ODK Web Forms offers a streamlined interface with faster load times, responsive design for various devices, and improved accessibility compared to Enketo.
docs/web-forms-intro.rst
Outdated
| * Entity creation or update | ||
| * References to form fields in translated labels and hints (this works for single-language forms) | ||
|
|
||
| You can change a form's setting between Enketo and Web Forms at any time. Any form links that users already have will continue to work and will reflect the setting on the server at the time that the user loads the form link. |
There was a problem hiding this comment.
Consider clarifying the implications of switching from enketo to odk wf
Switching to ODK Web Forms will not affect existing submissions, etc...
docs/web-forms-intro.rst
Outdated
| Image | ||
| ~~~~~~~~ | ||
|
|
||
| The :ref:`image question type <image-widget>` without appearance allows the user to capture an image. In Web Forms, if the user is on a mobile device, they can take a picture with their mobile camera. Devices like laptops that use a desktop browser will not show the capture button, even if they have a built-in camera. |
There was a problem hiding this comment.
What do you think about adding the calendar?
There was a problem hiding this comment.
Added a few notes about calendar and filed getodk/web-forms#393!
There was a problem hiding this comment.
Calendar image we could potentially add before the changes requested getodk/web-forms#393
|
Thanks for the feedback, @latin-panda! Over to you for a couple of screenshots, @alyblenkin |
docs/web-forms-intro.rst
Outdated
| .. warning:: | ||
| ODK Web Forms is experimental and does not support all form functionality! Please test your form carefully. | ||
|
|
||
| Starting in Central v2025.1.0, you can opt individual forms into using `ODK Web Forms <https://github.com/getodk/web-forms?tab=readme-ov-file#odk-web-forms>`_, an experimental replacement for Enketo designed from the ground up to align with ODK Collect. ODK Web Forms is still early in its development. We recommend trying ODK Web Forms if: |
There was a problem hiding this comment.
Could we just say Starting in Central v2025.1?
docs/web-forms-intro.rst
Outdated
| .. warning:: | ||
| ODK Web Forms is experimental and does not support all form functionality! Please test your form carefully. | ||
|
|
||
| Starting in Central v2025.1.0, you can opt individual forms into using `ODK Web Forms <https://github.com/getodk/web-forms?tab=readme-ov-file#odk-web-forms>`_, an experimental replacement for Enketo designed from the ground up to align with ODK Collect. ODK Web Forms is still early in its development. We recommend trying ODK Web Forms if: |
There was a problem hiding this comment.
The word experimental makes it feel very conceptual. Maybe that's what you're going for to create some resistance to fully adopting Web Forms? We could also say it's in beta?
There was a problem hiding this comment.
Fair, I've changed it to "an alternative to Enketo"! We already say later that it's early in its development.
|
|
||
| Starting in Central v2025.1.0, you can opt individual forms into using `ODK Web Forms <https://github.com/getodk/web-forms?tab=readme-ov-file#odk-web-forms>`_, an experimental replacement for Enketo designed from the ground up to align with ODK Collect. ODK Web Forms is still early in its development. We recommend trying ODK Web Forms if: | ||
|
|
||
| * You are curious about how web forms will evolve in Central. |
|
|
||
| By default, web forms in Central are powered by `Enketo <https://enketo.org/>`_, a powerful library that was initially developed outside the ODK project and that the ODK team has contributed to. | ||
|
|
||
| The ODK team is now developing `ODK Web Forms <https://github.com/getodk/web-forms?tab=readme-ov-file#odk-web-forms>`_ which will eventually replace Enketo in ODK Central. ODK Web Forms is designed to align with ODK Collect and provide a modern user experience. This page describes how to opt into trying ODK Web Forms and documents its functionality. |
| @@ -0,0 +1,70 @@ | |||
| Trying ODK Web Forms | |||
There was a problem hiding this comment.
Eventually we can add a hero image here too.
There was a problem hiding this comment.
Something like this but showing Web Forms on mobile
Adds a new "Trying ODK Web Forms" page. I'm open to alternative title suggestions. I wanted to make it intriguing and clear that it's experimental. I also wanted to avoid confusion with generic "web forms".
I originally had tried doing a page about generic "web forms" that combined information about Enketo and Web Forms. I got good feedback around that not being future-looking enough so I reworked it to be more focused.
See it at https://output.circle-artifacts.com/output/job/b30c0002-30c3-448f-82aa-98f5b84384d3/artifacts/0/docs/_build/dirhtml/web-forms-intro/index.html and https://output.circle-artifacts.com/output/job/dbef5880-2359-4960-b034-093dbc0d3439/artifacts/0/docs/_build/dirhtml/central-submissions/index.html
Screenshots are placeholders for now to show the general structure of the page, @alyblenkin will work on more beautiful ones!