IncludedFields property

ServerRelayButton.IncludedFields — { ? }

Special value available in formulas:

Item

ServerRelayButton

The button this property is part of, enabling multiple checked items in the app designer to share the same formula and be updated all at once.

Consider the fields Field1 and Field2, which should only be considered to be valid if their values are greater than 4. Without using the Item value, the Valid property of Field1 would need to use the formula Field1 > 4Field1 > 4 and the Valid property of Field2 would need to use the formula Field2 > 4Field2 > 4.

Using Item, both formulas can read Item > 4Item > 4. This is useful if you have many fields and you want to be able to update their formulas all at once. To do so, click their check boxes in Calcapp Creator and make sure that a checked field is selected. Then, when you update a formula for one checked field, you update all the other checked fields too, which is a great timesaver.

Use Item in exactly the same way you'd use the regular name. Button1.VisibleButton1,Visible and Item.VisibleItem,Visible are equivalent, for instance.

The fields that are sent to the server. This property is only consulted if the server relay button has been instructed to determine what fields to include using a formula, that is, if the FieldInclusion property returns FieldInclusion.CustomFieldInclusion,Custom.

This property requires a formula which returns an array. The elements of this array are only included if the other options of the server relay button allow them. For instance, if it has been configured not to include hidden fields, any hidden fields that are part of the array returned by this property are ignored.

Including a list of fields

This formula includes Field1, Field2 and Field3:

{ Field1, Field2, Field3 }{ Field1; Field2; Field3 }

Including a range of fields

Ranges enable a large number of fields to be referenced in a compact way. This formula includes the fields Field1 and Field5, as well as all fields that appear between them:

Field1:Field5Field1:Field5

This formula includes Field1, Field3 and Field5, as well as the fields that appear between Field3 and Field5:

{ Field1, Field3:Field5 }{ Field1; Field3:Field5 }

Including all fields of a form group, screen or the entire app

To include all fields of a form group or screen, simply write the name of the form group or screen in the formula:

{ FormGroup1, FormScreen1 }{ FormGroup1; FormScreen1 }

This technique can even be used with the app object, to include all fields in the app. Consider this formula:

IF(IncludeAllFields, { App }, { Field1, Field2 })IF(IncludeAllFields; { App }; { Field1; Field2 })

The formula above includes all fields in the app if the IncludeAllFields switch field has been toggled to its "on" position. Otherwise, it includes only Field1 and Field2.

Including fields conditionally with IF

Use IF inside of an array to include fields based on logical conditions.

This formula unconditionally includes Field1, but Field2 is only included if the value of Result is greater than 5:

{ Field1, IF(Result > 5, Field2) }{ Field1; IF(Result > 5; Field2) }

Including fields conditionally with FILTER

When there are many fields to conditionally include, using IF is not practical. FILTER takes an array as its first parameter and a logical array as its second parameter with the same number of elements as the first array. Only elements of the first array where the corresponding element of the second array is TRUE are part of the array returned from FILTER.

FILTER({ 1, 2, 3 }, { FALSE, FALSE, TRUE })FILTER({ 1; 2; 3 }; { FALSE; FALSE; TRUE }) returns the array { 3 }{ 3 }, because the elements 1 and 2 are associated with FALSE elements in the second array.

This IncludedFields formula uses FILTER to only include number fields whose values are greater than 3:

FILTER(Field1:Field5, Field1:Field5 > 3)FILTER(Field1:Field5; Field1:Field5 > 3)

This formula only includes fields with a defined value:

FILTER(Field1:Field5, ISDEFINED(Field1:Field5))FILTER(Field1:Field5; ISDEFINED(Field1:Field5))

This formula only includes visible fields:

FILTER(Field1:Field5, (Field1:Field5).Visible)FILTER(Field1:Field5; (Field1:Field5),Visible)

FILTER can also consider all fields of a form group, a form screen or the entire app, using FormScreen.Fields, FormGroup.Fields or App.Fields, respectively.

This formula includes all visible fields in the entire app:

Use | to combine fields from various sources. This formula includes all visible fields that belong to either FormGroup1, FormScreen1 or a range of fields. This formula uses the LET function to give the fields a name to cut down on repetition:

LET(MyFields := FormGroup1.Fields | FormScreen1.Fields | Field1:Field5, FILTER(MyFields, MyFields.Visible))LET(MyFields := FormGroup1,Fields | FormScreen1,Fields | Field1:Field5; FILTER(MyFields; MyFields,Visible))

Examples

{ Field1, Field2, Field3 }{ Field1; Field2; Field3 }

Makes a server relay button include the fields Field1, Field2 and Field3.

Field1:Field5Field1:Field5

Makes a server relay button include the fields Field1 and Field5, as well as all fields that appear between them.

{ Field1, Field3:Field5 }{ Field1; Field3:Field5 }

Makes a server relay button include the fields Field1, Field3 and Field5, as well as the fields that appear between Field3 and Field5.

{ FormGroup1, FormScreen1 }{ FormGroup1; FormScreen1 }

Makes a server relay button include all fields that belong to the form group FormGroup1 and the form screen FormScreen1.

IF(IncludeAllFields, { App }, { Field1, Field2 })IF(IncludeAllFields; { App }; { Field1; Field2 })

Makes a server relay button include all fields in the app if the switch field IncludeAllFields is toggled to its "on" position. Otherwise, the fields Field1 and Field2 are included.

{ Field1, IF(Result > 5, Field2) }{ Field1; IF(Result > 5; Field2) }

Makes a server relay button include Field1 unconditionally and Field2 only if the value of the number field Result is greater than 5.

FILTER(Field1:Field5, Field1:Field5 > 3)FILTER(Field1:Field5; Field1:Field5 > 3)

Makes a server relay button include the fields Field1, Field5 and all fields that appear between them, but only if their values are greater than 3.

FILTER(Field1:Field5, ISDEFINED(Field1:Field5))FILTER(Field1:Field5; ISDEFINED(Field1:Field5))

Makes a server relay button include the fields Field1, Field5 and all fields that appear between them, but only if they have defined values.

FILTER(Field1:Field5, (Field1:Field5).Visible)FILTER(Field1:Field5; (Field1:Field5),Visible)

Makes a server relay button include the fields Field1, Field5 and all fields that appear between them, but only if they are visible.

Makes a server relay button include the visible fields of the app.