Custom object property types

Purpose of custom (object) property types

The custom object property type can be used by web components to logically group a number of subproperties (that can be of different types) for easier usage.

Such custom object types are able to send granular updates between server and client. For example if you change from Rhino one subproperty value (or for more complex element property types - such as 'component' type - if something changes in only one of the subproperties) then only the change is sent over to the browser/client instead of the whole custom object (and the other way around - a subproperty change on client doesn't send the full object, just the change to server).

Custom object types are defined in .spec files with a fixed set of subproperties as below:

.spec file

    "model": {
        (...)
        "myPerson": "person"
		(...)
    },
    (...)
    "types": {
        "person": {
          "firstName": "string",
          "lastName": "string",
          "photo": "dataprovider"
          "styleClass" : { "type": "styleclass",
                           "tags": { "scope" :"design" },
                           "values": ["form-control", "input-sm", "svy-padding-xs"] }
        }
    }

Browser/client side value

The browser value of such a property is a Javascript object containing the defined sub-properties:

    {
        "firstName": "John",
        "lastName": "Doe",
        "photo": "https://...."
    }

Server side javascript value

The server side JS value of such a property is a custom implementation based on Javascript object - so you should be able to use it just like a normal JS object.

There is one difference though. In order to be able to send fine-grained updates to the client/browser, those values are 'watched'. That means that whenever you assign a completely new javascript object directly to the property (or if you assign a new object/array to one of it's sub properties on any level), that new value (reference) you assign will not be 'watched' directly; you have to take/read it back from the property (which will give you an equivalent 'watched' value) before using it further in code. Or you can access the value of the property directly every time, not kept as a reference.

For example:

DO it like this

var newPropertyValue = { mySybproperty2 : 10 };
// here you assign a new object to the property
elements.myCustomComponent.myObjectProperty = newPropertyValue;
// here you update the reference that you want to use later in code with the 'watched' new value
newPropertyValue = elements.myCustomComponent.myObjectProperty;
(...then later on, maybe during another event handler execution...)
// this modification will be detected because it's using the new 'watched' value you got from elements.myCustomComponent.myObjectProperty after it was assigned - and the change will be sent to the browser
newPropertyValue.mySybproperty1 = 5;

DON'T do it like this

var newPropertyValue = {};
// here you assign a new object to the property
elements.myCustomComponent.myObjectProperty = newPropertyValue;
(...then later on, maybe during another event handler execution...)
// this will modify the value in newPropertyValue but myCustomComponent.myObjectProperty will not be aware of that to send changes to client/browser
newPropertyValue.mySybproperty = 5;

Developer handling of custom object properties

Custom object properties can be edited at design-time from Servoy Developer's properties view and/or using drag and drop operations depending on type and configuration options. (TODO add more details here)

Nesting with custom object and array types

Custom object types can be nested with array types. This allows you to organize your model's properties better. For example (in .spec file):

    "model": {
        (...)
        "persons": { "type": "person[]" }
		(...)
    },
    (...)
    "types": {
        "person": {
          "firstName": "string",
          "lastName": "form",
          "profilePhotos": "dataprovider[]"
        }
    }

So the 'persons' property at runtime (client side) could look like this:

[
    { "firstName": "John", lastName: "Doe",
      "profilePhotos": [ "https://....", "https://...." ] },
    { "firstName": "Bob", lastName: "Smith",
      "profilePhotos": [ "https://....", "https://...." ] },
    { "firstName": "Jane", lastName: "Doe",
      "profilePhotos": [ "https://....", "https://...." ] },
]

Child pages