"Dynamic Data Attachments" calculation syntax enhancement

Development
1

Hello devs,

Dynamic Data Attachments is a promising feature with vast capabilities. It requires some enhancements from the UX level, but overall , it’s awesome.

One point that stopped me is the XLSForm syntax which’s unique inside this module. I don’t know how the decision was took. It’s not aligned with the patterns used in XLSForm.

We’re used to the following syntax for the calculated fields , checkout the query nodes

count(instance('survey')/root/item[P_Enumerator])

While just inside Dynamic Data Attachments the rule is changed to use the below

count(instance('survey')/root/data[P_Enumerator])

Why don’t we replace the data node by item node,so that we preserver consistency along the project. Alongside that there’s some features that are not working well due to this new pattern that’s introduced. If we rename the node, everything goes well.

I’m open for discussion :slight_smile:

1 Like
2

Hi @haidarz,

Thank you to bring this to our attention. Let me review this with the dev team and I’ll get back to you.

Meanwhile, if you feel comfortable with Python programming, you can still submit a PR to change the behaviour :wink:

FYI: data has been chosen to be consistent with our API endpoint (i.e.: /api/v2/assets/<asset_uid>/data.json)

1 Like
3

Hello @nolive ,

I understand that you where trying to find a key to be consistent in a way or another. I believe that item is a better choice since all xpath evaluations are using the xpath root/item.

I’ve skimmed the pyxform library and I’m confident enough that replacing data by item will have in return enough value and better integration.

Will try to raise PR to github asap.

Thanks :smiley:

2 Likes
4

I think that you may be interested in this line

1 Like
5

Exactly, that’s what I’m updating right now and adding my defense in the code comment.

2 Likes
6

I’ve raised the PR.

Kindly check

Next step, we need to update the docs if the PR is merged.

1 Like
7

Hi @haidarz, thanks for proposing this change. Would you please help me understand how root/item is the best (most consistent) XPath syntax for referencing entire submissions, as opposed to items in a choice list? If you could reference some existing documentation or, as you’ve mentioned, pyxform code, I would very much appreciate it. I’ve done my own research, which I’ve described below, but that lead me to conclude that our use of root/data is correct.

The ODK XForms specification has a section on secondary instances that does provide an example XPath with root/item:

instance('cities')/root/item[country='nl']

However, it’s important to note that the queried XML here is a list of choices, where each choice is an <item>, not entire submissions:

<instance id="cities">
    <root>
        <item>
            <itextId>static_instance-cities-0</itextId>
            <country>nl</country>
            <name>ams</name>
        </item>
        <item>
            <itextId>static_instance-cities-1</itextId>
            <country>usa</country>
            <name>den</name>
        …
</instance>

The only place I’ve found so far that discusses querying XML of entire submissions is “External XML data” on xlsform.org, which uses count(instance('houses')/house[rooms = current()/../rooms ]) to find the number of houses that have a certain number of rooms. Example XML is not provided there, but it would be called houses.xml and could look like:

<root>
    <house>
        <id>123</id>
        <rooms>2</rooms>
        <condition>good</condition>
        <occupied>yes</occupied>
    </house>
    <house>
        <id>456</id>
        <rooms>3</rooms>
        <condition>fair</condition>
        <occupied>no</occupied>
    </house>
</root>

In this case, <house> is definitely what the “dynamic data attachments” feature would call <data>: it’s an entire submission describing a particular house. We could have offered to let people configure the name instead of hard-coding <data>, but the feature was already complex enough, with UX challenges that you were eager to point out in your first post.

Furthermore, my understanding of the root/item convention is that it came from the XForm specification itself:

element description
<item> Child of <select> or <select1> or <odk:rank> that defines an choice option. As in XForms 1.0.
<itemset> Child of <select> or <select1> or <odk:rank> that defines a list of choice options to be obtained elsewhere (from a secondary instance). As in XForms 1.0.
<value> Child of <item> or <itemset> that defines a choice value. As in XForms 1.0.

It’s true that you can use the “dynamic data attachments” feature to populate choice lists for select questions, but that’s only one of many use cases for the feature. If an <item> by definition exists only within a <select> or a <select1>, then it’s not appropriate for us to call the node enclosing an entire submission <item>. Additionally, if you search https://getodk.github.io/xforms-spec/ for <data, omitting the closing bracket intentionally, you’ll see several examples of <data> being the first child node of <instance>. An illustrative one is the first complete XForm they provide:

<?xml version="1.0"?>
<h:html xmlns="http://www.w3.org/2002/xforms" 
        …>
    <h:head>
        <h:title>My Survey</h:title>
        <model>
            <instance>
                <data id="mysurvey" orx:version="2014083101">
                    <firstname></firstname>
                    <lastname></lastname>
                    <age></age>
                    <orx:meta>
                        <orx:instanceID/>
                    </orx:meta>
                </data>
            </instance>
            …

Based on this, I maintain that our use of <data> in the “dynamic data attachments” feature is correct and consistent with ODK specifications and documentation. Of course, I am certainly open to being proven wrong, and I do want to thank you again for contributing to KoBoToolbox—especially going so far as to write code and open a PR.

2 Likes