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

• [ ] #23
• [ ] #30
• [ ] #31
• [ ] #36

Additional

• [ ] #76
• [ ] https://github.com/getodk/web-forms/issues/43
• [ ] https://github.com/getodk/web-forms/issues/44

Early brainstorming

## Possible options - Javascript function (similar to [Enketo Core](https://github.com/enketo/enketo/tree/main/packages/enketo-core#usage-as-a-library)) - Vue component (similar to [JSONForms Vue binding](https://github.com/eclipsesource/jsonforms-vuetify-renderers/tree/main/vue2-vuetify)) - Web Component (similar-ish to [Fore](https://github.com/Jinntec/Fore?tab=readme-ov-file#an-xformish-framework-in-web-components) but we'd expose a single component representing an entire form; possibly related to [entire Fore form as Web Component](https://jinntec.github.io/Fore/demo/lab/fore-component.html)) @sadiqkhoja points out [here](https://github.com/getodk/web-forms/issues/20#issuecomment-1954473659) that Vue recommends [exporting Vue components](https://vuejs.org/guide/extras/web-components.html#web-components-vs-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]

Since primary target host is vue application, we can export it as Vue Component Library as a first step, later on based on demand we can export it as Web Component as well.

Vue documentation encourages use of Vue components for enhanced capabilities https://vuejs.org/guide/extras/web-components.html#web-components-vs-vue-components

[eyelidlessness]

How much are we thinking about web components at all (versus how much are they really just strawman examples in the issues opened so far)? It's an interesting idea, but one we haven't discussed much. I'm asking here, but it's the odd specificity of language in #23 that has me wondering.

[lognaturel]

odd specificity of language in https://github.com/getodk/web-forms/issues/23 that has me wondering

That's because I did a quick Web Components refresher to see what the likely idiomatic approach would be and wanted to have a brief record of it! You all should be able to edit these issues and add other notes or even shape them differently.

How much are we thinking about web components at all

It's been on my mind because I've been thinking about a way to be able to present this as relatively host-agnostic. I worry slightly that if the interface doesn't appear generic (e.g. it's Vue-specific), it will be dismissed right away by folks who don't use Central.

[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.