search

kobotoolbox / enketo-core

The engine that powers Enketo Smart Paper - Use it to develop your own enketo-powered app.
https://enketo.org
Apache License 2.0
1 stars 3 forks source link

readme

enketo-core

npm version Build Status Dependency Status devDependency Status Codacy Badge

The engine that powers Enketo Smart Paper and various third party tools.

This repo is meant to use as a building block for any enketo-powered application.

Follow the Enketo blog or Enketo on twitter to stay up to date.

Usage as a library

  1. Install with npm install enketo-core --save or include as a git submodule.
  2. Develop a way to perform an XSL Transformation on OpenRosa-flavoured XForms inside your app. The transformation will output an XML instance and a HTML form. See enketo-transformer for an example. For development purposes you may also use the free (and slow, not robust at all) API provided by Enketo LLC at http://xslt-dev.enketo.org/transform (add ?xform=http://myforms.com/myform.xml to use API).
  3. Add themes to your stylesheet build system (2 stylesheets per theme, 1 is for media="print").
  4. Override config.json and optionally widgets.js with your app-specific versions.
  5. Main methods illustrated in code below:

var Form = require('enketo-core');

// The XSL transformation result contains a HTML Form and XML instance.
// These can be obtained dynamically on the client, or at the server/
// In this example we assume the HTML was injected at the server and modelStr 
// was injected as a global variable inside a <script> tag.

// required string of the jquery selector of the HTML Form DOM element
var formSelector = 'form.or:eq(0)';

// required object containing data for the form
var data = {
    // required string of the default instance defined in the XForm
    modelStr: globalXMLInstance,
    // optional string of an existing instance to be edited
    instanceStr: null,
    // optional boolean whether this instance has ever been submitted before
    submitted: false,
    // optional array of external data objects containing: 
    // {id: 'someInstanceId', xmlStr: '<root>external instance content</root>'}
    external = []
};

// instantiate a form, with 2 parameters
var form = new Form( formSelector, data);

// initialize the form and capture any load errors
var loadErrors = form.init();

// submit button handler for validate button
$( '#submit' ).on( 'click', function() {
    form.validate()
        .then(function (valid){
            if ( !valid ) {
                alert( 'Form contains errors. Please see fields marked in red.' );
            } else {
                // Record is valid! 
                var record = form.getDataStr();

                // reset the form view
                form.resetView();

                // reinstantiate a new form with the default model 
                form = new Form( formSelector, { modelStr: modelStr } );

                // do what you want with the record
            }
        });
} );

Browser support

The following browsers are officially supported:

We have to admit we do not test on all of these, but are committed to fixing browser-specific bugs that are reported for these browsers. Naturally, older browsers versions will often work as well - they are just not officially supported. Note that some applications using Enketo Core (e.g. Enketo Express) may have more limited browser support.

How to develop Enketo Core

  1. install node and grunt-cli
  2. install dependencies with npm install
  3. build with grunt
  4. start built-in auto-reloading development server with grunt develop
  5. browse to http://localhost:8005/forms/index.html

How to create or extend widgets

To create new widgets, we recommend using this plugin template. The option {touch: [boolean]}, is added automatically to all widgets to indicate whether the client is using a touchscreen device.

Each widget needs to fulfill following requirements:

Notes for All Developers

Notes for JavaScript Developers

Notes for CSS Developers

The core can be fairly easily extended with alternative themes. See the plain, the grid, and the formhub themes already included in /src/sass. We would be happy to discuss whether your contribution should be a part of the core, the default theme or be turned into a new theme.

For custom themes that go beyond just changing colors and fonts, keep in mind all the different contexts for a theme:

  1. non-touchscreen vs touchscreen (add ?touch=true during development)
  2. default one-page-mode and multiple-pages-mode
  3. right-to-left form language vs left-to-right form language (!) - also the UI-language may have a different directionality
  4. screen view vs. print view
  5. questions inside a (nested) repeat group have a different background
  6. large screen size --> smaller screen size ---> smallest screen size
  7. question in valid vs. invalid state

Sponsors

The development of this app and enketo-core was sponsored by:

Related Projects

Change log

See change log

Performance (live)

See graphs

License

See license document.

In addition, any product that uses enketo-core is required to have a "Powered by Enketo" footer, according to the specifications below, on all screens in which enketo-core 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 this page 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