Data model at the interface

Binding form fields to the data model: When the data model is already defined and attached, we can in the application form bind specific fields (UI components) to fields of the model. In the form editor every component that stores some value (e.g. text field, selection field, date, etc.) has a property "Data model key". You just need to enter in this field the key defined in our model so that the data from that component is bound to the appropriate place in the model. From that moment the component becomes two-way bound (two-way binding) to the data model – during form initialization the value from the model (if it exists) will be loaded into the field, and when the user fills in or changes that value it will be written back to the data model when the application is saved. This means that after saving the form, all bound fields update their corresponding values in the data model, so the model always reflects the current state of the application's data.

Figure 1. Example of two-way binding using the data model key

Info: You can also use one-way binding of a field to the model in situations where we only want to display a value from the model on the form but not update it based on user input. Such a one-time read is performed, for example, by inserting a reference to a model variable in texts (labels) or by using the component property valueSourceId, which will retrieve the value from the model as read-only. However, by default for editable fields we use two-way binding so that entered data is saved.

Figure 2. Example of one-way binding using valueSourceId

Keep in mind that not every form component can be bound to the model. The data model only makes sense for fields that store values. Therefore we will not bind to the model, for example, elements such as:

• links (hyperlinks),

• CAPTCHA fields,

• single radio buttons (outside radio button groups),

• popup windows,

• QR codes (if present as an image/decorative element).

All other fields (text, numeric, list selections, checkboxes, dates, sections, etc.) can and should be bound to the data model if their value is to be preserved or used outside the form itself. This binding ensures consistency – every piece of data entered by the user has its place in the model, from where it can be further processed (e.g. passed to a process).

Handling array (list) fields: The data model allows defining fields that are collections (arrays) of objects or primitive values. If in the model a field is to have multiple repetitions (e.g. a list of addresses, a list of products, etc.), you should set its multiplicityMax > 1 (e.g. null for no upper limit) and prepare an appropriate data source that returns a collection. In the form such a field can be represented, for example, by a Repeatable Section (Repeatable Section) with appropriate fields inside. It is important to correctly refer to array elements in model keys:

• collection[].field – a reference to all occurrences of the field in the collection (returns the entire list of values or e.g. a concatenation, depending on the context),

• collection[0].field – a reference to the field in the first element of the collection (index 0 means the first element, 1 - the second, etc.),

• Note: You cannot omit the index! The syntax collection.field (without [] or index) is incorrect and will cause an error preventing the form from running. You must always use array notation when referencing fields of collection elements.

• For repeatable sections in the form where the user can dynamically add/remove items, Eximee uses the variable _rowIdx assigned to that section to pass the index of the current row. In the model key an identifier then appears in the form SectionName_rowIdx. For example, if a repeatable section is bound to the collection products[] and has a field name, then the field key in the section may look like: products[SectionName_rowIdx].name. This mechanism provides binding of each dynamically added field to a unique index in the model.

Figure 3. Connecting an array field to a repeatable section

Figure 4. Connecting a Combobox located in a repeatable section to the data model