Purpose of this property type
The array property type can be used by web components to hold a variable number of same-property-type values.
Such array types are able to send granular updates between server and client. For example if you change from Rhino one element's value (or for more complex element property types - such as 'component' type - if something changes in only one of the array elements) then only the change is sent over to the browser/client instead of the whole array (and the other way around - a change on client doesn't send the full array to server). In the future array types might support granular updates for add/remove element operations as well but for now those operations will result in the full value being sent.
Array types are simply defined in .spec files using '' suffix.
Array types also allow configuration options to be specified for the element type (defaults/values/tags/... + some types support type specific configuration options in .spec file) using 'elementConfig'.
For example when you would have only one 'component' typed property in the component model, you could link it to a foundset like this (more info in 'component' property type):
But if you want to have an array of 'component' values that are all linked to a foundset you can use array specific configuration option 'elementConfig' like this
Advanced .spec options
Another configuration option (that you will most likely never need) for arrays (available starting with Servoy 2019.06) is to be able to skip null design time element values completely at runtime ("skipNullItemsAtRuntime": true):
For example if in developer properties view you set on an array property ["a", "b", null, "c"] then, at runtime, the property will have ["a", "b", "c"] (it skips the null). You will probably never need to use this except when you want to create advanced custom components that have arrays of child components (so "type" : "component", "skipNullItemsAtRuntime": true) and where the security settings of a form might not allow some of the child components to be visible at runtime depending on the user that logs in. In that case those items in the array would be set to null automatically by Servoy and most of the times in this case you want to just get browser-side the child components that you can show in that array and not worry about nulls.
"pushToServer" .spec setting of an array property is currently automatically inherited by the elements of that property (so any "pushToServer" setting defined on elements of the array, so in "elementConfig" will be ingnored). That means that for example if you define the array prop. to be "shallow" watched, all it's elements will be shallow watched. If you don't define pushToServer or define "reject" then the elements of that array will not be watched inside the browser and any changes to them will not be sent to the server.
You should not use pushToServer: "deep" on array property types, as that will actually add a deep watch on the array and any change within an element of that array will be interpreted as an array prop. change and will send the full array value to the server. If you use "shallow" then the changes in array elements are watched anyway (so in the end it is similar to a deep watch), so you normally do not need "deep" anyway; "deep" is meant more for properties of types like 'object' where you can have random JSON content that you want to be deep watched (so it sends it's whole value to the server for any change - so without granular updates).
Browser/client side value
Developer handling of array properties
Array properties can be edited at design-time from Servoy Developer's properties view.
If the array property contains in it's configuration object in the .spec file "droppable": true and the element types are either custom object or component then drag and drop operations/visual selection can be used as well with the elements of the array in form designer.
Nesting with custom object and array types
Array types can be nested together with custom object types. This allows you to organize your model's properties better. For example (in .spec file):
So the 'persons' property at runtime (client side) could look like this: