Page History

...

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

...

the private configuration makes the handler only accessible through Server Side Scripting. But not by the client/browser itself. 

Api

This section defines the signatures and behaviors of functions that can be called from the solution on this component/service.

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

"functionNamesomeFunctionName": {
        "parameters": [
            { "name": "startIndex", "type": "int" },
            { "name": "endIndex", "type": "int" },
            {
                "name": "theData",
                "type": {
                    "type": "dataset",
                    "includeColumnNames": true,
                    "columnTypes": { "icon": "media" }
                }
            }
        ],
        "blockEventProcessing": true,
		"async":
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.

"async" is another optional parameter (default is false), which means the client side api is not called right away, but at next message sent to the client. By default all apis are sync, so they call the client and wait for the response. Async methods cannot return a value.The implementation of such api functions can be located either in the browser-side component/service logic implementation ("definition" in .spec file) or in the server-side component/service logic implementation ("serverscript" in .spec file)

There are several types of api calls described below.

Sync functions

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.

Sync functions that do not block event processing

A special kind of sync api function type is sync functions that do not block event processing. This is not needed - in almost all cases.

It can be defined by adding a "blockEventProcessing" : false (that defaults to true) to the function definition. When it is set to false, Servoy will expect that this API function call will be long-running (so it will not time out if it takes long to execute) 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 function call like "askUserForSomeValue(someForm, ...)" 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. Example:

        "askUserForSomeValue": 
        {
            "blockEventProcessing": false,
            "returns": "string",
            "parameters": [ { "name": "formToShow", "type": "form" }, { "name": "dialogTitle", "type": "string", "optional": "true" } ]
        }

Async

Async api calls will allow the calling code to continue executing and will execute the api call later/decoupled.

Async api functions cannot return a value.

There are 3 types of async calls.

Simple async functions

Simple async calls - when called from solution (server) code - will get executed in browser later, when current request to server is done.

Just add "async": true (another optional parameter (that by default is false)) to the call definition; it means the client side api is not called right away, but at next message sent to the client.

        "executeSomethingLater": 
        {
            "async": true
        }

Async-now functions

These are async functions that will be called in browser right away (rather then when the current request to server is done), but the code that calls then does not wait for them to finish execution before proceeding.

They are useful when for example you want to send progress information to the component shown in the browser while executing a long-running-operation server-side.

Just add "async-now": true (another optional parameter (that by default is false)) to the call definition.

        "sendProgress": 
        {
            "async-now": true,
            "parameters": [ { "name": "percent", "type": "int" } ]
        }

Delay until form loads functions

Anchor
delayUntilFormLoads delayUntilFormLoads

These are special types of async calls meant only for components, not services. These functions, when called, will execute later (similar to simple async, when a request to server is done executing) but only if the form is loaded inside the browser.

If the form is not loaded inside the browser they will wait for the form to get loaded (shown by solution somewhere) before being executed.

You can use these to avoid accidental calls from the solution to execute the api function without the solution intending to show the form. The difference compared to simple async functions is that simple async functions will load the form - if not loaded in browser - in a hidden div just in order to execute the api call... this can be time-consuming and is usually not needed (a form that is not shown just being loaded and discarded in order to call an async function).

Server Side Scripting

A component or service can have a server-side part , so as well (optional); this logic is executed directly on the server, ; in the spec file this is configured like:

...