enketo-transformer

Enketo Transformer

NodeJS library that transforms OpenRosa/ODK XForms into a format the Enketo understands. It works both as a library module, as well as a standalone app.

Technical Documentation

Prerequisites

1. Volta (optional, but recommended)
2. Node.js 16 and npm 6 (Node.js 14 is also supported)

Install as module

npm install enketo-transformer --save

Use as module

const transformer = require('enketo-transformer');
const xform = fs.readFileSync('path/to/xform.xml');

transformer
    .transform({
        // required string of XForm
        xform: xform,
        // optional string, to add theme if no theme is defined in the XForm
        theme: 'sometheme',
        // optional map, to replace jr://..../myfile.png URLs
        media: {
            'myfile.png': '/path/to/somefile.png',
            'myfile.mp3': '/another/path/to/2.mp3',
        },
        // optional ability to disable markdown rendering (default is true)
        markdown: false,
        // optional preprocess function that transforms the XForm (as libXMLJs object) to
        // e.g. correct incompatible XForm syntax before Enketo's transformation takes place
        preprocess: (doc) => doc,
    })
    .then(function (result) {
        // do something with result
    });

Install as app (web API)

1. clone repo
2. install dependencies with npm install

Use as app (web API)

1. start with npm start
2. limited use with GET /transform with xform parameter (required, xform URL), or
3. full-featured use with: POST /transform with URL-encoded body including xform (required, full XForm as a string), theme (optional, string), and media (optional, map) parameters

sample GET request:

curl http://localhost:8085/transform?xform=https://example.com/forms/78372/form.xml

sample POST request:

curl -d "xform=<xform>x</xform>&theme=plain&media[myfile.png]=/path/to/somefile.png&media[this]=that" http://localhost:8085/transform

Response format

{
    "form": "<form>.....</form>",
    "model": "<model>...</model>",
    "transformerVersion": "1.13.0",
    "languageMap": { "Français": "fr", "English": "en" }
}

Test

• run tests with npm test
• run tests in watch mode with npm run test:watch
• Tests can be run in watch mode for TDD workflows with npm run test-watch, and support for debugging in VSCode is provided. For instructions see [./#debugging-test-watch-mode-in-vscode](Debugging test watch mode in VSCode) below

Debugging test watch mode in VSCode

Basic usage:

1. Go to VSCode's "Run and Debug" panel
2. Select "Test (watch + debug)"
3. Click the play button

Optionally, you can add a keyboard shortcut to select launch tasks:

1. Open the keyboard shortcuts settings (cmd+k cmd+s on Mac, ctrl+k ctrl+s on other OSes)
2. Search for workbench.action.debug.selectandstart
3. Click the + button to add your preferred keybinding keybinding

Develop

The script npm run develop runs the app on port 8085 and also serves test/forms on port 8081. You could test the transformation output by placing an XForm in test/forms and running http://localhost:8085/transform?xform=http://localhost:8081/autocomplete.xml

There is also a helpful GET /transform/htmlform endpoint to easily inspect the HTML form output in the developer console. Example: http://localhost:8085/transform/htmlform?xform=http://localhost:8081/autocomplete.xml

A vagrant configuration file and provisioning script is also included. Use DEBUG environment variable to see debug terminal output, e.g.:

DEBUG=api,transformer,markdown,language node app.js

Release

Releases are done each time a dependent tool needs an enketo-transformer change.

1. Create release PR
2. Update CHANGELOG.md
3. Update version in package.json
   • Bump to major version if downstream has to make changes.
4. Check Dependabot for alerts
5. Run npm update
   • Check if node-libxslt has been updated because it has caused problems in the past
6. Run npm audit
   • Run npm audit fix --production to apply most important fixes
7. Run npm i
8. Run npm test
9. Run npm run build-docs
10. Merge PR with all changes
11. Create GitHub release
12. Tag and publish the release
    • GitHub Action will publish it to npm

License

See license document.

In addition, any product that uses enketo-transformer or parts thereof is required to have a "Powered by Enketo" footer, according to the specifications below, on all screens in which the output of enketo-xslt, or parts thereof, are used, unless explicity exempted from this requirement by Enketo LLC in writing. Partners and sponsors of the Enketo Project, listed on https://enketo.org/#about and on https://github.com/enketo/enketo-core#sponsors are exempted from this requirements and so are contributors listed in package.json.

The aim of this requirement is to force adopters to give something back to the Enketo project, by at least spreading the word and thereby encouraging further adoption.

Specifications:

1. The word "Enketo" is displayed using Enketo's logo.
2. The minimum font-size of "Powered by" is 12 points.
3. The minimum height of the Enketo logo matches the font-size used.
4. The Enketo logo is hyperlinked to https://enketo.org

Example:

Powered by

Change Log

See change log