| description |
|---|
Multiple Queries can be triggered in serial/parallel/conditional when a user interacts with a widget |
When you build an app on Appsmith, you manipulate data; add, update, delete and retrieve data, add actions and trigger them. You use Javascript functions, APIs, or Queries to build different workflows.
{% hint style="info" %} To create workflows, you should be familiar with triggering actions from widgets and expand on triggering more complex actions. {% endhint %}
The widgets have fields you can use to bind data or trigger operations. Appsmith has segregated the fields into Sync and Async fields.
Whenever you drag a widget on the canvas, you can select it and see the properties associated with it in the properties pane. The fields that expect input or data in the properties pane are called Sync Fields.
For example, if you have added an Input widget to the canvas, the properties like MaxChars, Regex, Error Message, and so on expect some input and are Sync Fields.
The properties that can trigger an action or perform an operation are called Async Fields.
For example, the properties like OnTextChanged and OnSubmit of an input widget are considered async fields. You can use these properties to define an action or perform an operation.
{% embed url="https://youtu.be/yn_8gs5w04g" %}
Let's look at some examples to understand how you can use async functions in sync fields.
You are fetching all the users and displaying information like First Name, Last Name, Email, and more on a page. You have a table widget to display the data.
Using an API
You have an API that fetches Users. You want to trigger the API execution, so you bind the API call to the widget, and the response generated will be shown in the table.
To add a Table widget; Navigate to Explorer >> Click Widgets >> Search table >> Drag a table widget onto the canvas. ****
{% embed url="https://youtu.be/iYZV9DPnugY" %} How to call API in the Sync field? {% endembed %}
To read data by using an API: Create an API - getAllUsers on Appsmith by adding the API from Explorer >> Click (+) Query/JS >> Select New Blank API >> Rename to getAllUsers (or select an existing API) Add API call to the table data property of a table widget as shown in the code snippet below:
{{getAllUsers.data}}
{% hint style="info" %} The table data property of a table requires a JSON Array so verify that your API returns a JSON Array. {% endhint %}
A {{API.run()}} method, if supplied to the Table data, will throw an error, as table data is a Sync field and cannot perform the execution. However, you can read the response generated by the API by accessing the data property {{API.data}} of an API. When you bound an API data property to a widget, Appsmith executes the API on page load. You can modify the API settings if you wish not to execute the API on page load.
Using a JSObject
You have a JSObject function that fetches all Users’ information, filters data for firstname & email, and then returns the result so you can bind it to the table widget and display information.
{% embed url="https://youtu.be/8mVQS6uaR6M" %} How to call an async JSObject function from a Sync Field? {% endembed %}
To read the data by calling a JSObject function: Create a JSObject - getFilteredUsersList on Appsmith by adding a JSObject from Explorer >> Click (+) Query/JS >> Select New JS Object >> Rename to getFilteredUsersList (or select an existing JSObject) You can add your API or Query Call to the function call and filter the data for the required details as below:
export default {
userFilteredList: async () => {
const listUser = await getAllUsers.run();
return listUser.map((user) => {
return {
"firstname" : user.name,
"email" : user.email
}
})
}
}
A function call to the JSObject getFilteredUsersList.userFilteredList() will throw an error as table data is sync field and cannot perform function execution. However, you can use the JSObject function response by adding {{<JSOBJECTNAME.FUNCTIONAME.data>}}( {{getFilteredUsersList.userList.data}})by reading the function's response. Appsmith handles the JSObject function execution on page load. You can modify the async function settings from the settings tab if you wish not to execute the function on page load.
Using a Query
You have a query that fetches Users’ information, returns the response, and binds it to the table widget to display data.
{% embed url="https://youtu.be/hqkI0h7DQ-s" %} How to trigger a query execution from a Sync field? {% endembed %}
To read data by calling a query: Create a Query - fetchUsersList on Appsmith by adding a Query from Explorer >> Click (+) Query/JS >> Select DatabaseName for which you want to add Query >> Rename to fetchUsersList (or select an existing Query) Assuming that the table name is Users. Add the following code to the query editor.
Hint - Replace users with the table name in your database
SELECT * FROM users ORDER BY id LIMIT 10;
An execution call to the query fetchUsersList.run() will throw an error as table data expects data and cannot perform query execution. However, you can read the query response and use it in the Table data to display records by using {{<QUERY_NAME.data>}}(fetchUsersList.data). Appsmith handles the query execution on page load. You can modify the query settings from the settings tab if you wish not to execute the query on page load.
You can trigger the actions by binding them with Async fields. For example, you want to show a success message on the submission of a button by using showAlert(). You'll have to bind the [showAlert()](Add a link to Actions - Show Alert method) function on the onClick() event.
{% hint style="info" %} You can only use the global actions provided out-of-the-box by Appsmith in the async fields, which are events or actions. {% endhint %}
{% embed url="https://youtu.be/tjJIDkoCyQE" %} Execute a global function from an async field {% endembed %}
The property pane allows us to configure the action to take once a Query returns with a success or an error. Success / Error is determined by the HTTP status code or the query response status returned by the API / Query.
We can decide to display a success or an error message by using the showAlert Action.
The GUI is limited to a single onSuccess / onError callback while the underlying framework has no limitation. To write complex workflows that cannot be accommodated in the GUI, click on the JS icon next to the event name & enable JavaScript. Now you can write conditional workflows and chain multiple Queries.
{% hint style="success" %} Once you have configured actions using the GUI, you can click on the JS icon next to the event to show the JavaScript equivalent of your configuration. This can help you learn to use JavaScript to configure workflows! {% endhint %}
Every query object contains a run method that is used to execute it. The run method is asynchronous and multiple queries can be executed in parallel as below
{{ API1.run(); Query2.run(); API2.run(); }}or chained to be called onSuccess / onError using the callback arguments in the Run Signature
{{
updateUsers.run()
.then(() => fetchUsers.run()
.then(() => {
showAlert('User Updated');
closeModal('Modal1');
})
.catch(() => showAlert("Fetch Users Failed"))
).catch(() => showAlert("Update User Failed", "error"))
}}Queries can also be chained to execute conditionally based on the value of a widget or the response of a Query
{{
statusDropdown.selectedOptionValue === "Pending" ?
fetchPendingUsers.run(() => {
fetchPendingUsers.data.length === 0 ? showAlert("No Users Pending Approval", "info") : showAlert("Fetched Users", "success");
}) :
fetchApprovedUsers.run();
}}{% hint style="success" %} Make use of the Appsmith Framework and External Libraries to quickly build logic into your applications {% endhint %}