Property Types

This version of the Property Types page is meant for custom components / services creators. For a basic version that only details how these types can be used inside Servoy solutions, see this page instead.

Not all property types are really meant for usage as API method parameters. Some of them are really meant for model property types only. Examples: dataprovider, tagstring (normal string will translate i18n, tags can't be resolved through api), media and valuelist (create a dataset out of a valuelist and with application.getValueListItems("vlname")), ...

Provided property value types

boolean

Boolean value, either true or false

border

CSS border string representation

clientfunction

This property type must be used in Titanium if the value of the property represents a javacript function that has to run client side. In NG1 (tag)string property type was used for this purpose, but for Titanium NG Client we must know when it is meant to be a client side javascript function rather then a simple string (due to Content Security Policy - security reasons). It is still a string at design time in both cases.

For NG1 it works the same as a tagstring property type and you can run the code inside the browser. But for Titanium this is handled differently: the component gets a function that is retrieved in a way that the browser allows - directly from the model (instead of getting a string and do an eval(string) on it to generate the function). This difference is because in Titanium it is not allowed to do eval in the browser by default - Content Security Policy doesn't allow that for security reasons.

Starting with version 2023.09, it is supported to use clientfunction(s) in the designer (input is still a simple string input) not just in properties typed that way in the component but also inside pure map or json property type values - but then - for a known possible sub-property/key that has 'clientfunction' type, this must be set in the .spec file of the component / service as a "value_types" tag on the map/json property type declaration; see map for an example.

If, for a 'map' or 'json' typed value, the sub-property/key that is supposed to be a 'clientfunction' is not set in the .spec file correctly (that it should be seen as a 'clientfunction') - or if you need to use it in a plain 'object' type - then this can be done correctly in Titanium through code, by creating a client side BrowserFunction explicitly - see clientutils.generateBrowserFunction(...)

color

String color value

Example:

#FFFFFF

dataprovider

Reference to a dataprovider, either a record or scope/form variable.

Can become a complex definition if it needs to support onDataChange, it needs to be able to send changes to server or display tags.

The ondatachange handler will receive as parameter the old datarovider value, the new dataprovider value and a JSEvent.

Starting with 2021.06 release the JSEvent.data will contain an object: {dataprovider : dataProviderID, scope : dataproviderScope, scopeid : variable_scope_or_datasource}.

Definition:

{ 
    "type": "dataprovider",
    "pushToServer": "allow", // optional: needed if you want this component
        // to be able to change the dataprovider's value on the server
    "ondatachange": { // optional
        "onchange": "onDataChangeMethodID", // the name of a handler
            // defined in spec
        "callback": "onDataChangeCallback" // the name of an API func
            // defined by the webcomponent that will get called when
            // pushed data change is successfully applied on server
    },
    "forFoundset" : "myFoundsetPropertyName", // optional; if specified
        // then on the client instead of one value you will get an
        // array of values one for each record in the viewport of given
        // foundset property (see also 'foundset' property type)
    "displayTagsPropertyName" : "myDisplaysTagsProp", // default is null.
        // If specified then the property will initially read the
        // boolean value of the property with given name; If that
        // property is true, tags (%%x%%) will be replaced, otherwise
        // they will be ignored (in which case it will just replace i18n
        // and html); if null, tags will be replaced or not based on
        // config option "displayTags"
    "displayTags" : false, // default is false. If displayTagsPropertyName
        // is non-null it will be ignored. Otherwise, only if it's value
        // is true, this property will parse tags (%%x%%)
    "resolveValuelist" : false // optional, default value is false
        // this is an optimization for read-only dataproviders
        // if true, the dataprovider will send directly the display value
        // from linked valuelist instead of real value; valuelist will
        // have no values sent to client; this way client doesn't need
        // to resolve the valuelist value anymore
}

Starting with 8.4, if 'forFoundset' above is used, then the client-side (in browser) value also provides two methods: addChangeListener / removeChangeListener. So you can add a listener that will receive updates (row insert/delete/change or full viewport update) similar to how the change listener in foundset property type works. Remember to always remove any added change listeners when the component's $scope is destroyed - similar to what is described in the link for the foundset property type listener.

In order for dataprovider typed properties to 'push' their value changes to the server (so changes in the browser to end up in records or scope/form variables) you must either use autoApply or directly apply / startEdit. If you do not 'apply' (auto or manually) the change, the updates will not be sent to server.

IMPORTANT In order to be able to change server-side dataprovider values using apply or svy-autoapply, the .spec file must declare that dataprovider property from the model as pushToServer: allow or higher. Otherwise the server will reject the dataprovider value updates and log a change denied warning.

Simple example of read-only dataprovider: .spec

{
    "name": "my-component",
    "displayName": ...,
    (...)
    "model":
    {
            "myDataProvider" : "dataprovider",
            (...)
    },
    (...)
}

.html

<input (...) ng-model="model.myDataProvider" svy-autoapply />

In server-side (solution) scripting, accessing a dataprovider property - for example "elements.myField.myDataprovider" - will yield a string: the dataprovider id (name of variable/column). You can also assign a dataprovider id (string) to that property.

Client side, the value of a dataprovider property depends on the actual value of the dataprovider (column/variable/...) as well as the type of the dataprovider (is it a number in the database, or a blob / string / date etc.).

For primitives dataprovider types, it will be the primitive value. For date dataprovider types, it will be a Date object on client.

For MEDIA typed dataproviders the client-side value depends on the server side value's content:

if the value is a BLOB / byte array then client-side you will get an object with two keys: { url: ... , contentType: ... } that can be used to load that content in the browser
if the value is a date, you will get a Date on client
if the value is a string:
- if it starts with "media:///" it will be an URL string on the client that points to that server side media resource from the solution
- other strings will be treated as strings
primitive types will just be sent 'as-is' to client

dataset

JSDataSet type equivalent. Currently can be used only for runtime api or model (to send a dataset to client).

Example

"jsDataSet":{"type" :"dataset", "includeColumnNames": true,
                                 "columnTypes":{ "icon" : "media" }}

The type can have two configuration properties:

includeColumnNames , default false, will also send the column names as a separate array to client as the first row
columnTypes can specify some column types which will be used for converting the value to send client side, this is needed for non basic columns/types

date

Date value

dimension

Dimension representation

Example

{
    width: 100, 
    height: 20
}

double

A floating point number

findmode

This property is for handling the find mode for a component (if the component needs to react spefic to findmode, like no formatting, allowing any kind of input) See findmode property type

font

CSS font string

form

URL string pointing to a form (like tab in tabpanel)

format

Format string.

Given an object in the .spec file - to be able to specify which dataprovider and/or valuelist property to map this format property on. The 'for' value can be one property name (pointing to a dataprovider-type property or a valuelist property or a string property), but it can also contain an array of 2 properties (one being a dataprovider-type property and the other a valuelist property).

It needs the 'for' clause to be able to deduct the type of the format (format depends on DP type, whether or not the valuelist has real/display values or not, ...). If you put a valuelist property in the "for" and that valuelist property has itself a "for" that points to a dataprovider property (that might be linked to a foundset or not) then you must add that same dataprovider property to the "for" clause of the format property as well. If you put a string property in the "for", the value of string property defines the type of the format, and it can be one of the following values: 'TEXT', 'NUMBER', 'DATETIME'.

Example 1

myFormatProp : { type: 'format', for: 'myDataProviderProp' }

Example 2

myFormatProp : { type: 'format', for: ["myValuelistProp", "myDataProviderProp"] }

Format property access from solution scripting will give the string value of the parsed format** . Assignment** to a 'format' typed property allows you to set a new format string.

foundset

Used to interact with server-side foundset from the browser (component properties can have this type). Accessible (if the component allows it) in server-side solution scripting and in properties view - when designing forms as well. See Foundset property type.

foundsetRef

Can be used to send a 'reference' of a server side foundset to the client. It is meant for handlers or server-side-API-calls - as argument type or return type. If server-side scripting returns/gives a foundset to such a type, browser side scripting will receive an unique foundsetId/reference to that foundset. Browser/client side scripting can later send that id back to server-side scripting and it will automatically be transformed into the original foundset object by this property type. See also Foundset property type - Combining Foundset Property Type, Foundset Reference Type, Record type and client-to-server scripting calls. The foundset that you want to pass a reference to should already be in the model on the client to send the reference back to the server. Its not use to use this as a foundset reference with a Server to Client call if you want to pass on the foundset as an api argument.

function

Callback function / function information that can be called on server from client. A callback function set for this type of property will be represented in the component model:

(old way of doing things) as a pair of "formname" and "script" that can be used as parameters for "servoyService.executeInlineScript" to execute it; servoyService is a service exposed by the @servoy/public package as ServoyPublicService.
starting with 2024.03, the value is directly a function, that does what is needed under the hood (without the need to use servoyService.executeInlineScript). For compatibility reasons, it does still have the "formname" and "script" properties set on it.

Example:

in the component spec

"model": {
    "myFunction" : { "type": "function"}
}

Starting with 2024.03 client side code can call that function directly:

this.myFunction(arg1, arg2); // arguments can be given as normal arguments to the function

So starting with 2024.03 there is no need to have a reference to the servoyService or use/know about the 2 properties (formname, script). It can be used directly as a function.

(old way) before 2024.03 (it still works in newer builds as well, for backwards compatibility reasons): in the component js implementation one needed to use the servoyService.executeInlineScript function

servoyService.executeInlineScript(this.myFunction.formname, this.myFunction.script, [arg1, arg2]);

Note that, in the old way, the component needs to have a reference to the "servoyService" service; the "formname" and "script" values are already encrypted in the model value; in the old way you needed to use those values (and not plain text values for formname and script). Arguments for the callback could be set using the last parameter of "servoyService.executeInlineScript".

insets

Padding insets representation

Example

{
    paddingTop: 10px, 
    paddingLeft: 20px,
    paddingBottom : 10px,
    paddingRight: 10px
}

int

An integer number

JSEvent

Type only used in handler call that go from client to server, see "Specification"

labelfor

Type for labelfor property of the label.

map

A map of key/value pairs. It's main purpose is converting string values, like "true"/"false" to boolean types, numbers as strings to number types (useful when using developer's properties view to assign values), and supporting i18n tags as values. It mostly supports primitive values, it does support nested structures since Servoy 2023.09 in the designer but only if those specific keys are marked like that through the "tags" spec attribute adding there an "value_types" entry, this is also needed to mark certain keys as clientfunction, for more full support of pure json with fully nested structurs look at the json property type

currently value_types can only have "map" or "json" as nested structures and "clientfunction" as the special value type that needs to be process specially.

Example

"gridOptions": {"type": "map", "tags": {"value_types": {"callback": "clientfunction","nested": {"type":"json","value_types": {"anothercallback": "clientfunction"}}}}},

json

This is like a map property type it has the same runtime behavior but it is more relaxed in what you can type in the designer, because that is a free textfield for a complete json definition, it has the same support for letting the designer/runtime know what types it can have internally to make sure thet clientfunction are send to the client see map for an example

The json property type also has basic support for typing through arrays then the value_types is mapping on the objects inside the array

"gridOptions": {"type": "map", "tags": {"value_types": {"array": {"type":"json","value_types": {"callback": "clientfunction"}}}}},

will work for the json structure

{
    "array": [
        {
            "callback": "function() {return 'test' }"
        }
    ]
    ]
}

so the value type "callback" will map on the internal objects in the array.

media

Reference to a Media entry. Media can be given in different ways on server (media name, media uuid, media url - for example "media:///servoy.jpg" -, media id). Client-side it will be an URL (string) that points to the media resource from the server.

object

Generic JSON type. When using this type, you should pass primitive values or objects/array of primitive values and objects/arrays - because it will generally not be able to handle correctly other types of values (for example you cannot give a foundset or a border and expect them to work). You should use more specific types from this list whenever possible instead of this generic type. The 'object' type relies on standard JSON to transfer it's contents to the browser; it tries to use some default conversions to make the value be a JSON-valid value (but the safest way is for you to give only what JSON allows as value).

point

Point representation

Example

{
    x: 10, 
    y: 20
}

protected

boolean security property, can be used to protect the entire component or specific properties or handlers in the component. For more information about 'protected' property type see this page.

Configuration:

Example

"enabled" : { "type": "protected", "blockingOn": false, "default": true }

modifiable

A security property, that can be used for nested data providers (like columns of a grid) - where some columns have a "dataprovider property type" that can be edited but some columns should not be editable. The dataprovider that it targets is given by the component's .spec file using the "for" config option of the 'modifiable' property type.

This property is a string property, so any non-null string can be set - if you want the attached data provider to be editable. But if you set a null value, then the server will not allow a change for that data provider.

If none of the nested data providers nested in an array is meant to be editable (but the root property needs to allow changes from client), then it is better to mark the dataprovider property directly as "pushToServer": "deny" instead of using "modifiable". So this type is meant to be used only for components that have optional editable support for data providers nested in arrays/custom objects. So data providers that would normally allow a send-to-server can be blocked if the component wants to allow the developer to block editing for some of those data providers (for example some columns).

record

Reference to a Record. You can use this type:

to send a Record identifier to browser/client code from server that can then be sent back to server later using the same type to become/be translated to the initial Record on server.
(starting with Servoy 8.3) to send a client/browser 'foundset' property type's row directly to server (using "record" property type for that); it will be translated to the actual Record on server. E.g.:

this.recordClicked(this.myFoundset.viewPort.rows[idx]);

(starting with Servoy 8.3) to send a client/browser 'foundset' property type's row to server using "foundsetProp.getRecordRefByRowID(id)". E.g:

// if the component uses the rowId internally to identify rows
var rowId = this.myFoundset.viewPort.rows[idx][$foundsetTypeConstants.ROW_ID_COL_KEY];
// (...)
// then it can just send a Record ref. to server using that
// ID directly without the need to get the actual row
this.recordClicked(this.myFoundset.getRecordRefByRowID(rowId));

See also "Foundset property type" - Combining Foundset Property Type, Foundset Reference Type, Record type and client-to-server scripting calls if you you are curious about how 'record' type can be used in combination with other types to create complex components.

relation

Reference to a Relation (this is a string, so if used as a api parameter, this would just mean the relation name)

rowRef

Starting from Servoy 8.3, 'record' type should be used instead. See 'record' type above.

DEPRECATED: (to be used only in 8.2) Also known as "Record Finder type". Can be used to send a rowId (from a foundset type property's viewport) from browser scripting to server side scripting. The property type will return a 'finder' function. When you call that function with the foundset as an argument it will return the record that corresponds to that rowId from the client. See Foundset property type - Combining Foundset Property Type, Foundset Reference Type, Record type and client-to-server scripting calls for and example of how it can be used.

runtimecomponent

The type of component (so that components can be passed as parameters)

scrollbars

An integer value which represents scrollbar definition. This type is used for designer to display special editor.

string

Plain string property. I18n keys will be resolved by default.

securestring

This type can be used to send a string client side that is used for state that is send back server side that is then used in some script. This can be something like an "id" or "name" that makes a certain thing special (like a breadcrumbid to know where you clicked on). This kind of id's are not need to be read as a value on the client or should be changable on a client and then being pushed, trying to trick the server script. For this 'securestring' type makes sure that the value is encrypted so has no meaning client side and also can't be altered and send to the server because the server expects this to be an valid encrypted string.

@since 2024.3.1

styleclass

String with space separated CSS classnames.Possible values supported by the component can be specified as hint for the developer

Example specifying special classnames supported by the component as hint for the developer

{
    type:'styleclass', 
    values:[
        'btn',
        'btn-default',
        'btn-lg',
        'btn-sm',
        'btn-xs'
    ]
}

In Servoy version below 8.3 if you name the property "styleClass" that has the "styleclass" type also element.addStyleClass and element.removeStyleClass will work and will add or remove style classes from that property. With 8.3 this still works but you can mark any styleclass property type to be the "mainStyleClass" by adding the tag 'mainStyleClass' and set the value to true for this property:

{
    "type": "styleclass",
    "tags": { "mainStyleClass":true}
}

tabseq

Tab sequence integer value. See sablo-tabseq

tagstring

String property that can optionally contain %%tags%%, html with links to media files or it can be an i18n key. It can also be a just a simple static string. It will be pre-processed before being provided to the web component, depending on the configuration options below.

Examples:

Example

Hello %%name%%, welcome to %%i18n:com.mycompany.mykey%% ...
    or
i18n:com.mycompany.mykey
    or
<html>...some html that can also contain links to media in it</html>
    or
just some static string

Here is how this type of property can be configured in the component's .spec file:

Definition

myTextProperty : {
    "type" : "tagstring",
    "displayTagsPropertyName" : "myDisplaysTagsProp", // default is null.
        // If specified then the property will initially read the
        // boolean value of the property with given name; If that
        // property is true, tags (%%x%%) will be replaced, otherwise
        // they will be ignored (in which case it will just replace i18n
        // and html); if null, tags will be replaced or not based on
        // config option "displayTags"
    "displayTags" : false, // default is true. If displayTagsPropertyName
        // is non-null it will be ignored. Otherwise, only if true this
        // property will parse tags (%%x%%)
    "useParsedValueInRhino" : true, // default is false. Server side
        // scripting read/modify will work with: if false the parsed
        // (with tags/i18n already replaced, so static) value, if true
        // the non-parsed (value containing %%x%% or i18n:..., which
        // will be after modify parsed) value
    "forFoundset" : "myFoundsetPropertyName" // optional; if specified
        // then on the client instead of one value you will get an array
        // of values one for each record in the viewport of given
        // foundset property (see also 'foundset' property type)
},
displaysTags : { "type" : "boolean", "scope" : "design" } // needed only
        // if "displayTagsPropertyName" is used as above

or simply (to use default config values):

Example

myTextProperty: "tagstring"

titlestring

String property similar to tagstring, but with support to use as default value the title string form a table column. It has a setting key: "for", that contains the dataprovider property from where the table column would be determined.

Configuration:

Example

"headerTitle": {"type" : "titlestring", "for": "dp"},
"dp": { "type": "dataprovider", "forFoundset": "myFoundset", "resolveValuelist" : true}

valuelist

Reference to a ValueList.

Supported configuration (in .spec file, next to the type of the property)

Valuelist property access from solution scripting will give the valuelist name. Assignment to a 'valuelist' typed property allows two types of values:

if you assign a String to it that will be interpreted as a valuelist name - and the valuelist with the given name is put in that property
if that property already contains a custom valuelist and you assign a Dataset to it then it will alter the items of the custom valuelist for that property of that element only.

For example, serverside:

// will output the name of the valuelist that is currently in "myValuelistProp"
application.output(elements.mycomponent.myValuelistProp);
 
// the following code would change the items of a custom valuelist inside one
// of the columns of a servoy-extra table component
elements.myExtraTable.columns[1].valuelist = databaseManager.convertToDataSet(
    new Array({ d: 'Item 1', r: 1}, { d: 'Item 2', r: 2},
              { d: 'Item 3', r: 3}, { d: 'Item 4', r: 4},
              { d: 'Item 5', r: 5}, { d: 'Item 6', r: 6}), ["d", "r"]);

NOTE: From 2022.09 on the valuelist property type at runtime did change a bit. Now it is more a complex object that has currently 2 properties:

name: to get the current name of the valuelist or to set it and then the valuelist of the given name is put in that property

dataset: this will return the dataset of the current values, or set the current values if it was a CustomValueList.

Client side, the valuelist will be an array of objects (items), each item will have two properties: "realValue" and "displayValue". If Valuelist is defined only having display values, realValue client side will be the same as display value:

svyOnChanges(changes: SimpleChanges) {
    if (changes['valuelistID']) {
        if (!this.valuelistID || this.valuelistID.length == 0) return;
        hasRealValues = false;
        for (var i = 0; i < .length; i++) {
            var item = this.valuelistID[i];
            if (item.realValue != item.displayValue) {
                hasRealValues = true;
                break;
            }
        }
    }
}

Client side, valuelist also has some API that can be used: filterList and getDisplayValue. Filter list api takes a filter parameter and applies it to valuelist server side, then filtered valuelist will be sent to client (in same property). This is used for typeahead component:

values = (text$: Observable<string>) => {
    const debouncedText$ = text$.pipe(debounceTime(200), distinctUntilChanged());
    const clicksWithClosedPopup$ = this.click$.pipe(filter(() => !this.instance.isPopupOpen()));
    const inputFocus$ = this.focus$;

    return merge( debouncedText$, inputFocus$, clicksWithClosedPopup$ ).pipe( switchMap( term => ( this.valuelistID.filterList( term ) ) ) );
};

Get display value API is used to retrieve a display value taking real value as parameter from server. This is needed in cases where valuelist has many items and we don't send all items client side for performance reasons (see max property, also settings server side).

this.valuelistID.getDisplayValue($scope.model.dataProviderID).subscribe(displayValue => {
    this.value = displayValue;
    this.cdRef.detectChanges();
});

Both functions return a promise that will be resolved when response comes from server, will receive as parameter the new filtered valuelist (beware also valuelist from model will be filtered) respectively the display value.

valuelistConfig

Can be used to configure a valuelist's behavior (where applicable). It was added in 2023.06.

Properties that can be configured from Properties View (on a property of valuelistConfig type):

visible

boolean security property, when set to false the component is protected from client data changes and function calls, data changes from the server are not sent to the client.

Property value type modifiers:

Note: defaults now also get applied to the model. This might change. Best practice is to initialize the model properties with values in the directive's link method and specify the same values as defaults in the .spec file for proper display in Servoy Developer.