Child pages
  • Specification (.spec file)
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 43 Next »

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

Definition

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

The specification defines:

  • identifier info (component name)

    Name convention: the provided string is of the form packagename, followed by a dash sign, followed by the componentname. The packagename is the name of the package the component is part of, and component name is simply the name of the component. Both packagename and componentname should be written in lowercase.

  • dependencies
  • definition of component logic, to support:
    • model properties
    • event handler
    • callable API
  • additional/child type info

In a json format:

spec file definition
{
	"name": "String packagename-componentname",
	"displayName": "String more descriptive name that is shown in the designer",
	"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 of this component",
	"libraries": Array of js/css definitions (map with 'name'-the lib name, 'version'-the lib version, 'url'-the lib url, 'mimetype'-the lib mimetype, one of 'text/javascript' or 'text/css') that needs to be included for this component,
	"model": {
	  "propertyName": type description, optional default value
	},
	"handlers": {
	  "functionName": "function type"
	},
	"api": {
	  "functionName": signature description json
	},
	"types": {
	  "typename": {
	    "propertyName": "type description"
 	  }
	}
}

A WebComponent specifies all its properties under the model, all the events under handlers and api has the javascript api the webcomponent has that the server can call.

Types are defining internal types that are used by this webcomponent for one or more of its properties.  (for example a tabpanel component has a tab type that describes one tab inside the tabpanel). They have the same support as under model:{}, there is no support for api or handlers on those types again because they are just container objects that push data to the webcomponent from the server.

Besides custom type descriptions any of the default provided property types can be used.

 

The function description in the handlers section can be just "function" or a more complex type describing the arguments and return type

"functionName" : {
        "returns" : "string",
        "parameters" : [
            { "name" : "start", "type" : "int" },
            { "name" : "end", "type" : "int" } 
        ]
}

The signature description json for functions in the api section describes the arguments, type of call and return type:

"functionName" : {
        "returns" : "string",
        "parameters" : [
            { "name" : "start", "type" : "int" },
            { "name" : "end", "type" : "int" } 
        ],
        "blockEventProcessing": true
}

"blockEventProcessing" is optional and not needed in almost all cases. It defaults to true. When it is set to false, Servoy will expect that this API call will be long-running (so it will not time out) and at the same time it will allow other events to be handled by the event dispatcher while waiting for the return value. This is helpful for example if a component would have an API call like "askForSomeValue(customForm)" which shows a modal dialog containing a form and returns a value. That API call has to wait for the return value an indefinite amount of time without blocking other events from being dispatched.

Tags

Properties can be configured with special tags that may be interpreted by the deployment environment.

Servoy defines a property called 'accessible' to configure boolean properties that will always supressed when a component is marked as inaccessible.

Tags example
"model": {
   "enabled" : { "type": "protected", "blockingOn": false, "default": true,
                 "tags": { "accessible":"accessible" }
   }
} 

Security

Components can be protected using two special security types: visible and protected.

For example. when a component is made readonly from the server the component will make the its UI non-editable. However, a malicious client could still send json messages to the server and update data.

Similarly, when a form or component is marked invisible, its data should not be sent to the client since it may contain sensitive data.

Protecting properties

Protecting properties (of type protected)are used to protect an entire component or specific properties or handlers.

When the property is blocking no changes or function calls from the client are accepted.

For example, the enabled property as defined below will be true by default, when set to false changes from the client to the component will be rejected. Also functions cannot be called from the client.

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

 

Protection can be done for specific properties or functions.

In this example, when protectCustomer is set to true, customerAddress can still be changed the the client, but customerName and removecustomer are protected.

Example protecting properties and handlers
"model:" {
    "customerAddress": "string", 
    "customerName": "string", 
    "protectCustomer": { "type": "protected", "for": ["removecustomer", "customerName"] }
   },
"handlers:" {
   "removecustomer": "function"
}

 

Protecting properties themselves can never be modified from the client.

Visibility properties

Visibility properties (of type visible) are similar to protecting properties. They are protecting the component and also hide the data from the client if the component is not visible.

In this example, a component's model can be filled with a customer name, but when the property visible is set to false, the component will be protected and the data will not be sent to the client. When visible is set to true, data not sent before will be pushed to the client.

Example visible
"model": {
   "visible" : "visible",
   "customerName": "string"
} 

 

Visibility properties themselves can never be modified from the client.

Container security

Protecting and visibility properties on containers will protect the container and also components inside the comtainer.

Example

As an example we could have a Tab Panel that has a definition like: (note: this example does not contain the entire Tab Panel spec)

tabpanel.spec
{
    "name": "servoydefault-tabpanel",
    "displayName": "Tab Panel",
    "version": 1,
    "icon": "servoydefault/tabpanel/tabs.gif",
    "definition": "servoydefault/tabpanel/tabpanel.js",
    "serverscript": "servoydefault/tabpanel/tabpanel_server.js",
    "libraries": [{"name":"accordionpanel", "version":"1", "url":"servoydefault/tabpanel/accordionpanel.css", "mimetype":"text/css"}],
    "model":
    {
            "background" : "color", 
            "borderType" : {"type":"border","stringformat":true}, 
            "enabled" : { "type": "protected", "blockingOn": false, "default": true }, 
            "fontType" : {"type":"font","stringformat":true}, 
            "foreground" : "color", 
            "horizontalAlignment" : {"type" :"int", "tags": { "scope" :"design" }, "values" :[{"LEFT":2}, {"CENTER":0},{"RIGHT":4}],"default" : -1}, 
            "location" : "point", 
            "readOnly" : "protected", 
            "selectedTabColor" : "color", 
            "size" : {"type" :"dimension",  "default" : {"width":300, "height":300}}, 
            "styleClass" : { "type" :"styleclass", "tags": { "scope" :"design" }, "values" :[]}, 
            "tabIndex" : "int", 
            "tabOrientation" : {"type" :"int", "tags": { "scope" :"design" }, "values" :[{"default" :0}, {"TOP":1}, {"HIDE":-1}]}, 
            "tabSeq" : {"type" :"tabseq", "tags": { "scope" :"design" }}, 
            "tabs" : {"type":"tab[]", "droppable":true}, 
            "transparent" : "boolean", 
            "visible" : "visible" 
    },
    "handlers":
    {
            "onChangeMethodID" : "function", 
            "onTabChangeMethodID" : "function" 
    },
    "api":
    {
            "addTab": {
                "returns": "boolean",
                "parameters":[
                                {                                                                 
                                 "name":"form/formname",
                                "type":"object []"
                                },
                                 {                                                                 
                                 "name":"name",
                                "type":"object",
                                "optional":true
                                },
                                 {                                                                 
                                 "name":"tabText",
                                "type":"object",
                                "optional":true
                                },
                                 {                                                                 
                                 "name":"tooltip",
                                "type":"object",
                                "optional":true
                                },
                                 {                                                                 
                                 "name":"iconURL",
                                "type":"object",
                                "optional":true
                                },
                                 {                                                                 
                                 "name":"fg",
                                "type":"object",
                                "optional":true
                                },
                                 {                                                                 
                                 "name":"bg",
                                "type":"object",
                                "optional":true
                                },
                                 {                                                                 
                                 "name":"relatedfoundset/relationname",
                                "type":"object",
                                "optional":true
                                },
                                 {                                                                 
                                 "name":"index",
                                "type":"object",
                                "optional":true
                                }             
                             ]
            },
            "getMaxTabIndex": {
                "returns": "int"
            },
            "getMnemonicAt": {
                "returns": "string",
                "parameters":[
                                {                                                                 
                                 "name":"i",
                                "type":"int"
                                }             
                             ]
            },
            "getSelectedTabFormName": {
                "returns": "string"
            },
            "getTabBGColorAt": {
                "returns": "string",
                "parameters":[
                                {                                                                 
                                 "name":"unnamed_0",
                                "type":"int"
                                }             
                             ]
            },
            "getTabFGColorAt": {
                "returns": "string",
                "parameters":[
                                {                                                                 
                                 "name":"i",
                                "type":"int"
                                }             
                             ]
            },
            "getTabFormNameAt": {
                "returns": "string",
                "parameters":[
                                {                                                                 
                                 "name":"i",
                                "type":"int"
                                }             
                             ]
            },
            "getTabNameAt": {
                "returns": "string",
                "parameters":[
                                {                                                                 
                                 "name":"i",
                                "type":"int"
                                }             
                             ]
            },
            "getTabRelationNameAt": {
                "returns": "string",
                "parameters":[
                                {                                                                 
                                 "name":"i",
                                "type":"int"
                                }             
                             ]
            },
            "getTabTextAt": {
                "returns": "string",
                "parameters":[
                                {                                                                 
                                 "name":"i",
                                "type":"int"
                                }             
                             ]
            },
            "isTabEnabled": {
                "returns": "boolean",
                "parameters":[
                                {                                                                 
                                 "name":"unnamed_0",
                                "type":"int"
                                }             
                             ]
            },
            "isTabEnabledAt": {
                "returns": "boolean",
                "parameters":[
                                {                                                                 
                                 "name":"i",
                                "type":"int"
                                }             
                             ]
            },
            "removeAllTabs": {
                "returns": "boolean"
            },
            "removeTabAt": {
                "returns": "boolean",
                "parameters":[
                                {                                                                 
                                 "name":"index",
                                "type":"int"
                                }             
                             ]
            },
            "setMnemonicAt": {
                "parameters":[
                                {                                                                 
                                 "name":"index",
                                "type":"int"
                                },
                                 {                                                                 
                                 "name":"text",
                                "type":"string"
                                }             
                             ]
            },
            "setTabBGColorAt": {
                "parameters":[
                                {                                                                 
                                 "name":"unnamed_0",
                                "type":"int"
                                },
                                 {                                                                 
                                 "name":"unnamed_1",
                                "type":"string"
                                }             
                             ]
            },
            "setTabEnabled": {
                "parameters":[
                                {                                                                 
                                 "name":"unnamed_0",
                                "type":"int"
                                },
                                 {                                                                 
                                 "name":"unnamed_1",
                                "type":"boolean"
                                }             
                             ]
            },
            "setTabEnabledAt": {
                "parameters":[
                                {                                                                 
                                 "name":"i",
                                "type":"int"
                                },
                                 {                                                                 
                                 "name":"b",
                                "type":"boolean"
                                }             
                             ]
            },
            "setTabFGColorAt": {
                "parameters":[
                                {                                                                 
                                 "name":"i",
                                "type":"int"
                                },
                                 {                                                                 
                                 "name":"s",
                                "type":"string"
                                }             
                             ]
            },
            "setTabTextAt": {
                "parameters":[
                                {                                                                 
                                 "name":"index",
                                "type":"int"
                                },
                                 {                                                                 
                                 "name":"text",
                                "type":"string"
                                }             
                             ]
            }
    },
"types": {
  "tab": {
          "name": "string",
          "containsFormId": "form",
          "text": "tagstring",
          "relationName": "relation",
          "active": "boolean",
          "foreground": "color",
          "disabled": "boolean",
          "imageMediaID": "media",
          "mnemonic": "string"
      }
}
     
}

 

 

  • No labels