Add "trigger" column to use value changes as triggers for calculations

[MartijnR]

Discussion: https://forum.opendatakit.org/t/xlsform-proposal-to-calculate-a-value-when-another-value-changes/24978/3

It would likely be very helpful to first implement a change in regular calculations: #70
It would perhaps be helpful, but optional, to first implement a change in label output: #439

Below is an attempt at creating cut-and-paste tests (i.e. with the new way of testing using markdown) that have to pass to implement this feature successfully:

Rules:

a. For all questions: if there is no calculation, either a label or a hint is required unless it has a value for 'trigger'.
b. If a question has either a label or a hint, a body element is included in the XForms output. (This is no change, but perhaps helpful to explain).
c. If a question with trigger has an empty calculation it will reset the value => value="".

Test 1:

type	name	label	calculation	trigger
text	a	Enter text
dateTime	b		now()	${a}

<data>
    <a/>
    <b/>
    ...
</data>
...
<bind nodeset="/data/b" type="dateTime" />
...
<input ref="/data/a">
    <label>Enter text</label>
    <setvalue event="xforms-value-changed" ref="/data/b" value="now()" />
</input>

Note: test for absence of <input ref="/data/b"> in body because b has no label and no hint.
Note: the value in the calculation column gets a completely different XForms output if the trigger column has a value!

Test 2:

type	name	label	calculation	trigger
text	a	Enter text
dateTime	c	Date of diagnostic	now()	${a}

<data>
    <a/>
    <c/>
    ...
</data>
...
<bind nodeset="/data/c" type="dateTime" />
...
<input ref="/data/a">
    <label>Enter text</label>
    <setvalue event="xforms-value-changed" ref="/data/c" value="now()" />
</input>
<input ref="/data/c">
    <label>Date of diagnostic</label>
</input>

Test 3:

type	name	label	calculation	trigger	hint
text	a	Enter text
integer	b		1+1	${a}
dateTime	c		now()	${a}	A hint

<data>
    <a/>
    <b/>
    <c/>
    ...
</data>
...
<bind nodeset="/data/b" type="int" />
<bind nodeset="/data/c" type="dateTime" />
...
<input ref="/data/a">
    <label>Enter text</label>
    <setvalue event="xforms-value-changed" ref="/data/b" value="1 + 1" />
    <setvalue event="xforms-value-changed" ref="/data/c" value="now()" />
</input>
<input ref="/data/c">
    <label/>
    <hint>A hint</hint>
</input>

Note: test for absence of <input ref="/data/b> in body (no label or hint).
Note: c has a hint and therefore <input ref="/data/c"> is included in the body.
Note: the empty <label/> element (vs. omitting it entirely) is unrelated to this issue, but assumed to be implemented: #439. If it hasn't been implemented, it may still be missing entirely from the output.

Test 4:

type	name	label	calculation	trigger
text	a	Enter text
dateTime	d	Date of something		${a}

<data>
    <a/>
    <d/>
    ...
</data>
...
<bind nodeset="/data/d" type="dateTime" />
...
<input ref="/data/a">
    <label>Enter text</label>
    <setvalue event="xforms-value-changed" ref="/data/d" value="" />
</input>
<input ref="/data/d">
    <label>Date of something</label>
</input>

Test 5:

type	name	label	calculation	trigger
text	a	Enter text
decimal	e			${a}

<data>
    <a/>
    <e/>
    ...
</data>
...
<bind nodeset="/data/e" type="decimal" />
...
<input ref="/data/a">
    <label>Enter text</label>
    <setvalue event="xforms-value-changed" ref="/data/e" value="" />
</input>

Note: test for absence of <input ref="/data/e"> in body (no label or hint).

Test 6:

type	name	label	calculation	trigger
text	a	Enter text
begin_group	grp			${a}
dateTime	c	Date of diagnostic	now()	${a}
end_group

<data>
    <a/>
    <grp>
        <c/>
    </grp>
    ...
</data>
...
<bind nodeset="/data/c" type="dateTime" />
...
<input ref="/data/a">
    <label>Enter text</label>
    <setvalue event="xforms-value-changed" ref="/data/grp/c" value="now()" />
</input>
<group ref="data/grp">
    <input ref="/data/grp/c">
        <label>Date of diagnostic</label>
    </input>
</group>

Note: this is essentially like test 2 but with a group.
Note: trigger column on begin_group should be ignored by pyxform.

[lognaturel]

This looks great to me, @MartijnR, thanks for taking the time to carefully write out all these test cases, that really helps confirm that the proposal covers the necessary ground.

One tiny thing, the value for the last case should be "now()".

[gushil]

Hi @MartijnR I've created a PR #442 to resolve this issue. As a note, I've disabled validation in test case because case no 4 and 5 is not passing validation. I think that is probably because of empty value of setvalue node created.

[gushil]

Hi @MartijnR

Created PR #447 based on @lognaturel implementation. Changed when column to trigger column.

[lognaturel]

This is now merged. We do need documentation before it gets released.