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

Scripts in widgets

You can make page widgets more interactive by using scripts.

A script is a code that describes widget behavior under certain conditions. In most cases, the code uses the Yes/No switch variables because most widget actions (hide, show, etc.) are bound to their values.

You can write Client-side scripts or Server-side scripts. Client-side means that the action takes place in the user’s browser. Server-side means that the action takes place on the ELMA365 server.

Server scripts run regardless of access to app items. Whereas in client scripts the access is limited according to user permissions. Let's say there is an app where the access to items is granted only to particular users. When a client-side script tries to load an item of this app in the browser of a user for whom access is restricted, an error will return. The server-side script will not return an error in this case. It works the same way when getting a list of app items. A client-side script will only return the items that the current user has access to. A server script will return all the items.

Usually, scripts in widgets do not require powerful hardware to operate, so we recommend writing client-side scripts whenever possible.

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

S1

In a widget's client script you can use Javascript libraries and custom functions. To do that, go to the Files tab of the designer. Upload one or several .js files with a set of functions or libraries. On the Scripts tab, use the import declaration to add the files to the source code.

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

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

Now you can refer to functions from this library in the script's code.

Also, client scripts allow using functions that are called automatically when displaying the widget. You can read more about that in System functions in widgets.

Call a server method from a client-side scripts

It's not always that 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.

A server-side script can, for example, refer to some 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 Server.rpc:

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 its returned type must be Promise<void>, only then will it appear in auto-complete for the client script.

Script use cases

 

Widgets are a convenient tool for displaying the information under various conditions. For example, you can create a tip or additional fields that appear after some specific actions.

Let’s see how to use scripts with widgets using the example of a test with several questions.

Example 1. Expand a panel

The questions are collapsed by default. As soon as the user clicks Begin test, the first question panel should expand.

S2

Add Panel with header widget and name it Question 1. Add the Expand q1 variable in the Expanded field in the panel settings. This variable should have a Yes/No switch type. The panel will remain collapsed until the value of the variable changes for true.

S3

When the user clicks Begin test, the value of the variable should change. In order for that to happen, configure the button.

S4

Add the script that is going to change the value of the Expand q1 variable for true. Go to the button settings and add the script in the On click handler field. Click Create, and then click Open. Write the script.  

S5

You can follow this instruction for the most widget activities. Let’s move on to the next example.

Example 2. Show information box

 

Configure the On mouse enter handler field for the Information box widget. This is the notification box that appears if the user selects more than one answer.

S6

Click Create > Open. Write the script in the Scripts tab.

S7

This box should appear under several conditions. Describe them in the script:
S8

Example 3. A pop-up window

 

You can configure the Modal window widget in the same way. This is a pop-up window with the test results. Add the Yes/No switch variable to the Show window field. It will indicate whether the user has completed the test correctly.

S9

The value of this variable is determined by the script below:

S10

 

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