Screen Data
Screen data is a feature that allows Screens to contain interactive structures and controls enabling more efficient manipulation of complex variable types, such as Maps and Collections. How Screen data enables this is by providing a way to move variables of the evaluation process' variable context into a separate variable storage of a Screen. Certain HTML content commands are then able to read and modify these variables as the Screen is being displayed, which can add some interactivity that cannot be achieved with the usual HTML content commands. The variables also move back to the evaluation process' variable context once the user proceed away from the Screen, allowing the logic commands to make use of the possibly changed values.
Basics of Screen data variables
The core idea of Screen data is that variables are able to exist on Screens. How this works is that a variable created by a command in the Flow may be declared as Screen data, therefore becoming a Screen data variable. This is done by having the screenData attribute - common to many variable-creating logic commands - on the command resolve into a value of true. When the Flow then ends up a on Screen step, this variable becomes part of the Screen's Screen data and becomes accessible to certain HTML content commands. If one of these content commands causes the variable's value to change, the change will be reflected on the Flow logic side as well after the user leaves the Screen.
Modifying a simple value
Modifying the value of a variable can be done with or without Screen data when dealing with simple value types, such as Strings. Here's a basic input for updating the String value of the variable "pieceOfText". The dyn-value content command initializes the input with the variable's value, while the name attribute defines the name of the context variable receiving the input's value, both the same in this case.
<input name="pieceOfText" type="text" dyn-value="pieceOfText"/>
Should the variable "pieceOfText" be a Screen data variable, this same input can be done by using Screen data. The name attribute in this case is no longer needed, as bound-value just modifies the "pieceOfText" Screen data variable and that change is automatically reflected in the logic following the Screen.
<input type="text" dyn-bound-value="pieceOfText"/>
Modifying the values in a Map
Often values to be displayed on a document are inside a Map, and there can also be a need for users to be able to edit those values for the document. This operation is also doable with or without Screen data, but now there's a more notable difference between the two. The goal here is to modify the "Description" value of the Data item variable "mainProduct".
Without Screen data, the modified value has to be saved into a separate variable first.
<input name="modifiedDescription" type="text" dyn-value="mainProduct.Description"/>
In a Step following the Screen, the "modifiedDescription" value is then set as the new value for the "Description" entry. This is done with the addMapEntry command.
<addMapEntry key="Description" value="${modifiedDescription}" map="${mainProduct.}">
With the use of Screen data through the bound-value command, that command is the only thing needed - no need for an additional variable or the Map-modifying command in the following logic. It is able to manipulate the Map entry's value directly.
<input type="text" dyn-bound-value="mainProduct.description"/>
Modifying a Collection
Collections are the variables behind most tables and lists on documents, but it is a variable type that is basically unmodifiable through basic Screen inputs. A Collection as a Screen data variable, however, can be modified on a Screen with the help of the bound-repeat content command. Add, remove or reorder the items, and modify the items themselves as well - bound-repeat is one of the primary Screen data commands due to its unique capabilities.
Interactivity
An aspect of all Screen data -related commands is that they will react to modifications of the Screen data variables in real-time. So if, for example, you have two inputs with bound-value commands accessing the same variable, typing anything into one input causes the same characters to appear in the other. This feature can be used to great effect with the bound-if command, which can make elements on the Screen dynamically appear or disappear as an input on the Screen is modified. Here a notification is visible if the Number variable "amountCats" has a value higher than 30.
<input type="number" dyn-bound-value="amountCats"/><span dyn-bound-if="amountCats > 30">There might be too many cats.</span>
Optional Screen sections can easily be created with bound-if and checkbox inputs, as they can manipulate Boolean variables. Here a container for advanced options is hidden until the relevant checkbox is checked.
<input type="checkbox" dyn-bound-value="showAdvOpts"/><span>Show advanced options</span><div dyn-bound-if="showAdvOpts"> ... </div>
Screen data with secondary Flows
When making use of secondary Flows running during Screens - Screen component and Background Flows - the only way those Flows can communicate with the main Flow, as well as each other to some extent, is through Screen data. The main Flow's Screen and these secondary Flows all share the same Screen data variable storage, so whatever secondary Flows do with Screen data variables, the effects will be visible in the main Flow and its currently displayed Screen.
Any variable created in a secondary Flow declared as Screen data will put into the Screen data variable storage, but at slightly different times depending on the type of the Flow. A Screen component Flow's Screen data variables will be delivered to the storage when the Flow arrives on a Screen step, while a Background Flow's Screen data variables are delivered once the Flow finishes successfully. If a Screen data variable coming from a secondary Flow has the same variable name as an already existing Screen data variable, the value of that variable from the secondary Flow will overwrite the existing value.
A secondary Flow may also create a new Screen data variable instead of just updating an existing one. Once the main Flow's Screen is submitted, any Screen data variable that didn't exist before that Screen will become a new variable in the main Flow's variable context. Like with setting any variable, if this new variable has the same name as an existing variable in the variable context, the new value will overwrite the existing value.
Secondary Flows may also modify Screen data variables with Map and Collection values by adding entries or items into them. If the addMapEntry and addItem logic commands are set to handle Screen data and the Map or Collection they're modifying is the name of a Screen data variable, the entry or item will go into that Screen data Map or Collection. This allows a secondary Flow to, for example, add a new item into the Collection of a bound-repeat on the Screen, causing a new repeated element to appear.