Page History
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
{
"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",
"serverscript": "[optional] A reference to the js file that implements this component's server-side logic, if any.",
"doc": "[optional] A reference to the js file that contains the jsdocs of the component api or model properties.",
"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. */,
"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
"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" */
}
}
} |
...
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
...
doc: 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
...
More information about how these properties work with containers can be found here.
Protecting properties
| Anchor | ||||
|---|---|---|---|---|
|
...
You might also want to read about how protecting works with containers below.
Visibility properties
| Anchor | ||||
|---|---|---|---|---|
|
...
You might also want to read about how visibility works with containers below.
Container security
| Anchor | ||||
|---|---|---|---|---|
|
...
Documentation for properties can be added to each property's definition via the "tags" section using key "doc" or in the doc file using a variable with same name as the property.
| Code Block | ||
|---|---|---|
| ||
/** * some desciption * @example elements.%%elementName%%.yourName = 'myname' */ var yourName; |
The description that you provide in the .spec file will be used in Servoy Developer as:
...
For information about documenting handlers see Documenting handlers and handler templates below. For information about documenting API functions see the documenting api functions example.
...
The "private" configuration makes the handler only accessible from Server Side Scripting, not from the client/browser itself.
The "ignoreNGBlockDuplicateEvents" configuration makes the handler ignore the system NG_BLOCK_DUPLICATE_EVENTS property.
A handler can have a JSEvent property type which is able to map a Dom event to a JSEvent object that the handler can have in Servoy scripting. A mapping is mostly made automatically by calling using in the template:
...
For information about documenting properties see Documenting what properties do above,. For information about documenting API functions see the documenting api functions example.
...
| Note | ||
|---|---|---|
| ||
When a component (not service) sync or simple async api function (see below) that the solution can call is implemented in browser-side component/service logic implementation ("definition" in .spec file), it is important to note that calling such a function when the form of that component is not already created in browser DOM will result in a temporary "force-load" of that form in a hidden div in the browser - just to be able to call that api function. As this is usually not useful and will slow-down the solution due to the hidden loading of a form, this situation should be avoided (either by the solution - calling the api call later after the form was shown - or, where possible, by using delay until form loads async api functions in components - see below). Servoy will log warning messages each time a sync API call to browser executes when the browser doesn't have the needed form present in DOM yet (triggering a force-load of the form in a hidden div). Most of the times this happens when solutions call component sync api functions to browser inside the onShow handler of a form. |
...
This is the default type of api function; the example above is a sync api function definition. Sync functions will call the client and wait for the api function to execute/return before continuing. Sync api functions can have a return value.In case of
component sync functions, if the Client side code of the sync api function can return either directly the intended return value or a Promise that in the end resolves with the intended return value. Server will wait for any client returned Promise to resolve before resuming server-side code execution.
In case of component sync functions, if the form is not present in browser's DOM then sync calls will force-load it in a hidden div just in order to execute the sync function on the component.
...
They are useful when for example you want to send progress information to the service client-side while executing a long-running-operation server-side.
Async-now function calls will not send other pending async calls to client nor update the client's state with other pending changes (model updates of components/services/etc.).
Just add "async-now": true (another optional parameter (that by default is false)) to the call definition.
...
Allow server side calls when component or parent form is not visible
By default, serve server side call calls coming from client are ignored if the component or the parent form is not visible (anymore), such as, calling . For example, a call to a server side function when switching to a new form, to do some cleanup, might get blocked. To still allow these calls,
you should add "allowaccess" : "visible" to the function definition in the .spec file.
Server Side Scripting
...
See Server Side Scripting for more info about server side scripting.
Doc file
(From 2021.12 on)
A component or service can have a doc file for specifying documentation of the api and model properties. This is the same as the JSDoc in client side (.js) file, but is needed because NG2 doesn't have a js file that we can use in this way, requiring doc to be specified in another place.
The api doc/property doc can also be specified in the spec file itself using the doc property , however this is suitable only for small descriptions.
| Code Block | ||||
|---|---|---|---|---|
| ||||
"doc": "servoydefault/tabpanel/tabpanel_doc.js", |
| Code Block | ||||
|---|---|---|---|---|
| ||||
/**
* some sample text
* @example elements.%%elementName%%.yourName = 'myname'
*/
var yourName;
/**
* This is a sample function from doc javascript file.
*/
function somemethod() {
} |
Palette categories
Web Components are organized in component packages. The palette of the WYSIWYG editor shows components grouped by package name. To further group components from the same package, the property 'categoryName' can be used. 'categoryName' is a property that each component can specify in its spec file. The palette then displays components belonging to the same category grouped under the specified 'categoryName'.
...
Overview
Content Tools
Activity