Enketo Customization

Martijn van de Rijdt, 12 Jul 2017

I would like to highlight some changes in Enketo that may be interesting to developers using Enketo tools in their own applications.


The more popular Enketo becomes, the larger the demand for customization. Not all of these customizations are suitable for inclusion in the common Enketo libraries or the common Enketo Express application. For example, the customization may be specific to a particular group of specialized users or to integration into a specific custom system.

One of the main sponsors of the Enketo Project that has frequent customization needs is OpenClinica. This clever company is very aware of the high long-term costs of forking Enketo’s form engine - Enketo Core - and has tried to avoid it by investing in Enketo tools. (Thanks OpenClinica!)

Whenever a customization is required that does not belong in the common Enketo tools, an evaluation is made on how to best include it in a way that:

  1. avoids forking Enketo libraries and
  2. avoids changing common files in ports of Enketo Express that would increase maintenance (merging) costs.

Both of these design criteria usually result in reorganizing the code in the common tools to make them more extensible.

Despite very substantially changing the behavior of the engine, OpenClinica is still using Enketo Core as published on npm and therefore will continue to easily benefit from all the ongoing improvements made to it. Merging changes in the main Enketo Express app into their port is also usually painless.


In some cases, it has made sense to add alternative form engine behavior and expose this via new configuration options. Examples of recent additions to Enketo tools include:


Widgets have been modular for a while now. A widget lives in its own folder and is easy to enable or disable in a particular application. It is also straightforward to add your own custom widget in your own application and still use the common Enketo Core library. Sometimes these widgets make it in the official Enketo Core library without being activated by default such as the ArcGIS geo widget contributed by the Survey123 team at Esri.

Evaluation Cascade

It has recently become possible to augment the most elementary part of Enketo’s form engine by adding methods at the end of its standard evaluation cascade. A good example can be found here (Form.prototype.evaluationCascadeAdditions = [ constraintUpdate ];).

XPath evaluator

Due to a requirement by Medic for their application, and thanks to their contribution, Enketo Core provides an easy way to swap its XPath evaluator with another one of your choosing.

Everything else

A major recent change is that Enketo Core now exposes pretty much everything. It is now possible to replace individual functions and override complete modules without forking. Naturally, this is one of the more risky endeavors, as there are no guarantees that Enketo’s internal API stays completely stable, but in some cases the benefits of doing this (vs. forking), outweigh the potential future costs. The risks can also be mitigated by adding sensible tests and using Continuous Integration.

Should you have a need to customize an Enketo library or application, we recommend first opening a GitHub issue in the appropriate repository. If there is interest to include your customization in the common tools, this would be a win-win situation for all. If not, there will be ways we can help you develop a plan that minimizes the future headache of keeping your application up-to-date with the latest version of the Enketo tool(s).