@getodk/web-forms

This package is a Vue component library that uses @getodk/xforms-engine to render ODK XForms. These forms are generally authored by end users in Excel using the XLSForm standard. Learn more on the ODK website and the ODK Web Form project's main README.

Feature matrix

This section is auto generated. Please update feature-matrix.json and then run npm run feature-matrix from the repository's root to update it.

Question types (basic functionality)🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩⬜⬜ 91%

| Feature | Progress | | ---------------------------------------------------------- | :------: | | text | ✅ | | integer | ✅ | | decimal | ✅ | | note | ✅ | | select_one | ✅ | | select_multiple | ✅ | | select_*_from_file | ✅ | | repeat | ✅ | | group | ✅ | | geopoint | ✅ | | geotrace | ✅ | | geoshape | ✅ | | start-geopoint | ✅ | | range | ✅ | | image | ✅ | | barcode | | | audio | ✅ | | background-audio | | | video | ✅ | | file | ✅ | | date | ✅ | | time | ✅ | | datetime | ✅ | | rank | ✅ | | csv-external | ✅ | | acknowledge | ✅ | | start | ✅ | | end | ✅ | | today | ✅ | | deviceid | ✅ | | username | ✅ | | phonenumber | ✅ | | email | ✅ | | audit | |

Appearances🟩🟩🟩🟩🟩🟩🟩🟩⬜⬜⬜⬜⬜⬜⬜ 54%

| Feature | Progress | | --------------------------------------------------------------- | :------: | | numbers | ✅ | | multiline | ✅ | | url | | | ex: | | | thousands-sep | ✅ | | bearing | | | vertical | | | no-ticks | | | picker | | | rating | ✅ | | new | | | new-front | | | draw | ✅ | | annotate | ✅ | | signature | ✅ | | no-calendar | | | month-year | ✅ | | year | ✅ | | ethiopian | | | coptic | | | islamic | | | bikram-sambat | | | myanmar | | | persian | | | placement-map | ✅ | | maps | ✅ | | hide-input | | | minimal | ✅ | | search / autocomplete | ✅ | | quick | | | columns-pack | ✅ | | columns | ✅ | | columns-n | ✅ | | no-buttons | ✅ | | image-map | | | likert | ✅ | | map | ✅ | | field-list | ✅ | | label | ✅ | | list-nolabel | ✅ | | list | ✅ | | table-list | ✅ | | counter | | | hidden-answer | | | printer | | | masked | ✅ |

Parameters🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩⬜⬜⬜⬜⬜ 66%

| Feature | Progress | | ---------------------------------------------------------------------------------------------------------------------------------- | :------: | | randomize | ✅ | | seed | ✅ | | value | ✅ | | label | ✅ | | rows | ✅ | | geopoint capture-accuracy,warning-accuracy, allow-mock-accuracy | ✅ | | range start, end, step | ✅ | | image max-pixels | ✅ | | audio quality | | | Audit: location-priority,location-min-interval, location-max-age,track-changes, track-changes-reasons,identify-user | | | geotrace/shape incremental=true | | | range labels, placeholder | |

Form logic🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩 100%

| Feature | Progress | | ----------------------------------------------- | :------: | | calculate | ✅ | | relevant | ✅ | | required | ✅ | | required message | ✅ | | custom constraint | ✅ | | constraint message | ✅ | | read only | ✅ | | dynamic defaults (including triggercolumn) | ✅ | | choice filter | ✅ | | default | ✅ | | repeat_count | ✅ | | create or update Entities | ✅ |

Descriptions and annotations🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩⬜⬜⬜⬜ 75%

| Feature | Progress | | -------------------------------------------------------------- | :------: | | label | ✅ | | hint | ✅ | | guidance hint | | | form translations | ✅ | | form translations with ref to otherfield | ✅ | | Markdown | ✅ | | Inline HTML | ✅ | | image | ✅ | | big-image | | | audio | ✅ | | video | ✅ | | autoplay | |

Theme and layouts🟩🟩🟩🟩🟩🟩⬜⬜⬜⬜⬜⬜⬜⬜⬜ 40%

| Feature | Progress | | -------------------------------------------------------------------------- | :------: | | grid | | | pages | | | logo | | | application translations | ✅ | | theme color | | | preview form | ✅ | | send instance | ✅ | | view instance | | | edit instance | ✅ | | table of contents | |

XPath🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩⬜ 98%

| Feature | Progress | | ------------------------------------------------------------------------------------------------------------- | :------: | | operators | ✅ | | predicates | ✅ | | axes | ✅ | | string(* arg) | ✅ | | concat(string arg*|node-set arg*) | ✅ | | join(string separator, node-set nodes*) | ✅ | | substr(string value, number start,number end?) | ✅ | | substring-before(string, string) | ✅ | | substring-after(string, string) | ✅ | | translate(string, string, string) | ✅ | | string-length(string arg) | ✅ | | normalize-space(string arg?) | ✅ | | contains(string haystack, string needle) | ✅ | | starts-with(string haystack, stringneedle) | ✅ | | ends-with(string haystack, stringneedle) | ✅ | | uuid(number?) | ✅ | | digest(string src, string algorithm,string encoding?) | ✅ | | pulldata(string instance_id, stringdesired_element, string query_element,string query) | ✅ | | if(boolean condition, _ then, _ else) | ✅ | | coalesce(string arg1, string arg2) | ✅ | | once(string calc) | ✅ | | true() | ✅ | | false() | ✅ | | boolean(* arg) | ✅ | | boolean-from-string(string arg) | ✅ | | not(boolean arg) | ✅ | | regex(string value, string expression) | ✅ | | checklist(number min, number max, stringv*) | ✅ | | weighted-checklist(number min, numbermax, [string v, string w]*) | ✅ | | number(* arg) | ✅ | | random() | ✅ | | int(number arg) | ✅ | | sum(node-set arg) | ✅ | | max(node-set arg*) | ✅ | | min(node-set arg*) | ✅ | | round(number arg, number decimals?) | ✅ | | pow(number value, number power) | ✅ | | log(number arg) | ✅ | | log10(number arg) | ✅ | | abs(number arg) | ✅ | | sin(number arg) | ✅ | | cos(number arg) | ✅ | | tan(number arg) | ✅ | | asin(number arg) | ✅ | | acos(number arg) | ✅ | | atan(number arg) | ✅ | | atan2(number arg, number arg) | ✅ | | sqrt(number arg) | ✅ | | exp(number arg) | ✅ | | exp10(number arg) | ✅ | | pi() | ✅ | | count(node-set arg) | ✅ | | count-non-empty(node-set arg) | ✅ | | position(node arg?) | ✅ | | instance(string id) | ✅ | | current() | ✅ | | randomize(node-set arg, number seed) | ✅ | | today() | ✅ | | now() | ✅ | | format-date(date value, string format) | ✅ | | format-date-time(dateTime value, stringformat) | ✅ | | date(* value) | ✅ | | decimal-date-time(dateTime value) | ✅ | | decimal-time(time value) | ✅ | | selected(string list, string value) | ✅ | | selected-at(string list, number index) | ✅ | | count-selected(node node) | ✅ | | jr:choice-name(node node, string value) | ✅ | | jr:itext(string id) | ✅ | | indexed-repeat(node-set arg, node-setrepeat1, number index1, [node-setrepeatN, number indexN]{0,2}) | ✅ | | area(node-set ns|geoshape gs) | ✅ | | distance(node-set ns|geoshapegs|geotrace gt|(geopoint|string)arg*) | ✅ | | geofence(geopoint p, geoshape gs) | ✅ | | base64-decode(base64Binary input) | ✅ | | intersects(geoshape gs|geotrace gt) | |

Misc🟩⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜ 11%

| Feature | Progress | | -------------------------------------------------------------------------------- | :------: | | last saved instance | | | defaults from query parameters | | | multi-form app-like experience | | | prevent multiple submissions | | | configure end of form experience | | | save as draft | | | offline entities | | | MBtiles / offline map layers | | | submission encryption | ✅ |

Usage

To use this library in a Vue.js application:

1. Import @getodk/web-forms as a dependency in the application
2. Install the exported plugin by adding app.use(WebFormsPlugin) in entry component (usually App.vue)
3. Add the exported component anywhere in the application:

<OdkWebForm
    :form-xml="formXml"
    :fetch-form-attachment="fetchAttachment"
    :missing-resource-behavior="missingBehavior"
    :submission-max-size="5242880"  <!-- 5MB -->
    :edit-instance="editOptions"
    :preload-properties="preloadProperties"
    :device-id="abc123"
    @submit="handleSubmit"
    @submit-chunked="handleChunkedSubmit"
/>

Plugin

The plugin is there to initialize PrimeVue, currently it exposes no options. In the future, configuration options may be added to the plugin.

import { WebFormsPlugin } from '@getodk/web-forms';
app.use(WebFormsPlugin);

Props (OdkWebFormsProps)

The <OdkWebForm> component accepts the following props:

• formXml (string, required): The XML of the ODK XForm to be rendered.
• fetchFormAttachment (FetchFormAttachment, required): Function to fetch form attachments.
• missingResourceBehavior (MissingResourceBehavior, optional): Defines behavior when resources are missing.
• submissionMaxSize (number, optional): Maximum size for chunked submissions. Required when subscribing to submitChunked event.
• attachmentMaxSize (number, optional, defaults to 100MB): Maximum size for submission attachments in bytes.
• editInstance (EditInstanceOptions, optional): Options to resolve and load instance and attachment resources for editing.
• preloadProperties (PreloadProperties, optional): Properties to make available for binding in the form using jr:preload.
• deviceId (string, optional): If provided is available for binding into the form using preload attributes. Ignored if preloadProperties.deviceID is given.

Events (OdkWebFormEmits)

The component emits the following events:

• loaded: Emitted when the form is loaded and displayed to the user
• submit: Emitted when the user presses the "Send" button on a valid form
  • Payload: ([submissionPayload: MonolithicInstancePayload, callback: HostSubmissionResultCallback])
• submitChunked: Emitted for chunked submissions when the form is valid
  • Payload: ([submissionPayload: ChunkedInstancePayload, callback: HostSubmissionResultCallback])
  • Note: Requires submissionMaxSize prop to be set

What if I don't use Vue?

We will eventually publish a framework-agnostic custom element.

Development

To run in development, run this command at the monorepo root:

npm run dev -w=packages/web-forms

Individual test environments, and their corresponding watch modes, also have separate commands which can be found in package.json.

Upload XLSForm and XForm functionality in demo app and in dev mode depends on XLSForm-online. Run the xlsform-online locally. By default it runs on port 8000, if you are running it on another port then you should update the config file.

Project Structure

web-forms/
├── public/                   # Static assets (e.g., favicon.ico)
├── src/
│   ├── assets/
│   │   ├── images/           # Web Forms and Demo page images
│   │   ├── styles/           # Web Forms and Demo page styles
│   ├── components/           # UI components
│   │   ├── form-elements/    # Form elements or controllers (question types, hints, labels, inputs)
│   │   ├── form-layout/      # Form layout and rendering (e.g., form panel, groups, repeats, form error classes)
│   │   ├── common/           # Reusable smaller components (e.g., icon, image, checkbox components)
│   ├── demo/                 # Demo page
│   ├── lib/                  # Utilities
│   ├── index.ts
│   ├── web-forms-plugin.ts   # Vue plugin
├── tests/                    # Unit tests
├── e2e/                      # E2e tests
├── package.json
├── vite.config.ts
├── playwright.config.ts

Styling Overview

This project uses a combination of PrimeFlex and PrimeVue for consistent styling, alongside specific font rules for the ODK Website's Web Forms Preview.

• PrimeFlex: A CSS utility library used for layout-related properties such as positioning (e.g., flexbox, grid), responsive breakpoints, font-size and font-weight adjustments.
• PrimeVue: A UI component library that defines the visual design of components, including shapes (e.g., borders, rounded corners) and color schemes.

Theming with CSS Variables

We use CSS variables for theming with two prefixes:

• --p- Prefix: Variables prefixed with --p- (e.g., --p-primary-50) come from PrimeVue and control its component styles (e.g., colors, borders). These are part of PrimeVue’s theming system.
• --odk- Prefix: Variables prefixed with --odk- (e.g., --odk-font-family) are custom to this project and manage styles outside PrimeVue or PrimeFlex, such as application-specific typography.

Z-Index Layering System

This package uses a centralized z-index layering system to manage UI stacking order, defined in src/assets/styles/style.scss. The ODK variables (e.g., --odk-z-index-error-banner) ensure elements like floating error messages, form controls, and overlays stack correctly without overlap.

• Key layers:

  • --odk-z-index-base (background)
  • --odk-z-index-form-content (inputs, buttons)
  • --odk-z-index-form-floating (highlights, tooltips)
  • --odk-z-index-error-banner (floating errors)
  • --odk-z-index-overlay (modals)
  • --odk-z-index-topmost (loaders, notifications)

• Usage: Apply with z-index: var(--odk-z-index-error-banner); on positioned elements (e.g., position: absolute).

Fonts

Form elements use font-family: Roboto, sans-serif; for accessibility and a clean, readable appearance.

Material Design

This package uses the Material Design system for the UI, though not strictly. The idea is to closely match the design to that of ODK Collect.

Icons

The IconSVG component renders Material Design Icons (MDI) with customizable size and style variants. It uses the @mdi/js library for icon data and supports a predefined set of icons.

<IconSVG name="mdiCamera" size="md" variant="primary" />

To add a new icon:

• Import the icon from @mdi/js in the IconSVG component.
• Add the icon to the iconMap object with its corresponding name.
• Use the icon by passing its name to the name prop.

Material Icons are available under the Apache License Version 2.0. Copy of the license can be found at ./src/assets/fonts/LICENSE-2.0.txt

Translations

Translations are managed on Transifex. Translators can contribute at: https://app.transifex.com/getodk/web_forms

For developers, see TRANSLATIONS.md for details on how UI strings are managed and how to add or update translations.

Pulling and pushing translations

Use the npm scripts in this package to sync with Transifex. From the repository root:

• Pull translations from Transifex into locales/:

  npm run translations:pull -w @getodk/web-forms

• Push the English source strings (locales/strings_en.json) to Transifex:

  npm run translations:push -w @getodk/web-forms