Listening and clearing

• Listening and clearing are mechanisms that allow defining dynamic behavior of form components and their associated variables. They enable changes in one field to automatically affect other fields, components, or values in the form.

• Listening attribute (ListeningOn) – allows specifying which other components or variables a given component "listens to." This means that a change in the value of the indicated component or variable will cause the listening component to react — for example, by recalculating its value or refreshing its visibility.

• Field Clear attribute (ClearOn) – defines which changes in other components or variables will trigger automatic clearing (removal) of the value of a given component. In other words, if the specified related field or variable changes its value, the component with clearing enabled will remove its current value (clear the field).

• Both of the above attributes are available in the Interactions section of the properties panel for the selected component. Configuration is done via a special window — click the List next to the Listening or Field Clearbutton, which will open a popup to edit these settings.

Illustration 1. The "Interactions" section

• In the Triggering elements list (opened by the Listbutton) a list of components that the control listens to is displayed. The list can be narrowed using the filter field (Filter...) at the top of the window. Next to each added item there is a trash icon — it appears when hovering — which allows removing that item from the listening list.

Illustration 2. Element selection window for listening

• To add a new element to listen to, use the Add MID field at the bottom of the window. This field suggests all available identifiers (MID/ID) of components and variables that can be listened to. Choose the desired component from the suggestion list (by clicking it or confirming with the Enter key). The selected element will be added to the list, and the Listening attribute description in the properties panel will show information about the number of listened elements (e.g. Listenings: 1).

Illustration 3. Pointing the element to add

• Note: If validators, services or conditions (visibility, activity, requiredness) that refer to values of other fields or variables are used in the component logic, you should correctly set Listening (and possibly Field Clear) for those dependencies. Otherwise changes in the related fields will not be automatically taken into account by that component.

Usage examples

• Automatic field recalculation – A calculated field (e.g. the sum of two values) listens for changes in the source fields. If the user changes the value in any of the constituent fields, the sum field will automatically recalculate its value.

• Dynamic section visibility – A form section displayed conditionally (e.g. additional details shown after checking the "Show more"checkbox) should listen to that checkbox. This way changing the checkbox state will immediately re-evaluate the condition and hide or show the section according to its definition.

• Resetting a dependent field value – A field that should be cleared after another selection changes uses the Field Clearattribute. For example, the "Car model" field may listen to the "Car brand" field and have clearing set with respect to it. Changing the brand will automatically remove the previously selected model value so the user can choose a new model matching the changed brand.

• Refreshing the document list after changing the page – The Document list (DocumentList) component can listen to the currentPageMid variable (the identifier of the current form page). This causes the component to reload/refresh its data when navigating to a different page of the application. That prevents displaying an outdated set of documents (e.g. prints) after a page change.

FAQ

• Q: What is the difference between the Listening and Field Clear? A: Listening causes the component to react (recalculate or refresh) in response to a change in the value of a specified other field or variable. Whereas Field Clear causes the component's current value to be automatically erased when the indicated related field or variable changes.

• Q: Do I have to set listening if my component uses a condition or validator that refers to another field? A: Yes. If the component logic (e.g. visibility or requiredness condition, validator script, etc.) uses the value of another field or variable, the component must listen to that element. Otherwise changes to that field's value will not be reflected in real time — the condition or validation will not react to the changed data.

• Q: I set the Field Clearattribute, but the field does not remove its value when the related component changes — why? A: Most likely the listening attribute is missing. For field clearing to work correctly, the target component must also listen to the indicated triggering element. In other words, in the component configuration you should add Listening together with Field Clear referring them to the same component whose change should clear the value.

• Q: How do I add or remove an element from the listening list for a given component? A: Open the listening configuration window — in the properties panel click List next to the Listeningattribute. In the Triggering elements list window a new element is added via the Add MID field (by typing or selecting the appropriate component/variable from the list and confirming with Enter). To remove an element from the listening list, hover over its name in that window and click the trash icon next to it.

• Q: What elements can be listened to? A: A form component can listen to changes of other components (form fields) and to session variables associated with the form. During configuration, the listening window provides a full list of IDs/MIDs of all fields and variables that can be chosen as listening sources.