Client Utils

(clientutils)

Overview

The client utilities object. Available as "clientutils." in scripting. This provides some utility functions purely for interaction with the client, like generating urls or using client side functions.

Returned Types

JSBlobLoaderBuilder,

Methods Summarized

Type	Name	Summary
JSBlobLoaderBuilder	createUrlBlobloaderBuilder(dataprovider)	Creates a blob loader url that can be sent to the browser so that it can download the value of the given dataprovider.
Object	generateBrowserFunction(functionString)	This generates a browser function for the given function string that can be executed in the browser by a component that needs a function for a certain property value.
JSBounds	getBounds(webComponent)	Retrieves the screen location and size of a specific element.
JSBounds	getBounds(webComponent, subselector)	Retrieves the screen location and size of a specific child element.
String	getMediaURL(mediaName)	Get the media url that can be used to server a media in NGClient.
void	requestFullscreen()	This method is making the HTML document to be displayed in full screen mode.

Methods Detailed

createUrlBlobloaderBuilder(dataprovider)

Creates a blob loader url that can be sent to the browser so that it can download the value of the given dataprovider. The dataprovider is mandatory, but also a datasource or server/tablename combination should be given if it points to a database column.

The .build() method of the returned builder will return the url that can be sent to the browser inside a piece of html.

The blob loader URL can be used in HTMl Areas for example in order to display images stored in the database, or to provide a clickable download link for that content as a file. In the other situations, the mimetype indicates to the browser what the type of file is and the browser might use that information in order to open the file in the appropriate application directly. The filename is suggested/given to the user when saving/downloading the file.

Parameters

• String dataprovider the dataprovider who's value should be sent to the browser (it can be a global scope variable or a datasource column)

Returns: JSBlobLoaderBuilder

Sample

// server/table column
var tableName = 'pdf_documents';
var columnName = 'invoice_doc';
var mimeType = 'application/pdf';
var bloburl1 = clientutils.createUrlBlobloaderBuilder(columnName)
                    .serverAndTable("example_data", tableName).rowid(doc_id)
                    .filename(file_name).mimetype(mimeType).build();

// datasource based column
var bloburl2 = clientutils.createUrlBlobloaderBuilder("invoice_doc")
                    .datasource("db:/example_data/pdf_documents").rowid(doc_id)
                    .build();

// global var
var bloburl2 = clientutils.createUrlBlobloaderBuilder("scopes.sc1.profilePhoto")
                    .filename("profilePhoto.png").mimetype("application/png")
                    .build();

generateBrowserFunction(functionString)

This generates a browser function for the given function string that can be executed in the browser by a component that needs a function for a certain property value. The resulting object should be assigned into a config/property object (where the property it typed as 'object'/'json'/'map' in the .spec) that is then assigned to a component. The component will receive this function as a real function object in TiNG (but still as a plain string that needs to be evalled in NG1).

This is needed because in TiNG it is not allowed - due to the Content Security Policy (CSP) that is enforced - to eval(string) in order to get a function object (that then can be executed later on).

This is a more dynamic variant of the .spec property type "clientfunction": https://docs.servoy.com/reference/servoy-developer/property_types#clientfunction

You do not need to use this for properties/arguments/return values that are declared to have "clientfunction" type in the .spec file, but rather for when you want to give it inside plain 'object' typed values. Starting with 2023.09, 'map' and 'json' property types (even nested if configured in the spec correctly) are supported.

Parameters

• String functionString The javascript function (given as a string - DON'T USE a javascript function with toString or a String constructor) that should be running in the client's browser.

Returns: Object An object that can be assigned to a property of an component or custom type. (but which is then nested/part of an object type)

Sample

var options = { myfunction: clientutils.generateBrowserFunction("function(param) { return param + 1 }") };
elements.component.options = options;

getBounds(webComponent)

Retrieves the screen location and size of a specific element. Returns the bounds (object with x, y, width and height properties).

Parameters

• Component webComponent the component

Returns: JSBounds

Sample

var bounds = clientutils.getBounds(elements.myelement);

getBounds(webComponent, subselector)

Retrieves the screen location and size of a specific child element. Returns the bounds (object with x, y, width and height properties).

Parameters

• Component webComponent the parent component

• String subselector a selector to identify a child component starting with parent component

Returns: JSBounds

Sample

var bounds = clientutils.getBounds(elements.myelement,'.subclass');

getMediaURL(mediaName)

Get the media url that can be used to server a media in NGClient.

Parameters

• String mediaName Name of the media

Returns: String

Sample

clienutils.getMediaURL('solution.css');

requestFullscreen()

This method is making the HTML document to be displayed in full screen mode.

Returns: void

Sample

clientutils.requestFullscreen();

---