Items property

FormScreen.Items — { ? }

The items of this form screen as an array, including all form groups, fields, buttons, text boxes and named values.

Accessing all items of a form screen through this property has many uses:

The following sections detail how these scenarios can be realized. Skip to the examples at the bottom for the concise version.

Summing all number fields

This formula returns the sum of the values of all numeric fields, including number fields:

SUM(Screen1.Items)SUM(Screen1,Items)

The formula above can also be written as follows:

SUM(Screen1.Items.Value)SUM(Screen1,Items,Value)

However, as the SUM function is looking for an array of numbers to add together, and number fields return numbers through their Value properties, .Value,Value is inferred and does not need to be spelled out.

In fact, you can make the formula even shorter:

SUM(Screen1)SUM(Screen1)

In the formula above, .Items.Value,Items,Value is inferred.

Summing all fields except date and time fields

The formulas above ask all items of the form screen to return numbers that the SUM function can add together. Items that cannot do that, such as text fields, are ignored.

However, number fields are not the only fields that can return numbers, that is also true for number drop-down fields and date and time fields.

Adding together the values of number fields and number drop-down fields makes sense, but mixing values of number fields and number drop-down fields with values of date and time fields only makes sense when you want to add days to a date. (The value of a date and time field represents the number of days that have elapsed since December 31, 1899, meaning that 18,264 represents January 1, 1950.)

To process only number fields, use the NumberFields property instead. This formula adds together the values of the number fields of Screen1, ignoring date and time fields:

SUM(Screen1.NumberFields)SUM(Screen1,NumberFields)

To also include the values of number drop-down fields, use this formula:

Summing the other fields of a form screen

Let's say that the form screen Screen1 consists of ten fields, Field1 through Field10. If Field10 should contain the sum of the other fields, it is tempting to try to associate this formula with the Value property of Field10:

SUM(Screen1)SUM(Screen1)

However, that formula will not work. Instead, you'll get an error message, because you're effectively asking that the calculated value of Field10 includes the value of Field10 itself.

This is similar to trying to use the formula Field1 * 2Field1 * 2 for the Value property of Field1, effectively asking that the value of Field1 should be set to the value of Field1, multiplied by two. This is known as a circular calculation, and results in an error message.

In order to solve this issue, the formula needs to reference the fields to include in the calculation explicitly:

SUM(Field1:Field9)SUM(Field1:Field9)

Above, Field1:Field9Field1:Field9 creates an array consisting of Field1, Field9 and all items that appear between them. Notably, Field10 is not part of the array.

Enabling a button only if all fields are valid

The Enabled property of a button determines if users can interact with the button. If a button should only be enabled if all fields of Screen1 are considered valid, associate this formula with the Enabled property of the button:

AND(Screen1.Items.Valid)AND(Screen1,Items,Valid)

Above, the Screen1.Items.ValidScreen1,Items,Valid formula returns an array of logical values (TRUE or FALSE), where TRUE indicates that an item is valid and FALSE indicates that an item is invalid. The AND function, when applied to this array, returns TRUE only if all array elements are TRUE. In effect, the button is only enabled if all fields of the form screen are valid.

The items of a form screen can include not only fields, but also buttons and text boxes which don't support a Valid property. The elements of the Screen1.Items.ValidScreen1,Items,Valid array that correspond to buttons and text boxes are blank. They have no effect on the value returned from AND, as this function ignores blank values.

Making the background color red if a field is invalid

The BackgroundColor property determines the background color of a screen and all screens that follow that have no explicit background color set. That means that if the background color is set for the first screen of an app, and no other screens have a background color set, the first screen determines the background color of the entire app.

We can make use of this knowledge to make the background of the entire app red, but only if at least one field of the form screen Screen1 is invalid. This formula is associated with the BackgroundColor property of the first screen:

IF(OR(NOT(Screen1.Items.Valid)), Color.Red)IF(OR(NOT(Screen1,Items,Valid)); Color,Red)

The formula fragment Screen1.Items.ValidScreen1,Items,Valid returns a logical array, where TRUE indicates that the corresponding item is valid and FALSE indicates that the corresponding item is invalid. Applying the NOT function to this array negates every element, meaning that TRUE indicates that an item is invalid and FALSE indicates that an item is valid. (The ! operator would have had the same effect.)

Then, the OR function is applied to this array. It returns FALSE only if all elements of the array are FALSE. In other words, it returns TRUE if one or several elements are TRUE, meaning that it returns TRUE if one or several items are invalid.

Finally, the IF function is used to return the color red if one or several items are invalid. Otherwise, IF returns a blank value, which has no effect on the background color. The net effect is that the background color of the app is made red if one or several items of Screen1 are invalid.

Including all values of a form screen in an email

The Body property of email report buttons allows the body of an email to be set through a formula. While email report buttons have built-in support for including field values, through the IncludedFields property, building a text string manually to include in the email body allows us more flexibility.

Consider this formula, which should be associated with the Body property of an email report button:

TEXTJOIN(NEWLINE(), FALSE, Screen1.Items.Label & ": " & Screen1.Items.Value)TEXTJOIN(NEWLINE(); FALSE; Screen1,Items,Label & ": " & Screen1,Items,Value)

Above, the formula fragment Screen1.Items.LabelScreen1,Items,Label returns a text array, made up of the labels of the items of Screen1. The formula fragment Screen1.Items.ValueScreen1,Items,Value also returns an array, this time made up of the values of the items. Using &, the labels are joined together with the values, separated by a colon.

The resulting text array, where every element consists of a label, followed by a colon and a value, is converted into a single text string using the TEXTJOIN function. Its first parameter, NEWLINE()NEWLINE(), ensures that the array elements are separated from one another using line breaks.

Requiring all fields of a form screen to be filled out

The NextScreenAvailable property of form screens determines if users are allowed to move forward to the next screen. If a user should only be allowed to move forward once all fields of a form screen have been filled out, associate this formula with the NextScreenAvailable property of the form screen:

AND(ISDEFINED(Screen1.Items.Value))AND(ISDEFINED(Screen1,Items,Value))

The ISDEFINED function returns a logical array when its sole parameter is an array. TRUE elements in the array indicate that the fields have defined values, that is, have been filled out. Conversely, FALSE elements indicate that the fields have not been filled out.

Finally, the AND function returns TRUE only if all elements of the array are TRUE, otherwise it returns FALSE. The net effect is that AND returns TRUE only if all fields of Screen1 have been filled out, prompting the NextScreenAvailable property to only allow users to proceed once all fields have defined values.

Taking special action when all switch fields are toggled "on"

The NextScreen property of a form screen determines the screen the user is presented with when they attempt to move on to the next screen. If a warning screen should be shown, instead of the regular next screen, when all switch fields of Screen2 have been toggled to their "on" positions, associate this formula with the NextScreen property of the form screen:

IF(AND(Screen2.Items), WarningScreen)IF(AND(Screen2,Items); WarningScreen)

The AND function is looking to process logical values, a request that the switch fields of FormScreen satisfy by returning their values. In other words, this formula is equivalent:

IF(AND(Screen2.Items.Value), WarningScreen)IF(AND(Screen2,Items,Value); WarningScreen)

The formula above won't work if there are items in the form screen which use values which are not logical, such as number fields. To solve this issue, you can refer explicitly to switch fields using the SwitchFields property:

IF(AND(Screen2.SwitchFields.Value), WarningScreen)IF(AND(Screen2,SwitchFields,Value); WarningScreen)

When the formulas above are associated with the NextScreen property of a form screen, the net effect is that the user is brought to WarningScreen, instead of to the regular next screen, but only if all switch fields have been toggled to their "on" positions.

Ranges versus this property

If the form screen Screen1 only consists of the fields Field1, Field2 and Field3, these formulas are equivalent:

Screen1.ItemsScreen1,Items
Field1:Field3Field1:Field3
{ Field1, Field2, Field3 }{ Field1; Field2; Field3 }

The second formula uses a range to create an array consisting of Field1, Field3 and all items that appear between them, which in this case is only Field2.

The chief advantage of the Items property, compared to a range, is that there is no need to update formulas when additional items are added to a form screen. If Field4 were to be added to the form screen, the Field1:Field3Field1:Field3 range would have to be changed to Field1:Field4Field1:Field4 everywhere it is used.

By contrast, Screen1.ItemsScreen1,Items automatically includes Field4, and any other items that are added.

Filtering items

If you want to process only a subset of the items returned from this property, use the FILTER function. It can base its decision on which items to return on the property values of the items.

This formula only returns visible items:

FILTER(Screen1.Items, Screen1.Items.Visible)FILTER(Screen1,Items; Screen1,Items,Visible)

Crucially, you can also filter on the names of the items, using standard text functions. This formula only returns items whose names include the text string "Required":

FILTER(Screen1.Items, CONTAINS(Screen1.Items.Name, "Required"))FILTER(Screen1,Items; CONTAINS(Screen1,Items,Name; "Required"))

If you use a deliberate naming strategy for your items, you can use FILTER in conjunction with this property to ensure that you only process a specific subset of items.

Related properties

Use the Items property of a form group to access all items of said form group and the Items property of the app object to access all items of the entire app.

There are many other properties that return only certain items. For instance, Fields returns all fields of a form screen, whereas NumberFields only returns the number fields of a form screen.

Examples

SUM(Screen1)SUM(Screen1)

Returns the sum of the values of all number fields, number drop-down fields and date and time fields that belong to Screen1.

SUM(Screen1.Items)SUM(Screen1,Items)

Returns the sum of the values of all number fields, number drop-down fields and date and time fields that belong to Screen1. If .Items,Items is left out, it is inferred.

SUM(Screen1.NumberFields)SUM(Screen1,NumberFields)

Returns the sum of the values of all number fields that belong to Screen1.

Returns the sum of the values of all number fields that belong to Screen1. If .Value,Value is left out, it is inferred.

Returns the sum of the values of all number fields and number drop-down fields that belong to Screen1.

AND(Screen1.Items.Valid)AND(Screen1,Items,Valid)

Returns TRUE if all fields of Screen1 are valid and FALSE otherwise. Screen1.Items.ValidScreen1,Items,Valid returns a logical array, where each element reflects whether its corresponding item is valid. Finally, the AND function returns TRUE if all elements are TRUE and FALSE otherwise.

TEXTJOIN(NEWLINE(), FALSE, Screen1.Items.Value)TEXTJOIN(NEWLINE(); FALSE; Screen1,Items,Value)

Returns all field values of a form screen as a text string, where values are separated from one another using line breaks. The formula fragment Screen1.Items.ValueScreen1,Items,Value returns an array of values, which the TEXTJOIN function joins together with line breaks.

AND(ISDEFINED(Screen1.Items.Value))AND(ISDEFINED(Screen1,Items,Value))

Returns TRUE if all fields of Screen1 have been filled out. When the ISDEFINED function is applied to an array of items, it returns a logical array whose elements indicate if the corresponding item has a defined value. The AND function returns TRUE if all array elements are TRUE and FALSE otherwise.

Returns TRUE if all switch fields of Screen2 have been toggled to their "on" positions. Screen2.SwitchFields.ValueScreen2,SwitchFields,Value returns a logical array containing the values of all switch fields. The AND functions returns TRUE if all array elements are TRUE and FALSE otherwise.