Function to access the value of a control

[ebruchez]

Issue #2471 is about accessing the value of a control within a section template. This issue is about a function independent from section templates.

We could name the function, as suggested in #2471, fr:control-value($name).

See also #2471, #2909, #309, #2113.

[ebruchez]

Must work from

• actions
• processes
• formulas
• fr:databound-select1 itemsets

The function would work locally within a section template (later see #2471).

Dependencies

Formulas raise the question of dependencies, which we currently (optionally, and enabled by default since 2018.1 for new forms) handle via variables.

• See DependencyAnalyzer and #2186.
• Options:
  • rename uses of fr:control-value() back and forth to a variable reference in formulas
  • not great: what if the semantic is not identical?
  • make DependencyAnalyzer aware of fr:control-value()
  • not great: we don't want XForms code depending on Form Runner concepts
  • make fr:control-value() an XForms function, like xf:control-value()
  • but when it would have to take an id, and we like having "names" in Form Runner

In addition, also handle PathMap dependencies, where fr:control-value('foo') resolves to a bind by name, which translates to a path.

Repeat resolution

Currently, we have resolution with:

• variables in binds
• bind and the bind() function

We need to determine how fr:control-value() resolves repeated controls.

[ebruchez]

One way to go about this:

• for formulas, we keep variables in UI as well as in the stored XPath expressions
• for other uses, the user sees variables, but we rewrite them to Form Runner functions

This allows DependencyAnalyzer to remain unchanged when handling calculate and default formulas.

[ebruchez]

For repeat resolution, the first use case we have are dynamic LHHA. In this case, the expression is in the view. It should probably resolve the same way we resolve controls within actions, "the control which is the closest by following repeat iterations and repeat indexes is chosen". This is implemented by FormRunner.resolveTargetRelativeToActionSource. Note that there are two options:

• followIndexes = true(): older behavior for setting values, etc.
• followIndexes = false(): behavior for setting item choices, which can resolve to more than one control

Since this is resolved from LHHA which are on controls which are relevant and necessarily have binds, could we use the regular bind resolution instead? Not obvious as this could also be used from other places.

Also, what type should the value have? If the node has a type, say xs:date, should we return that? Or the formatted value? I would think that the value should have the type when possible, and that formatting should be done somewhere else, like with xxf:r().

Thinking we might want to have:

• fr:control-string-value($control-name as xs:string, $follow as xs:boolean) as xs:string*
• fr:control-typed-value($control-name as xs:string, $follow as xs:boolean) as xs:array(xs:anyAtomic)

Should the user be allowed to choose:

• whether to get the string or typed value?
• whether to follow repeats or not?

Tasks:

• [x] implement function
  • [x] basic implementation
  • [x] PathMap: anything that makes sense?
  • See further comment below.
• [x] tests
• [x] doc

[ebruchez]

For PathMap, in theory, we could build the projection if we know statically the ancestors of the control. For example:

fr:control-string-value('foo')

Points to the projection:

instance('fr-form-instance')/section-1/section-2/grid-3/foo

Except that the same cached expression could occur in two different forms with a different data model. So that won't work without making sure the expression is different!

So I suggest that for now, we do not include support for PathMap.

[ebruchez]

Documented