Widget Data Binding and State¶
Form widgets are configured in the form definition and operate on the current form-data XML document. The bound data node is the value that is saved with the form.
XPath Binding¶
Input widgets use their XPath attribute to select a node relative to the current data context. Leave XPath empty only for widgets whose own documentation says they do not store a value. Use an XPath that resolves to one intended node for ordinary input controls; an unresolved binding is rendered but cannot persist a user change.
Containers such as TableContent, RepeatingContent, and Spreadsheet establish an item context. Their child controls' XPaths are evaluated relative to the current row, not necessarily the form root.
Rules, Read-Only State, and Hints¶
Widgets that expose rules and Hints can be changed by the form rules engine at runtime. Rules may hide, disable, require, or otherwise format a widget. A disabled input is rendered as display content by many widgets, so treat it as read-only rather than as an editable value with a disabled HTML attribute.
The RequiredForGroup property used by supported widgets associates the widget with a validation group. A button only validates the group named by its ValidationGroup; its click script does not run when that validation fails.
List Data Sources¶
DropDown, CheckList, RadioList, TagList, and related controls obtain items from DataSources. The selected value is stored through the control binding. ValueXPath and CaptionXPath select fields from each returned item; when a caption binding is configured, the selected caption is kept in the form data alongside the selected value.
MappingXPath can copy additional fields from the selected item into the form data. If item availability depends on other form values, add those paths to MonitoredXPaths; the control refreshes when they change. CacheDataSources defaults to enabled, so disable caching only when the source must be re-evaluated for every refresh.
Literal Templates¶
Labels, button labels, HTML content, and several captions accept literal/template content. Template expressions are evaluated against the current data context when the widget is refreshed. Treat values inserted into an HTML-producing widget as untrusted unless that widget explicitly sanitizes them.