Asynchronous JavaScript Function Settings

The asynchronous function allows you to choose when you want to execute code. For example, you may want to delay the query execution or fetch the data on demand.
How to Define an Asynchronous Function in Appsmith?
In the Appsmith environment, a function is termed as async if you are performing one of the below actions:
You have a keyword (async) that marks the asynchronous execution of the function.
1
export default{
2
	functionName: async() => {
3
	   //use async-await or promises
4
	}
5
}
Copied!
You have any in-built Appsmith functions like showModal(), showAlert(), etc., added in the function block.
You want to execute a query or call an API on run time. For example, you have an API GetUsersList, and you want to call this API on runtime, that is, whenever the JS Object function callAPI() is executed. Your function may look as below:
1
export default {
2
   callAPI: () => {
3
      GetUsersList.run();
4
   }
5
 }
Copied!
The line of code GetUsersList.run() marks the function callAPI() for asynchronous execution and hence callAPI function is considered as async.
A JavaScript Editor in Appsmith provides some additional settings for asynchronous functions that will help you add more configurations.
You can specify the settings in the Settings tab on the Appsmith JS Editor.
Settings
You’ll see the Settings tab next to Code whenever you have added an asynchronous function to the JS Object. Head to the Settings tab and click on it to reveal additional configurations.
Let’s quickly dive into these configurations to understand how they help you make your application behavior better.
Navigate to JS Object —> You’ll see Settings next to Code
How to navigate to JS Object Settings for asynchronous function?
Click on Settings to reveal configurations.
Configurations available for asynchronous functions
You get two settings to configure for asynchronous functions:
RUN ON PAGE LOAD
CONFIRM BEFORE CALLING
The settings are available at the function level. For every asynchronous function defined, you’ll have a corresponding configuration available for a run on page load and confirm before calling. Refer to the screenshot below, where you can see that the functions - myFun2 and showData have configurations available that you can define for them individually.
The asynchronous function configurations are available for each async function defined in a JS Object.
RUN ON PAGE LOAD
As the name suggests, you can use the configuration to mark that your function will be executed whenever a page is loaded. For example, you have a page User Listing and have added a JS object with the function GetUserRole which fetches the user’s role. You want that the query should be executed at the time of page load so that the logged-in user will be able to see the user listing. To get this working, you have to set the RUN ON PAGE LOAD configuration as YES for the GetUserRole function. Once the configuration is in place, the function GetUserRole  will be executed whenever the app is loaded and the response generated by it will be displayed on the page.
By default, RUN ON PAGE LOAD is turned ON (Yes selected) for functions that display data on a widget. That is, the widget binds to the response generated by JSObjectName.asynFunctionName.data. In this case, the on-page load is automatically set as true. You can explicitly change this setting to suit your logic in the Settings tab.
If you wish to delay the call of function on demand, then select No. It marks that the function will not be called on page load, and the execution will be deferred until called on demand by calling the function.
Configure run on page load
On Appsmith, you can bind execution of JS Objects on page load in either of two ways:
Bind Response to Widget
Whenever you bind a query or API response to a widget, Appsmith automatically sets the execution of the corresponding API or Query on page load. For example, you have a widget that refers to the data property of the JavaScript async function by adding {{JSObject.myFun.data}}, at that time Appsmith marks the execution of that query/API on page load. You can modify the same by navigating to JSObject → Settings → RUN ON PAGE LOAD → Select No.
RUN ON PAGE LOAD Set to Yes when you bind function data to a widget
Here’s a quick snapshot of how Appsmith triggers a query or API execution on page load:
Add a table widget (Table1), and add a function in JSObject5 that calls an API getUsers. The getUsers API call is embedded in the showData function and generates a user listing.
Call a getUsers API in the showData JS function
Bind the response generated by showData to table widget Table1 by adding the below code in the Table Data property available on the property pane of the Table widget.
1
{{JSObject5.showData.data}} // behind the scenes Appsmith 
2
                           // marks execution of showData on page load 				        
3
                          // to get the response and bind it to the table data 
Copied!
showData function called on page load
Asynchronous Function Setting
Especially for asynchronous functions, you can explicitly mark the execution of an async function on page load for the corresponding JS Object.
Navigate to JS Object —> Click on Settings —> Select Yes for RUN ON PAGE LOAD next to the JS function. You are all set. Appsmith will take care of executing the async function on page load for you.
How to set run on page load for async function?
As shown in the screenshot below, you can see that the showData function is called on page load, and Table1 displays the data.
Data displayed in the table widget
CONFIRM BEFORE CALLING
With this setting, you can generate a confirmation pop-up and take the user’s input for executing the function. For example, the JS object has the function deletePermission which calls an API that deletes the database’s permission. You would want to ensure that the user wants to delete permission, in which case, you would like to show a confirmation dialogue. The confirmation dialog ensures that the user wants to perform a delete action. A user can choose Yes to delete or can decline the same by choosing No. Thus Confirm Before Calling comes in handy to protect against users accidentally running destructive operations.
A confirmation dialog is shown to the user before execution on myFun2
Configure confirm before calling
Confirmation is like a nudge given to the user before executing a function. It ensures that the user is aware of the action that would be performed, and the same is not triggered by chance. A confirmation setting can only be defined explicitly from the Settings tab.
Navigate to JS Object —> Click on Settings —> Select Yes for CONFIRM BEFORE CALLING next to the JS function. You are all set. Appsmith will take care of executing and showing the confirmation dialogue to the user whenever the action is triggered.
Configurations for CONFIRM BEFORE CALLING
When to use Asynchronous Settings?
Asynchronous function settings enable users to create complex workflows by executing functions before the application loads, allowing the data manipulation logic to run and make the desired outcome — secure function execution with a confirmation before you want application users to execute any critical operations.
Let’s understand the settings deeper with examples.
For example, you would want to apply restrictions in your application based on the user’s domain. That is, anonymous users (users who are not a part of your domain) cannot access certain application pages. You can quickly implement this by creating a function that uses the asynchronous function setting- Run on page load.
Appsmith users Vs Non-Appsmith users
Here’s a quick snapshot of steps that you can take to create this logic:
Create an application and add two pages to it
First Page (UserListingForAppsmithUsers)- Add a table, and rename it to UserListing which displays the data generated by the showUserListing function of the DataLoader JS object. The function generates a list of users.
Second Page (AnonymousUser) - Displays a message to the user.
Create a JS object DataLoader and add a function showUserListing that checks whether the user is logged in or not._ The function will verify the below logic:
If the user is logged in, then the GetUserList API will be called, and the response will be generated
If the user is not logged in or is not an appsmith user, redirect the user to the AnonymousUser page.
Mark function showUserListing of JS Object - DataLoader to run on page load by selecting Yes.
UserListingForAppsmithUsers - DataLoader JS object Code. You can see that a function showUserListing is marked for asynchronous execution by defining the async keyword.
1
export default {
2
	showUserListing: async () => {
3
		//use async-await or promises
4
		if(appsmith.user.isAnonymous) {
5
	       	  navigateTo("AnonymousUser");
6
		}
7
		//verify if the logged-in user is from appsmith
8
		if(appsmith.user.email.match("appsmith")){
9
		  return GetUserList.run();
10
		}else{
11
		  navigateTo("AnonymousUser");
12
		}		
13
	}
14
}
Copied!
For logged-in appsmith users, a user listing is shown as theGetUserList API is executed:
The user listing is displayed to logged-in appsmith users
Anonymous users - Whenever the application renders, the showUserListing function is executed. The function determines whether the user is anonymous. You can use the property of a user object isAnonymous to check the user's logged-in status.
1
appsmith.user.isAnonymous
Copied!
An anonymous user is shown the page with an unauthorized message
Suppose the user is not logged in, then appsmith.user.isAnonymous returns true and redirects the user to the AnonymousUser page and displays the message.
You are not authorized to view user data.
If the user is logged in appsmith.user.isAnonymous returns false and the logic is executed to verify if the logged-in user is an Appsmith user. If the user is an Appsmith user, GetUserList API is called to fetch the user listing. The execution is completed, and the response is generated, displayed in the UserListing table.
You can do authentication and authorization using the Async function settings. To get started;
1.​View and fork the authentication application;
2.​View and fork the authorization application.
With the out-of-the-box settings provided for async functions, you can manage the execution of your asynchronous functions and create a better user experience.