Define API for embedding in host application

[lognaturel]

User story

As the developer of an application
I want to embed one or more ODK Web Forms
so that users of my application can use a rendered form from a form definition and other settings

Requirements

Must

• Provide filled instance to host application for submission #23
• Accept and use form attachments (external secondary instances, images, etc) #30
• Provide submission attachments to host application  #31
• Accept an instance for editing #36

Additional

• Expose as custom element #76
• Accept and use style/theming configuration #43
• Accept and use default language configuration #44

Early brainstorming

Possible options

• Javascript function (similar to Enketo Core)
• Vue component (similar to JSONForms Vue binding)
• Web Component (similar-ish to Fore but we'd expose a single component representing an entire form; possibly related to entire Fore form as Web Component)

@sadiqkhoja points out here that Vue recommends exporting Vue components

Questions

• How important is it that it's framework-agnostic? If the initial reaction of possible adopters is that it's very Vue-focused, it could limit its reach (but maybe that's ok or even good)
• Does the host application need to know anything about errors or is that a responsibility of Web Forms?

[sadiqkhoja]

How to use @odk-web-forms/ui-vue in Central

1. Import @odk-web-forms/ui-vue as npm package in central-frontend from the file system
2. Install the exported plugin by adding app.use(ThemePlugin) in container.js
3. Add the exported component anywhere in the application:
   <OdkWebForm :form-xml="formVersionXml.data" @submit="handleSubmit" />

[sadiqkhoja]

Configurations I would like to see as a consumer of ODK Web Form in my host application:

• Ability to hide language selector even if the Form has multiple languages, and a prop/method to change the language from the host application. Imagine host application has site-wide language selector.

• Ability to provide labels for element such as Save button, Add button, Print button (aria-label), etc

• Ability to provide translations instead of defining them in the Form definition. This is very low on my wish list, but I am imagining host applications to be using 3rd party translation tool like we do for Central and passing those would be ideal. I guess this can generalize to have an ability to pass secondary instance.

• Ability to hide print button

• Ability to hide Form title

• Ability to hide Submit button and a prop/method to get current state of primary state. I am thinking of composing a grand Form with multiple Form definitions.

• Events:

  • Submission
  • Save as draft
  • Error
  • Print (maybe)
  • Language change (maybe)

• Ability to provide header image (multiple resolutions?)

• Theme

  • Set primary (and secondary?) color
  • Set dark / light theme - by default use system/browser setting
  • Select theme - if we ever ship multiple themes like Material / Bootstrap / ODK2024 / ODK2026 🤷‍♂️

• Layout

  • Default (all questions are listed on a single page)
  • Pages (groups are divided in to multiple pages) - Form definition to have higher priority?
  • Grid (tabular layout) - Form definition to have higher priority?
  • Mobile (one question at a time) - maybe this is default layout if app is open on a mobile phone with the ability for host application to turn this feature off.
  • Ability to hide Form card and set the width to 100%

[lognaturel]

It feels like there are likely to be two common modes: one in which ODK Web Forms provides a "container" with language selection, print, title, etc and one in which the host application is responsible for its own container. The events you've outlined fit into that world in that they're the interface a host application can use to define their own container.

I think it would be simpler if we could have some sort of container/no container binary instead of selectively opting in or out of each one. Does that seem like it could meet the needs we know of?

[sadiqkhoja]

I like the idea of container/no container option

[lognaturel]

@sadiqkhoja if it's ok with you I'd like to move this epic out of any milestone since we won't address it all at once. We can update the top issue to link to any related work that does get slotted in.