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

nodeJS 12 and npm

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)

clone repo
install dependencies with npm install

Use as app (web API)

start with npm start
limited use with GET /transform with xform parameter (required, xform URL), or
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

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

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:

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

Example:

Change Log

See change log

eyelidlessness / enketo-transformer