OC Only: Async Query widget

[enketo-issue-mover]

From @MartijnR on June 29, 2018 19:55

Somewhat related to #1052

Objective:

• bypass autocomplete limitations in Safari, IE11 (and probably Edge) of LARGE external files
• bypass general XPath query performance in IE11 of LARGE external files

The "widget"

Have a 'widget' with a button that upon click makes an (asynchronous) request to an OC endpoint. Possible block complete form UI during request.

1. The url could be a jr:// url that can be found in the Manifest.
2. Enketo could pass an xpath-query parameter to the API request
3. Enketo could pass a result-type to the API request with as possible values string and instance
4. We don't mix and match asynchronous and synchronous functions in XPath.

simple string, that populates oc1:

type	name	appearance	bind::oc:api-query	calculation
text	oc1	oc-api-query	oc-api(jr://file/abc.xml, /path/to[name=${one}]/node, 'string' )
calculate	two			${oc1} + 3

node fragment (readonly text = note because it doesn't store a value in this node):

type	name	appearance	bind::oc:api-query	calculation
note	oc1	oc-api-query	oc-api(jr://file/abc.xml, /path/to[name=${one}]/item, 'instance' )
calculate	two			instance("abc")/path/to/node

An empty <instance id="abc" oc:writeable="true" /> would have to be added to the XForm as well for the last example.

Upon failed retrieval:

• user can retry.
• form may have logic that would show errors if the request never succeeds (e.g. required questions that never populate)

Upon successful retrieval:

If the result is of type string, the simplest flavor of this widget would simply populate that question (i.e. that text question with an oc-api-query appearance) with the returned value. This seems fairly straightforward.

If the result is of type instance, it could populate/add/refresh (?) an instance in the form. (NOTE: requires creating support for writable instances, and triggering re-evaluation of logic when such an instance gets re-freshed). There could be other questions that use that instance, e.g. calculations or selects that will get updated. Not sure yet about the XForm and XLSForm syntax possibilities here.

Copied from original issue: kobotoolbox/enketo-express#1076

[enketo-issue-mover]

From @MartijnR on July 4, 2018 22:2

for simple string version, Martijn to implement:

• [ ] let oc:api-query bind attribute be passed to output
• [ ] add widget to enketo-express-oc with UI that implements the oc-query() binding action

This would take him about 3-4 days (mocking the API).

OC to implement:

• [ ] API endpoint listed in manifest. In the XLSForm example above it would be listed under <filename>abc.xml</filename>". The endpoint receives an xpath-query(any XPath) and result-type (with value "string") parameter, and returns a string value of the XPath expression. E.g. using a browser evaluator you'd return: document.evaluate('/path/to/node', document, null, XPathResult.STRING_TYPE).stringValue using the document root as the context. If the document contains name-spaced nodes, it would have to build a namespace resolver as well.

[enketo-issue-mover]

From @MartijnR on July 4, 2018 22:8

What we actually need to use for the instance population is XForms Event and Actions.

for the complex instance-populating version, Martijn to implement:

• [ ] in enketo-core (or better in an extension to it) a method to populate an oc:writeable instance
• [ ] when instance is updated, find all logic that refers to the instance and re-evaluate this
• [ ] add the instance retrieval and population to the previous widget

This would take him about 5-6 additional days.

OC to implement:

• [ ] API endpoint listed in manifest. In the XLSForm example above it would be listed under abc.xml". The endpoint receives an xpath-query(any XPath) and result-type (with value "instance") parameter, and returns an XML document obtained by evaluating the XPath expression. E.g. using a browser evaluator you'd do: document.evaluate('/path/to/node', document, null, XPathResult.NODE_SNAPSHOT_TYPE) and iterate through the result and append each result node to an empty XML document to a single <instance> node. The evaluation uses the document root as the context. If the document contains name-spaced nodes, it would have to build a namespace resolver as well.
• [ ] a way to ensure that the empty instance is added to the XForm

[enketo-issue-mover]

From @MartijnR on July 6, 2018 19:36

Does the first parameter of oc-api make sense? Enketo doesn't actually need to retrieve this file. OC needs to be able to find it. Maybe this should just be the OC API endpoint that Enketo should send the request to?

Needs more thought.

[enketo-issue-mover]

From @pbowen-oc on July 27, 2018 19:58

@kkrumlian - We need to provide input to go ahead with this.