# ServoyApi (serverside)

(servoyApi)

## Overview

The `ServoyApiObject` provides server-side utility methods to facilitate interactions within the Servoy environment, primarily for NG and Titanium client components or services. These utilities are integral to the internal implementation of web objects, enabling seamless data management and dynamic UI interactions.

The API supports functionalities such as creating foundsets and view foundsets using `QBSelect` for flexible data retrieval and filtering. It allows direct manipulation of forms on the server, including methods to show or hide forms dynamically, ensuring efficient updates without additional client-side round trips. Session-specific filters can be applied to foundsets, offering dynamic, user-specific data restrictions.

Additional capabilities include performing SQL queries with query builders, generating media URLs from server-side byte arrays, and creating custom `JSEvent` instances for event-driven workflows. Developers can also use utility functions like deep copying of complex objects and creating empty datasets, enhancing data and object management within the platform.

## Methods Summarized

| Type                                                                                           | Name                                                                                                                           | Summary                                                                                                                                                                         |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean)                 | [addFoundSetFilterParam(foundset, query, filterName)](#addfoundsetfilterparam-foundset-query-filtername)                       | Add a filter parameter that is permanent per user session to limit a specified foundset of records.                                                                             |
| [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object)                   | [copyObject(value)](#copyobject-value)                                                                                         | Can be used to deep copy a custom value.                                                                                                                                        |
| [JSDataSet](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsdataset)   | [createEmptyDataSet()](#createemptydataset)                                                                                    | Creates an empty JSDataSet                                                                                                                                                      |
| [JSEvent](https://docs.servoy.com/reference/servoycore/dev-api/application/jsevent)            | [createJSEvent()](#createjsevent)                                                                                              | This will create a JSEvent filled with component information.                                                                                                                   |
| [JSEvent](https://docs.servoy.com/reference/servoycore/dev-api/application/jsevent)            | [createJSEvent(eventType)](#createjsevent-eventtype)                                                                           | This will create a JSEvent filled with component information and set the type of the event (for example onClick).                                                               |
| [JSDataSet](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsdataset)   | [getDataSetByQuery(query, max\_returned\_rows)](#getdatasetbyquery-query-max_returned_rows)                                    | Performs a sql query with a query builder object.                                                                                                                               |
| [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array)                     | [getDatasourcePKs(datasource)](#getdatasourcepks-datasource)                                                                   | This will generate a list of primary keys names for the given data source.                                                                                                      |
| [JSFoundSet](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsfoundset) | [getFoundSet(query)](#getfoundset-query)                                                                                       | Creates a foundset.                                                                                                                                                             |
| [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string)                   | [getMediaUrl(bytes)](#getmediaurl-bytes)                                                                                       | This will generate a url from a byte array so that the client can get the bytes from that url.                                                                                  |
| [QBSelect](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/qbselect)     | [getQuerySelect(dataSource)](#getqueryselect-datasource)                                                                       | Get select query for dataSource                                                                                                                                                 |
| [JSFoundSet](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsfoundset) | [getViewFoundSet(name, query)](#getviewfoundset-name-query)                                                                    | Creates a view (read-only) foundset.                                                                                                                                            |
| [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean)                 | [hideForm(formName)](#hideform-formname)                                                                                       | Hide a form directly on the server for instance when a tab will change on the client, so it won't need to do a round trip for hiding the form through the browser's component.  |
| void                                                                                           | [resume()](#resume)                                                                                                            | This needs to be called when #suspend() is called to resume the servoy scripting call that was suspended.                                                                       |
| [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean)                 | [showForm(formNameOrInstance)](#showform-formnameorinstance)                                                                   | Show a form directly on the server for instance when a tab will change on the client, so it won't need to do a round trip for showing the form through the browser's component. |
| [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean)                 | [showForm(formNameOrInstance, relationName)](#showform-formnameorinstance-relationname)                                        | Show a form directly on the server for instance when a tab will change on the client, so it won't need to do a round trip for showing the form through the browser's component. |
| void                                                                                           | [showFormDelayed(model, formNameProperty, relationNameProperty)](#showformdelayed-model-formnameproperty-relationnameproperty) | Calls showForm delayed with latest form name and relation name from the model.                                                                                                  |
| void                                                                                           | [suspend()](#suspend)                                                                                                          | This can be called by server side code of components or services to suspend the api call that is done from Servoy Scripting.                                                    |

## Methods Detailed

### addFoundSetFilterParam(foundset, query, filterName)

Add a filter parameter that is permanent per user session to limit a specified foundset of records.\
This is similar as calling foundset.js\_addFoundSetFilterParam, but the main difference is that this\
works also on related foundsets.

**Parameters**

* [JSFoundSet](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsfoundset) **foundset** The foundset to add the filter param/query to
* [QBSelect](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/qbselect) **query** The query repesenting the filter
* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **filterName** a name given to this foundset filter

**Returns:** [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) true if the filter parameter was successfully added, false otherwise.

### copyObject(value)

Can be used to deep copy a custom value.

**Parameters**

* [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) **value** the value to be copied

**Returns:** [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) a copy of the value object, the same as constructing the object in javascript from scratch

**Sample**

```js
var eventSourceCopy = servoyApi.copyObject(eventSource);
```

### createEmptyDataSet()

Creates an empty JSDataSet

**Returns:** [JSDataSet](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsdataset) an empty JSDataSet

### createJSEvent()

This will create a JSEvent filled with component information.

**Returns:** [JSEvent](https://docs.servoy.com/reference/servoycore/dev-api/application/jsevent) the jsevent

**Sample**

```js
var event = servoyApi.createJSEvent();
```

### createJSEvent(eventType)

This will create a JSEvent filled with component information and set the type of the event (for example onClick).

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **eventType** type of the event

**Returns:** [JSEvent](https://docs.servoy.com/reference/servoycore/dev-api/application/jsevent) the jsevent

**Sample**

```js
var event = servoyApi.createJSEvent('onClick');
```

### getDataSetByQuery(query, max\_returned\_rows)

Performs a sql query with a query builder object.\
Will throw an exception if anything did go wrong when executing the query.\
Will use any data filter defined on table.

**Parameters**

* [QBSelect](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/qbselect) **query** QBSelect query.
* [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) **max\_returned\_rows** The maximum number of rows returned by the query.

**Returns:** [JSDataSet](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsdataset) The JSDataSet containing the results of the query.

**Sample**

```js
var dataset = servoyApi.getDataSetByQuery(qbselect, 10);
```

### getDatasourcePKs(datasource)

This will generate a list of primary keys names for the given data source.

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **datasource** the data source

**Returns:** [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) a list of primary key names

**Sample**

```js
var pkNames = servoyApi.getDatasourcePKs(datasource);
```

### getFoundSet(query)

Creates a foundset.

**Parameters**

* [QBSelect](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/qbselect) **query** query builder used to get the data for the foundset

**Returns:** [JSFoundSet](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsfoundset) The foundset created based on the specified query.

### getMediaUrl(bytes)

This will generate a url from a byte array so that the client can get the bytes from that url.

**Parameters**

* [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) **bytes** The value where an url should be created for

**Returns:** [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) the url where the bytes can be downloaded from

**Sample**

```js
var url = servoyApi.getMediaUrl(bytes);
```

### getQuerySelect(dataSource)

Get select query for dataSource

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **dataSource** the dataSource

**Returns:** [QBSelect](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/qbselect) QB select for the dataSource

### getViewFoundSet(name, query)

Creates a view (read-only) foundset.

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **name** foundset name
* [QBSelect](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/qbselect) **query** query builder used to get the data for the foundset

**Returns:** [JSFoundSet](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsfoundset) The view foundset created based on the specified query.

### hideForm(formName)

Hide a form directly on the server for instance when a tab will change on the client, so it won't need to do a round trip for hiding the form through the browser's component.

**Parameters**

* [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) **formName** the form to hide

**Returns:** [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) true if the form was hidden

**Sample**

```js
servoyApi.hideForm(formToHideName)
```

### resume()

This needs to be called when #suspend() is called to resume the servoy scripting call that was suspended.

So this can be called in an serverside call from the client that couldn't really be done directly in a sync call to the client.

**Returns:** void

### showForm(formNameOrInstance)

Show a form directly on the server for instance when a tab will change on the client, so it won't need to do a round trip\
for showing the form through the browser's component.

NOTE: Make sure this isn't called with a form name that can direclty come from the client, because this call allows all forms to be shown!

**Parameters**

* [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) **formNameOrInstance** the form to show

**Returns:** [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) true if the form was marked as visible

**Sample**

```js
servoyApi.showForm(formToShowName)
```

### showForm(formNameOrInstance, relationName)

Show a form directly on the server for instance when a tab will change on the client, so it won't need to do a round trip\
for showing the form through the browser's component.

NOTE: Make sure this isn't called with a form name that can direclty come from the client, because this call allows all forms to be shown!

**Parameters**

* [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) **formNameOrInstance** the form to show
* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **relationName** the parent container

**Returns:** [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) true will always return true, this is always a bit later

**Sample**

```js
servoyApi.showForm(formToShowName)
```

### showFormDelayed(model, formNameProperty, relationNameProperty)

Calls showForm delayed with latest form name and relation name from the model.

**Parameters**

* [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) **model** the component model
* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **formNameProperty** the name of the property that contains the form name in model
* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **relationNameProperty** the name of the property that contains the relation name in model

**Returns:** void

**Sample**

```js
servoyApi.showFormDelayed(model, 'containedForm', 'relationName')
```

### suspend()

```
This can be called by server side code of components or services to suspend the api call that is done from Servoy Scripting.
So the server side code will block the servoy scripting call but it self does call a async client side function where it waits for some results
This is handy if the result come in through another call which can't directly be handled  through the websocket message, like a large file upload.

It is very important that when this call is done there is always a #resume() call done! Else the event thread will not resume the call that triggered this.
```

**Returns:** void

***