Client Utils

(clientutils)

Overview

The clientutils object provides essential utilities for client-side operations in applications, streamlining tasks like generating URLs, managing browser functions, and retrieving interface dimensions. It is designed to enhance interaction with the client environment, ensuring efficiency and flexibility in various scenarios.

One key function, createUrlBlobloaderBuilder, enables the creation of downloadable URLs for content, such as database columns or global variables, which can be presented in HTML areas. This allows for flexible handling of files with customizable filenames and MIME types.

The generateBrowserFunction method facilitates the secure execution of JavaScript functions on the client side by creating executable function strings. This is particularly useful in environments with stringent Content Security Policies (CSP).

Other functions include getBounds, which retrieves the position and size of UI components or their sub-elements, and getMediaURL, which generates URLs for serving media assets. Additionally, the requestFullscreen method enables full-screen display for the HTML document, enhancing user experiences in immersive scenarios.

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 will generate a browser function for the given function string - that can be executed in the browser by a component/service that needs a client side executable function for one of it's properties / method arguments.
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 will generate a browser function for the given function string - that can be executed in the browser by a component/service that needs a client side executable function for one of it's properties / method arguments.

The resulting object should be assigned to / given as a (config) property / method argument (that is typed as 'object'/'json'/'map' in the .spec). The component will receive this function as a real function object in TiNG (but it will still be a plain string that needs to be evalled in NG1).

This method is needed because in TiNG it is not allowed to eval(string) - due to the Content Security Policy (CSP) that is enforced - 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".

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, even 'map' and 'json' property types (values nested inside those - if configured in the component/service .spec file correctly) support client functions given as simple strings, without the need to call this method.

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/service or to a method argument - if that is typed as, or is part of something typed as 'object'.

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();

---