SwitchFields property
The switch fields of this form group as an array.
Accessing all switch fields of a form group through this property has many uses:
- Only showing a form group if all switch fields of another form group have been toggled to their "on" positions.
- Enabling a button only if all switch fields of a form group are valid.
- Deciding which background color to use based on whether the switch fields of a form group are valid.
- Collecting the labels and values of all switch fields of a form group as a text string, for use as the body of an email.
The following sections detail how these scenarios can be realized. Skip to the examples at the bottom for the concise version.
Requiring all switch fields to be toggled "on"
The Visible property of a form group determines if it is visible to the user. If a form group should only become visible once all switch fields of FormGroup1 have been toggled to their "on" positions, associate this formula with the Visible property of a different form group:
When this formula is associated with the Visible property of another form group, the net effect is that the form group is only made visible once all switch fields have been toggled to their "on" positions.
Enabling a button only if all switch 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 switch fields of FormGroup1 are considered valid, associate this formula with the Enabled property of the button:
Above, the FormGroup1.SwitchFields.ValidFormGroup1,SwitchFields,Valid formula returns an array of logical values (TRUE or FALSE), where TRUE indicates that a switch field is valid and FALSE indicates that a switch field 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 switch fields of the form group are valid.
Making the background color red if a switch 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 switch field of the form group FormGroup1 is invalid. This formula is associated with the BackgroundColor property of the first screen:
The formula fragment FormGroup1.SwitchFields.ValidFormGroup1,SwitchFields,Valid returns a logical array, where TRUE indicates that the corresponding switch field is valid and FALSE indicates that the corresponding switch field is invalid. Applying the NOT function to this array negates every element, meaning that TRUE indicates that a switch field is invalid and FALSE indicates that a switch field 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 switch fields are invalid.
Finally, the IF function is used to return the color red if one or several switch fields 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 switch fields of FormGroup1 are invalid.
Including all switch field values of a form group 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:
Above, the formula fragment FormGroup1.SwitchFields.LabelFormGroup1,SwitchFields,Label returns a text array, made up of the labels of the switch fields of FormGroup1. The formula fragment FormGroup1.SwitchFields.ValueFormGroup1,SwitchFields,Value also returns an array, this time made up of the values of the switch fields. 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.
Ranges versus this property
If the form group FormGroup1 only consists of the switch fields Field1, Field2 and Field3, these formulas are equivalent:
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 SwitchFields property, compared to a range, is that there is no need to update formulas when additional switch fields are added to a form group. If Field4 were to be added to the form group, the Field1:Field3Field1:Field3 range would have to be changed to Field1:Field4Field1:Field4 everywhere it is used.
By contrast, FormGroup1.SwitchFieldsFormGroup1,SwitchFields automatically includes Field4, and any other switch fields that are added.
Filtering switch fields
If you want to process only a subset of the switch fields returned from this property, use the FILTER function. It can base its decision on which switch fields to return on the property values of the switch fields.
This formula only returns visible switch fields:
Crucially, you can also filter on the names of the switch fields, using standard text functions. This formula only returns switch fields whose names include the text string "Required":
If you use a deliberate naming strategy for your switch fields, you can use FILTER in conjunction with this property to ensure that you only process a specific subset of switch fields.
Related properties
Use the SwitchFields property of a screen to access all switch fields of said screen and the SwitchFields property of the app object to access all switch fields of the entire app.
The Fields property returns all fields of a form group, not just switch fields. The Items property returns all items of a form group, including fields, buttons, text boxes and named values. Use NumberFields, TextFields, DateTimeFields, NumberDropDownFields and TextDropDownFields to access other kinds of fields.
Examples
Returns TRUE if all switch fields of FormGroup1 are valid and FALSE otherwise. FormGroup1.SwitchFields.ValidFormGroup1,SwitchFields,Valid returns a logical array, where each element reflects whether its corresponding switch field is valid. Finally, the AND function returns TRUE if all elements are TRUE and FALSE otherwise.
Returns all switch field values of a form group as a text string, where values are separated from one another using line breaks. The formula fragment FormGroup1.SwitchFields.ValueFormGroup1,SwitchFields,Value returns an array of values, which the TEXTJOIN function joins together with line breaks.
Returns TRUE if all switch fields of FormGroup1 have been toggled to their "on" positions. FormGroup1.SwitchFields.ValueFormGroup1,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.