Low-code designer > Set up interfaces / Scripts in widgets

Scripts in widgets

You can make widgets on pages interactive by using scripts.

A script is a piece of code that describes a widget’s behavior under certain conditions. Scripts use variables, the most common type being Yes/No switch, as most widget actions (hide, show, etc.) are bound to the values of such properties.

Scripts can be:

  • Client-side. Executed in a user’s browser.
  • Server-side. Executed on the ELMA365 server.
  • Mixed. These scripts are executed on the client side, but they call server methods.

Server scripts run regardless of access settings configured for app items, while in client scripts access is limited based on the user’s permissions. Lets say there is an app where access to items is granted only to particular users. When an item of this app needs to be loaded for a user who doesn’t have the necessary permissions, a client-side script will return an error, but a server-side script will be executed successfully. It works the same way when getting a list of app items. A client-side script will only return items that the current user has access to. A server script will return all items.

Scripts for widgets usually don’t require powerful hardware to operate, so we recommend writing them on the client side whenever possible.

Scripts are written in the TypeScript programming language on the Scripts tab of the interface designer.

S1

In client-side scripts in widgets, you can use JavaScript libraries and custom functions. To do that, go to the Files tab of the interface designer. Upload one or several .js files with the code of the required functions or libraries. On the Scripts tab, use the import declaration to connect the files you added to the source code.

For example, to connect the jQuery library, go to the Files tab and upload a file with the most recent version of the library, for example, jquery-3.6.0.min.js. Then open the Scripts tab, to the client-side script, and add the following declaration in the beginning of the script:

import $ from "jquery-3.6.0.min.js";

Now you can call functions from this library in the scripts code.

Also, client-side scripts allow using functions that are called automatically when displaying a widget or when saving a form. Read more about it in System functions in widgets.

Get data from widgets

The way you can get data from a widget’s context depends on where a widget is located.

Interface widgets

If you are setting up an interface and creating a custom widget, you can access its context using the Context constant. For example:

Context.data.string_1 = 'string value';

If you need to access a system widget placed on a page, you also need to use Context.

Widgets on forms

If you need to access a widget placed on an app form, you need to use the ViewContext constant, as Context in this case grants access to the context of the app itself:

const itemName = Context.data.__name;
ViewContext.data.string_1 = `Name ${ itemName }}`;

Read more about this in ELMA365 TS SDK, in the Scripts in widgets article.

Call a server method from a client-side script

Not all operations can be performed strictly on the server side or on the client side. Sometimes a hybrid approach is necessary. In this case you can implement a client-side script to do part of the work and then call a server script. This approach is mostly used to implement the logic for locking interfaces and sending user notifications.

For example, you can have a server function that processes data. It can call external services:

async function DoSomeWork() : Promise<void> {
  // A typical logic of a server-side script
  // External calls can be made via `await`
  let response = await fetch('https://my-service.mycompany.com/getmydata?token=' + Context.data.secureToken);
  Context.data.mySecureData = await response.text();
}

Then, in the code of a client-side script, you can call this method by using the Server.rpc property:

async function onButtonClick() : Promise<void> {
  ViewContext.data.blockUI = true;
  await Server.rpc.DoSomeWork();
  ViewContext.data.blockUI = false;
}

Please note that data between the server and the client is passed only via Context or ViewContext. The method on the server side must not have parameters and has to return Promise. Only then it will appear in the auto-complete list for the client-side script.

You can also call server methods using nested widgets like Button or Code. Read more about it in the Scripts in widgets article in ELMA365 TS SDK.

Found a typo? Highlight the text, press ctrl + enter and notify us