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

System functions in widgets

Client scripts in widgets support two functions that are called automatically when displaying a widget:

  • onInit is called when initializing the widget before it starts to display the interface template;
  • canRender is called after onInit, and returns true if the widget has to be displayed or false if the widget shouldn't be displayed.

These functions are not compulsory.

onInit

By the time the execution of the function starts, the input data in the widget's context, Context.data.* has been filled in. You can add whatever data is missing data to the method's body, and it will be later used to display the widget or execute a custom function. Also, in the method's body you can call API methods or server functions.

async function onInit (): Promise<void> {
   // Function's body
}

Example

Let's say you need to create a widget that will display full names of users alongside with their date of birth, as a table.

Add a "users" variable of the Table type to the widget, as well as two String variables: "name" and "birthDate.  

Place the "users" variable on the template's canvas. In client scripts, write the onInit function:

async function onInit (): Promise<void> {
    const users = await System.users.search().size(100).sort('__name', true).all();
    for (const user of users) {
        let item = Context.data.users!.insert();
        item.name = user.data.__name;
        item.birthDate = user.data.birthDate ? user.data.birthDate.format('L') : '';
    }
    Context.data.users = Context.data.users;
}

canRender

Use this function when you need to display the interface template only in case a certain condition is met, for example, when the context input data is filled in.

async function canRender (): Promise<boolean> {
   // Function's body (must return true/false)
}

The canRender function is different from the Hide system field. If the value of the Hide field is true, the template is still displayed because it is hidden from users only when an option is flagged in the web element's styles. When the canRender function returns false, the template isn't displayed at all. This is applicable, for example, when using complex widgets where displaying a template can cause an error if certain required fields are empty.

Example

Let's say you need to create a widget to display short info about an item of the "Contracts" app.

Create two variables: "date" variable of the Date data type, and "number" variable of the Number type. As input parameter specify the variable storing the Document app. In our case, it will be used to store an item of the "Contracts" app.  

This widget can be reused in different business processes and on forms of apps that have a Document app  context variable. The widget's template should not be displayed if the input field is empty.

To make that possible, add an "app" variable to store a Document app. Also, add additional "date" and "number" variables. Their types must match the similar fields in the "Contracts" app. Uncheck the Input and Output boxes for these variables.

Place the "date" and "number" variables on the form and mark them as Read only. To make the widget stand out on the page, put it into a box. To do that, go to the HTML styles field and specify the following:

border: 1px solid gray;

In client scripts, write the onInit and canRender functions:

async function onInit (): Promise<void> {
   if (!await canRender()) {
      return;
   }
   const appItem = await Context.data.app!.fetch();
   Context.data.date = appItem.date;
   Context.data.number = appItem.number;
}
async function canRender (): Promise<boolean> {
   return !!Context.data.app; // Returns true if the app field is filled in
}

After you have published the script, place the widget on the form of any other app that has a variable for storing an item of a Document app, and map this variable with the input field of the widget.

Now, the widget will be displayed on pages of items that have this field filled in. If the field is empty, nothing will be shown, neither the box nor the hidden elements of the widget.

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