README.md

Openrosa XForms Evaluator

Wrapper for browsers' XPath evaluator with added support for OpenRosa extensions.

For more info on extended XPath expressions/bindings supported by XForms/OpenRosa/OpenDataKit (ODK) see:

• ODK XForm Specification

Installation

yarn

yarn add openrosa-xpath-evaluator

npm

npm install --save openrosa-xpath-evaluator

Use

Initialisation

const orxe = require('openrosa-xpath-evaluator');
const evaluate = orxe();

Querying

var result = evaluate(
    '//ul/li/text()', // XPath expression
    document, // context node
    null, // namespace resolver
    XPathResult.ORDERED_NODE_SNAPSHOT_TYPE
);

// loop through results
for (var i = 0; i < result.snapshotLength; i++) {
    var node = result.snapshotItem(i);
    alert(node.nodeValue);
}

Dependencies

This library has no explicit dependencies, but expects various DOM & XPath-related values to be supplied by the browser (Element, Node, XPathResult etc.).

To use the ODK digest() function, you'll need to add node-forge to your project.

Development

Useful resources

• https://www.w3.org/TR/1999/REC-xpath-19991116/
• https://getodk.github.io/xforms-spec/
• https://developer.mozilla.org/en-US/docs/Web/API/XPathEvaluator
• https://developer.mozilla.org/en-US/docs/Web/API/Document/evaluate
• https://developer.mozilla.org/en-US/docs/Web/XPath/Introduction_to_using_XPath_in_JavaScript
• https://developer.mozilla.org/en-US/docs/Web/API/XPathResult
• https://developer.mozilla.org/en-US/docs/Web/API/Node

Known limitations

• namespace:: axis is not supported (but it might work in your browser if you're lucky)
• xpath variables ($var) are not supported

Not implemented

The following XPath/ODK/OpenRosa functions are not implemented in this library, but may still work depending on your usage.

XPath 1.0 functions

• instance()
• current()

ODK functions

• pulldata()
• jr:choice-name()
• jr:itext()
• indexed-repeat()

TODO

• arrange source code, e.g. src/core and src/openrosa

Release

1. Create release PR
2. Check Dependabot for alerts
3. Run npm update
4. Run npm audit
   • Run npm audit fix --production to apply most important fixes
5. Run npm ci
6. Run npm test
7. Update CHANGELOG.md
8. Update version in package.json
9. Merge PR with all changes
10. Create GitHub release
11. Tag and publish the release
    • GitHub action will publish it to npm public repository

Acknowledgement

This library was developed by Medic Mobile for their Enketo-based application. In 2020, it was transferred to the Enketo organization. Many thanks to Medic Mobile for this very valuable contribution to the Enketo and ODK world.

Development of this application was made possible by:

• Medic Mobile
• DIAL Open Source Center
• OpenClinica