https://github.com/toggle-corp/enketo-transformer
https://github.com/toggle-corp/enketo-transformer
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/toggle-corp/enketo-transformer
- Owner: toggle-corp
- License: apache-2.0
- Created: 2018-07-05T06:01:20.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2018-07-05T06:04:05.000Z (almost 7 years ago)
- Last Synced: 2025-01-09T07:13:03.642Z (4 months ago)
- Language: JavaScript
- Size: 180 KB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
Enketo Transformer
=================
[](http://badge.fury.io/js/enketo-transformer) [](https://travis-ci.org/enketo/enketo-transformer) [](https://david-dm.org/enketo/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.
### Prerequisites
1. nodeJS 6+ and npm (only tested on Ubuntu 14.04, on older distros the GCC compiler may not be recent enough)
### Install as module
```bash
npm install enketo-transformer --save
```
### Use as module
```js
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:
```bash
curl -d "xform=x&theme=plain&media[myfile.png]=/path/to/somefile.png&media[this]=that" http://localhost:8085/transform
```
### Response format
```json
{
"form" : ".....",
"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
A vagrant configuration file and provisioning script is also included. Use DEBUG environment variable to see debug terminal output, e.g.:
```bash
DEBUG=api,transformer,markdown,language node app.js
```
### License
See [license document](./LICENSE). Also note the additional 'powered by enketo' [footer requirement of enketo-xslt](https://github.com/enketo/enketo-xslt#license) which is used in this repository and therefore applicable.
### Change Log
See [change log](./CHANGELOG.md)