Vellum

Vellum is a JavaRosa XForm designer used in CommCare HQ.

Image courtesy of the ReMIND project.

Vocabulary

Some of the names used in the source code are less than intuitive. Hopefully this list will help to reduce the confusion. The list is ordered with the least intuitive items first.

• Vellum: also known as the Form Builder.
• Mug: an object representing a question. Each mug has a type: Text, Date, Audio, etc. While some mug type names match the corresponding label used in the UI, some do not. For example, a Trigger is called a Label in the UI.
• JavaRosa: the language/translation module. A core part of the JavaRosa module is the IText system, which provides an API for translated strings and multimedia used to adorn questions.
• Widget: a control or group of controls displayed on the right side of the screen and used to interact with mug properties.
• Plugins: features that are not part of the core are implemented as plugins. The plugin architecture is loosely based on the JSTree plugin system. Many very important components are implemented as plugins, so just because something is a plugin does not mean it is a second-rate feature. For more details on plugins, see PLUGIN_DEVELOPMENT.md.

Usage

Checkout the source from GitHub

Run yarn dev to watch and continuously bundle files during development.

To bundle for production, run yarn build.

Running make will run yarn build and all TAR up artifacts in vellum.tar.gz.

Load index.html to run in a browser.

See here and tests/main.js for example options usage.

Vellum targets modern browsers. IE8 and earlier are not supported.

Testing and Running Locally

Prerequisites

Make sure you have Node.js 14.x installed and are using node 14.x in your working directory (tip: manage multiple versions of node.js with nvm)

Make sure you have npm 7.x installed (npm install npm@7)

Run yarn dev to generate bundles based on the dev webpack configuration.

Setup

Make sure everything is up-to-date:

$ yarn install --frozen-lockfile

You may now run the testserver. This allows you to run vellum in dev mode and/or run the test suite.

$ npm run testserver

Click the link in the output to open in your browser, or run

$ chromium-browser http://localhost:${VELLUM_PORT:-8088}

Running tests

You can run tests in the browser using the testserver described above.

Commands to run tests headlessly (make sure npm run testserver is called in the background):

./test

or to run a specific test:

./test "Name of specific test"

or pass a regex to run multiple tests:

./test "SaveToCase"  # run all tests with 'SaveToCase' in the name

A block like the following:

describe('the test', () => ...
  describe('with this condition', () => ...
    it('passes', ...)

would be referenced as the test with this condition passes. So the final command would be:

./test 'the test with this condition passes'

Contributing

Follow the Airbnb JavaScript Style Guide.

Install dependencies:

$ npm install --no-package-lock yarn  # if yarn is not installed globally
$ `npm bin`/yarn install

Build optimized version:

$ make