Specification (.spec file)

Overview

A (WYSIWYG) form designer needs component meta data to be able to handle components. This meta data is expressed in a specification.

Definition and basic structure

A simple metadata specification is expressed in json format. (called the .spec definition file)

The specification defines:

identifier information (component name, icon, display name, ...)

Name convention: the provided string is of the form package name, followed by a dash sign ('-'), followed by the component name. The package name is the name of the package the component is part of, and component name is simply the name of the component. Both package name and component name should be written in lower-case.

dependencies (any extra js & css library dependencies that the component or service need to use)
definition of component structure, to support:
- model properties
- event handlers
- callable APIs
additional/child property type info (information about custom types of data that can be used in model, api/handler parameters and return values)

In a json format: spec file definition

{
    "name": "packagename-componentname", // String
    "displayName": "more descriptive name that is shown in the designer", // String
    "version": the component version (integer)
    "icon": "A reference to the icon shown in designer" ,
    "preview": "A reference to the preview gif to be displayed" ,
 
    "definition": "A reference to the js file that implements this component's in the browser (NG1 ONLY)",
    "serverscript": "[optional] A reference to the js file that implements this component's server-side logic, if any.",
    "doc": "A reference to the js file that contains the jsdocs of the component api or model properties. (NG1 ONLY)",
    "group": true // default true, so the definition file can be grouped when creating the .war file for deployment
    "deprecated": "This component will be replaced in the next versions.", // (optional) some string to mark the component as deprecated - if it is deprecated
    "replacement": "package-compname", // (optional) in case of deprecation, developer will provide a quick fix for such components to be automatically changed to the given replacement component
                                       // (make sure they have compatible .spec defined; in most cases this is useful when moving components from a package to another package or when
                                       // rewriting a component but keeping it's contract unchanged)
    "libraries": [], // Array of js/css definitions (which are JSON objects with
                     // 'name'-the lib name, 'version'-the lib version, 'url'-the lib url,
                     // 'mimetype'-the lib mimetype, one of 'text/javascript' or 'text/css',
                     // 'group' - give false here when this lib dependency should not be grouped when exported
                     // as .war; default true) that need to be included for this component. (NG1 ONLY)
 
    "keywords": [], // Array of keywords used for searching components in the palette.
                    // For instance, for the calendar component some appropriate keywords that might be used are: "day", "month", "year"
 
    "categoryName": "Advanced", // category for form designer palette; only makes sense for components, not services

    "ng2Config": { // TiNG only describing the package how it is defined for TiNG
       "packageName": "The name of the projects package.json",
       "serviceName": "If it is a service this is the name of the Angular Service",
       "entryPoint": "The directory of the build output (/dist/xxx)",
       "moduleName": "The Module Name",
       "dependencies": {
           "csslibrary": ["A module path to a css lib that needs to be included;priority=5"]
        },
        "assets": [{
                    "glob": "Filter like: *.js",
                    "input": "The directory that should be include (most likely dir in node_modules package)",
                    "output": "The output dir where these files should be in (seem from the root of the WAR)"
              }]
    },   
    "model": {
        "property1Name": /* type description (optionally including optional default value and others) */,
        "property2Name": /* type description (optionally including optional default value and others) */
    },
 
    "handlers": {
        "handler1Name": { /* handler function type definition*/ },
        "handler2Name": { /* handler function type definition*/ }
    },
 
    "api": {
        "apiFunction1Name": { */ api function signature description json*/ },
        "apiFunction2Name": { */ api function signature description json*/ }
    },
 
    "internalApi" : {
        "internalApiFunction1Name": { */ internal api function signature description json*/ },
        "internalApiFunction2Name": { */ internal api function signature description json*/ }
    },
 
    "types": {
        "customType1Name": {
            "subProp1Name": /* type description" */,
            "subProp2Name": /* type description" */
        },
        "customType2Name": {
            "subProp1Name": /* type description" */,
            "subProp2Name": /* type description" */
       }
    }
}

An NG web component or ng service specifies all its properties in the model section of the .spec file, all the events under handlers section and the api section has the javascript callable api that the webcomponent exposes (that the server/solution can call).

Starting with 8.2 (before these were defined in "api") there is also the internalApi section that is better described in Server Side Scripting page (calls between client and server that are only meant for the code inside the component/service to use).

You can find an example .spec file below.

Grouping of library dependency options

The "group" property on the top level spec or in the libraries section tells Servoy if that the definition or library can be grouped or not; by default this is allowed. This is used when a WAR is generated by the WAR Exporter.

The "group" property The libraries which contain references to external files cannot be grouped because in the deployed applications the relative paths to those resources are lost, therefore the components will not work.

Such libraries are font-awesome.css or tinymce.js, they should always have "group": false in the specification file of the components that use them.

Deprecation support

A component/service/layout can be marked as deprecated by using the "deprecated" and/or "replacement" properties.

The deprecated components/layouts will not be shown anymore in the palette.

The deprecated services will not be shown anymore under the Solution Explorer plugins node. Markers will be added in case they are used in scripting.

The following combinations are possible:

"deprecated": "true" // a boolean as a string; this just means "deprecated" without any extra info (it is a string and not a boolean directly in case you want to provide more information about the deprecation; see below)

"deprecated": "This component will be removed in version X.", // some extra message explaining to the developer why it was deprecated or what to use instead

In the case when the "replacement" property is used (supported for component level deprecation only), the generated markers for the used deprecated components will also have a quick-fix.

"deprecated": "This component will be removed in version X.",//some extra message
"replacement": "packagename-compname"

Using only the "replacement" property will also mark the component as deprecated, and the generated marker will have a quick-fix.

"replacement": "packagename-compname"

The "deprecated" property The "deprecated" property can also be used to deprecate service/component api or properties:

e.g. service function

"removeKL": {
    "returns": "boolean",
    "deprecated": "Please use removeKeyListener(...) instead.",
    "parameters": [ { "name": "callbackKey", "type": "string" } ]
 }

e.g. component property

"model": {
    "enabled" : {"type": "boolean", "default": true, "deprecated": "true"},
    ...
}

In this case, the deprecated property will not be shown in the properties view.

Model

An NG web component or ng service specifies all its properties and the type of each property in the model section of the .spec file.

Apis or handlers are not supported under "model" or "types" because these are just meant as container objects that transmit data/information between the component/service and the server.

For giving types of each property you can use any of the default provided property types that you can find here as well as any custom types defined in the "types" section. Arrays are also allowed (append "[]" to the type name).

Property types under model can be defined in two ways:

simply by specifying it's type:

"someTextProperty": "string"

with additional configuration options if you want/need to tell Servoy more about how this property should be treated (this is just a sample, all configuration options are optional and each one will be detailed later); "type" is mandatory.

"someTextProperty": { "type": "string", "tags": { "scope": "design" },
                                        "values": [ { "Predefined Text 1": "sample text 1" }, { "Predefined Text 2": "sample text 2" } ],
                                        "default": "nothing interesting" }

Array types

To define an array property just append "[]" to the type name.

"someTextProperties": "string[]" To specify configuration options for each element of the array you can do:

"someTextProperties": { "type": "string[]", "elementConfig" : {
                                                "tags": { "scope": "design" },
                                                "values": [ { "Predefined Text 1": "sample text 1" }, { "Predefined Text 2": "sample text 2" } ],
                                                "default": "nothing interesting" }
                                            }

For more information on array types see the array property types page.

Custom types

types section defines custom internal types that can then be used by this web component/service for one or more of its properties in the model as well as for parameter and return value types defined in other sections. (for example a tabpanel component has a "tab" type that describes one tab inside the tab-panel). Custom type definitions each support for defining subproperties whatever is supported under model. For example:

"types": {
    "someCustomTypeName": {
        "name": "string",
        "containsForm": "form",
        "texts": "tagstring[]",
        "relationName": "relation",
        "active": "boolean"
    }
}

For more information on custom property types and how they work see the custom object property types page.

Configuration options

There is a set of standard configuration options and each specific property type (for more advanced types like "foundset", "dataprovider", ...) can have some extra configuration options that are detailed by each type.

Stardard tags are the ones that control data synchronization, tags and default/initial/predefined values.

Data synchronization

Data modifications are automatically propagated from server to client.

For performance (and security) reasons, data modifications from client to server are not propagated by default. To enable client-to-server data send, use the property's pushToServer config option. For example:

pushToServer example

"model": {
   "searchfield": { "type": "string", "pushToServer": "shallow" }
}

pushToServer can take the following values:

reject - this is the default; there is no data synchronization from client to server for this property; the server will throw an exception if updates are pushed from client to server on such properties (for both NG & Titanium client)
allow - the server allows data changes received from client for such a property;
- NG1 client-side: it needs a manual trigger or a directive that triggers the send of changes for that property (in NG1, it's for dataprovider properties -> svy-apply (manual servoy api call) or svy-autoapply (directive));
- Titanium client-side: it needs manual send-to-server; that means that component client side code needs to call an .emit(value) on the @Output (or, in case of services, ServoyPublicService.sendServiceChanges(...)) of the root property that is/contains the changed value (even if it intends to send only a subprop/element of the root property that only has ALLOW pushToServer). Before using .emit(...)/.sendServiceChanges(...), in the rare cases where you use an 'object' type in the .spec file for elements of custom arrays or sub-properties of typed custom objects, and the content of that value is a nested JSON, in order for the custom objects type/custom array type to 'see' the changes nested inside the JSON of the plain 'object' value (so for change by reference of the 'object' typed value it is not needed), you can use either ICustomObjectValue.markSubPropertyAsHavingDeepChanges(subPropertyName: string) or ICustomArrayValue.markElementAsHavingDeepChanges(index: number)
shallow - same as allow, but client-side it reacts to changes-by-reference as described below:
- NG1: a shallow watch will be added automatically on the value (in the client) and changes-by-reference will automatically be sent to the server; the watch is based on object reference/primitive value (it is faster then 'deep', but in case of nested plain 'object' properties (with array/object JSON content) it will only detect and send changes automatically when the values are different by reference (even if they are actually 'equal' by content))
- Titanium: client code will automatically react and send the changes to server ONLY when components/services change by reference the values inside typed custom objects/arrays/... (declared as such in the .spec file; for example inside a 'string[]' or 'myColumnObject'). But it DOES NOT work automatically for root properties that change by ref. Root property change-by-ref in Titanium currently always needs a manual trigger; see the description from 'allow' above. Changes nested inside untyped nested JSON values ('object' in .spec) need to be triggered manually as well, as they are not changes-by ref of that 'object' value. That can be done via:
  - if the deep untyped JSON that has changes is a root property, emit(value) on the component @Output (and in case of services via ServoyPublicService.sendServiceChanges())
  - if the deep untyped JSON that has changes is a subproperty of a typed custom object from .spec, ICustomObjectValue.markSubPropertyAsHavingDeepChanges(subPropertyName: string)
  - if the deep untyped JSON that has changes is an element of a custom array from .spec, ICustomArrayValue.markElementAsHavingDeepChanges(index: number)
deep - same as allow, but client-side it is meant to react at any changes of properties of type 'object' - even nested changes if it contains nested JSON - and for any change it detects (doesn't matter how little) it will send the whole value to the server:
- NG1: a deep watch on the value (in the client) will automatically be added and changes (both by reference and nested inside the 'object') will automatically be sent to the server; the watch is based on object equality (compares old and new values of nested JSON values; it is slower then 'shallow', because it keeps and compares two copies of the nested JSON)
- Titanium: as the newer angular versions do not have deep watches anymore (to detect nested changes in plain 'object' typed-in-spec JSON values), it will behave exactly as 'shallow', see description above.

Note that in Servoy, data-provider property changes are sent to server using svy-apply (servoy api call) and svy-autoapply (directive); for these to work properly, these properties should set pushToServer to allow. Otherwise those data provider properties will be read-only.

Information about how "pushToServer" works in particular with Array property type and with Custom object property type:

before Servoy version 2023.03: for nested properties through custom object or array types, the pushToServer of the root property will be enforced on all elements/sub-properties of that property.
starting with Servoy version 2023.03: pushToServer on elements/sub-properties is taken into account; if the root property is defined as "reject" then all nested elements/sub-properties will be reject just as before. Child elements/sub-properties can only restrict parent object/array's push to server level (so from anything -> reject only) or switch between allow/shallow/deep, and if the child doesn't specify a "pushToServer", it will inherit it from the parent. If no "pushToServer" is specified on any of the parents and child the default will be used: "reject".

When typed arrays and typed objects are used in the spec file. (for example a 'string[]', 'myColumnObject' or 'myColumnObject[]') - starting with 2023.03 - pushToServer defined values are combined as follows:

Typed Object/Array (so PARENT) defined pushToServer

Sub-property/Element (so CHILD) defined pushToServer

RESULTS IN CHILD being

unset

reject (default)

reject

allow

unset

allow

all others

same as CHILD

shallow

unset

shallow

all others

same as CHILD

deep

unset

deep**

deep

all others

same as CHILD

in the table above, "all others" means the rest of available combinations that are not explicitly specified in the table, "*" means any value, be it set to something or not set at all; parent "pushToServer" is of course the computed value of parent that takes into account already all the parents of parent

** "deep" is useful only for random untyped JSON object values (so "object" type) in NG1 Client (Titanium client treats it the same as 'shallow'). You normally don't use 'deep' on a typed array or custom object in the .spec file anyway. If you do that, parent is then "deep" in the table above; being smart types, they won't add deep angular watches directly on themselves even in NG1 (they do handle changes on each level but separately in these smart types), but only on their 'dumb' ('object'/primitive and some other types) child/leaf values. So, they just propagate the "deep" value to children anyway, even though it will not actually generate any "deep" angular watches along the way for smart nested structures (so it would behave similar to 'shallow' on each level of nesting except for the dumb leafs where NG1 does add a deep watch).

Example: in the following .spec, that has nested properties (via typed arrays/objects) with pushToServer defined in multiple places

(...)
"model": {
   "giftInTheMaking": { "type": "gift", "pushToServer": "shallow" },
   "giftTemplates": "gift[]",
   (...)
},
"types": {
    "gift": {
            "intenalId": { "type": "int", "pushToServer": "reject" },
            "shortDescription": "string",
            "details": "string",
            "productIds": "int[]",
            "storeConfigJSON": { "type": "object", "pushToServer": "deep" }
    }
}
(...)

the root properties and sub-properties/elements will have the following actual pushToServer:

Property

< 2023.03

>= 2023.03

giftInTheMaking

shallow

giftInTheMaking.intenalId

shallow

reject

giftInTheMaking.shortDescription

shallow

giftInTheMaking.storeConfigJSON

shallow

deep

giftTemplates

reject

giftTemplates[idx].intenalId

reject

giftTemplates[idx].shortDescription

reject

giftTemplates[idx].storeConfigJSON

reject

If a root property doesn't have a pushToServer set in .spec file it is then considered "reject" by default. That implies that all it's sup-properties/elements are 'reject' as well.

Tags

Properties can be configured with special tags that may be interpreted by the deployment and/or development environment.

Supported tags are:

scope

Restricts the model property to: 'design', 'runtime' or 'private'.

Design means property can only be assigned from designer (not from scripting). Runtime means the property cannot be assigned from designer (will be hidden in Properties View). Private is an internal property, that should only be used by component itself (so component.js or component_server.js). Will not show in Properties View and cannot be assigned from scripting.

doc: string

A string (can have some basic html tags in it) that describes what the property does to the developer. See Documenting what properties do for more details.

addToElementsScope: boolean

For component type, specify whether component should be added to elements scope. Default is false, so component can be accessed only via component property. If true, will be accessible like any other element of the form.

logWhenOverMax: boolean

For the valuelist property type. If set to false, no logging will be done when only sending "max" number of items to the browser even though the valuelist does contain more than "max" items. Default is true.

allowaccess: string or array of strings

This tag can define if an edit (sent from browser to server) of this property is allowed even if properties such as "visible" or "enabled" (of the component or parent form) are false. By default, if the visibility of a component or its parent form is false, Servoy doesn't allow the modification (coming from browser) of any other property (it blocks it and logs it on server). With this tag you can say for a property that changing it should be allowed even in these situations; for example on "size" property you could say: I allow it for "visible"; or for both: ["visible", "enable"]

directEdit: boolean

One property of a component can be tagged as directEdit for designer, this way that property can be edited directly by double clicking the component (for example text property on label/button).

useAsCaptionInDeveloper : boolean and captionPriority : integer (> 0) (starting with Servoy 8.3)

Can be used to provide a caption for Custom Object Types in developer based on the value of a subproperty. For example if you create a table component that defines in .spec custom object types (that could also be "droppable" in developer) for columns, you might want to show as caption in developer for each such 'column' the header text subproperty value or - if that is not set - the dataprovider subproperty value. The captionPriority tag will allow you to specify in which order subproperties are checked for non-empty string values for the caption. That caption text ends up visible in places such as the outline view or in form designer for each column. You would specify it like this:

(...).spec

    (...)
    "model": {
        "columns": { "type": "column[]", "droppable": true, (...) },
    (...)
     "types": {
        "column": {
            "dataprovider": { "type": "dataprovider",
                              "tags": { "useAsCaptionInDeveloper" : true,
                                        "captionPriority" : 2 }, (...) },
            "headerText": { "type": "tagstring",
                            "tags": { "useAsCaptionInDeveloper" : true,
                                      "captionPriority" : 1 }},
    (...)

showInOutlineView: boolean (for Servoy < 8.3)

In the Outline View, Custom Type objects have the name of the type as lables. The showInOutlineView:true tag can be added to any property definition in order to append the design time value of that property to the label of the custom type object in the Outline View. If you are using Servoy >= 8.3 please use "useAsCaptionInDeveloper " and "captionPriority" instead. Starting with that version "showInOutlineView" : true is equivalent to "useAsCaptionInDeveloper" : true.

main: boolean (starting with Servoy 8.4)

Used only for dataprovider types. In case there are more then one dataprovider types, setting this tag to 'true' will define the main dataprovider, that is needed on different places, like sorting. As an example, having a component with 2 dataprovider properties, and using it in a table view, that component is used for column rendering, and calling sort on that column, by clicking on the column header, will need the dataprovider from the component to do the sort - using the 'main' tag, we can define the dataprovider to use. (see onrenderlabel component from servoy-extra package)

mode: string (starting with Servoy 2019.03) - Restricts the model property to: 'combobox' or 'typeahead' in developer properties view. (Default is combobox)

This can be used only on string properties when they have "values" attribute. Setting mode to typeahead will create a typeahead property in property editor. Setting mode to combobox or skipping mode property will create a combobox in property editor.

"someTextProperties": { "type": "string",
                        "tags": { "scope": "design", "mode": "typeahead" },
                        "values": [ "off", "shipping", "billing", "phone", "address"]
                      }

wizard: boolean

This property will trigger/ not trigger the dataprovider dialog on dropping a component in the editor, is only for dataprovider types. Setting this property on false or not adding this property will not trigger the dataprovider dialog. Below you have an example of triggering the dataprovider dialog.

	(...)
	"dataprovider": { "type": "dataprovider", "tags": { "wizard": true, ... }}
	(...)

Default / Initial / Predefined values

A property can have a "default" value like:

"text": { "type": "string", "default": "I am a button" }

But this would mean that restore to default or empty the property would always set that default property back. This is wanted behavior if the property has to have some default value like if a property must be 1 of a few values and the default is one of those.

If a property should allow the developer to choose in the properties view from a predefined set of values you can use the "values" attribute in combination with "default" and optionally "mode" tag (see above) (default can be one of the predefined values but can also be something else):

"horizontalAlignment": {
    "type": "int",
    "tags": { "scope": "design" },
    "values": [