Actions
Actions define the behavior of the app in response to user interactions with the app's elements or widgets. These actions can be triggered by various user gestures (or touch), such as tapping on a button, selecting an option from a dropdown list, or submitting form, on page load.
Actions can be simple or complex, depending on the app's requirements. Simple actions might include displaying a message, navigating to a new screen, or updating the value of a variable. Complex actions might involve making an API call or integrating with other third-party services using custom actions.
By defining actions in response to user interactions, you can create more engaging and intuitive user experiences.
Types of action
Most of the widgets can handle three basic types of action:
On Tap: Handles the user gesture of a single tap.
On Double Tap: Handles the user gesture of double tap.
On Long Press: Handles the user gesture of tapping and holding for a duration.
Apart from these common types of action, there are a few more action types that are available on some specific widgets:
On Submit: This is available on a TextField widget. The action is triggered when the user finishes editing the text and indicates that they are done, such as by pressing the "submit" or "done" button on their keyboard.
On Page Load: This is available on the page widget. The action is triggered as soon as the page loads and can be used to execute various tasks, such as fetching data from a database, displaying a message or notification, or updating the content of the page. By using this, you can ensure that certain tasks are automatically executed when a page is loaded, without requiring any additional user input.
On Phone Shake: This is available on the page widget and is triggered by physically shaking your phone. When the phone is shaken, the action that has been set will be executed, which can include various functions such as displaying a message, opening a new page, or initiating a phone call. This feature is commonly used in gaming apps, where shaking the phone can trigger a particular action, such as rolling dice or shuffling cards.
On Selected: This is available on widgets, such as Dropdown, CheckboxGroup, Slider, RadioButton, ChoiceChips, RatingBar. This action is triggered as soon as the selection changes on these widgets.
On Page Swipe: This is available on the PageView widget. The action added under this is triggered whenever the page is swiped.
On Toggle: This is available on the ToggleIcon widget. Actions added under this are triggered every time the toggle icon is clicked.
On Completed, On Change: This is available on the PinCode widget. Actions added under this are triggered when a user is done entering a pin or changes a pin in the PinCode widget.
On Count Changed: This is available on the CountController widget. Actions added under this are triggered whenever the count changes in the CountController widget.
Adding action
To add an action on any widget:
Select the Widget (e.g., Button) on which you want to add the action.
Select Actions from the properties panel (the right menu).
To add a simple action, such as navigating to a page or showing a snackbar message:
Click + Add Action button.
Select the Type of Action. By default, this is set to On Tap.
Search and select the action.
To add actions based on a condition or complex action flow:
Click + Add Conditional Action. This will open the action flow editor.
To add a new action in the same action flow, use the + button.
NOTE: Actions differ according to the widget selected. If you are applying an action on a TextField widget, On Submit gesture is available. Similarly, if you are applying an action on the page widget, On Page Load will be available.
Adding multiple actions
You can define a sequence of actions to trigger when a particular user interaction takes place. For example, when a user taps a button, you could have actions that first update the variable and then inform the user.
The one on the top will be triggered first followed by the rest.
Adding conditional actions
Conditional actions are triggered based on a specific condition or set of conditions. This gives you more flexibility and customized workflow that adapt to different scenarios or inputs. For example, you can use a conditional action to check if the user has entered the correct credentials before granting them access to the app. If the credentials are incorrect, you can display an error message, otherwise navigate the user to the home page.
You can add the conditional action in the following ways:
Conditional action with multiple branches (if > else if > else)
1. Single condition
A single condition is useful when you need to trigger actions based on a specific single condition that results in True or False branches. Some examples of when a single condition may be useful include:
Checking if a user is logged in before displaying personalized content.
Show a message if a user's device is not connected to the internet.
Set dark or light mode theme based on a variable.
To add a single condition:
Select the Widget (e.g., Button) on which you want to add the action.
Select Actions from the properties panel (the right menu), and click + Add Conditional Action.
From a Set Variable menu, select Conditions > Single Condition.
Click on the First Value and Set Variable (e.g., app state variable).
Specify how you would like to compare the first value with the second one (e.g., Equal To, Less Than, etc.).
Click on the Second Value and provide the value by selecting a Specific Value or From Variable.
In the True branch, add actions that you would like to trigger when the condition is true.
In the False branch, add actions you want to trigger if the condition is false.
Here's how to set up an action that checks if a user is over 18 and then takes appropriate steps based on the outcome:
Tip: You can also directly set a boolean value that returns true or false. Here's an example of triggering actions to set a dark or light mode theme based on the 'isDarkMode' boolean variable from an app state variable.
2. Multiple conditions
Multiple conditions are useful when you need to trigger actions based on a set of conditions that results in True or False branches. Multiple conditions are evaluated in sequence, and the action under the True branch is triggered if all the conditions are met. If any of the conditions are not met, the action under the False branch is executed.
Some examples of when multiple conditions may be useful include:
Trigger actions only if a user is admin and is in edit mode.
In the e-commerce app, decide the shipping method based on the destination address or the total order amount.
In a weather app, if the current temperature is above 80 degrees Fahrenheit and the humidity is above 70%, show an alert dialog to stay hydrated.
To add multiple conditions:
Select the Widget (e.g., Button) on which you want to add the action.
Select Actions from the Properties panel (the right menu), and click + Add Conditional Action.
From a Set Variable menu, select Conditions > Combine Conditions.
Under the First Condition, click on UNSET and add the single condition or directly provide the variable that returns a boolean value (True or False).
If you want all the conditions to be true, keep the AND tab selected. And if you want any one condition to be true, change it to OR.
Similarly, add the next condition.
To add more conditions, click on the + Add button.
In the True branch, add actions that you would like to trigger when all the conditions are true.
In the False branch, add actions you want to trigger if the condition fails.
Tip: You can also mix multiple AND conditions with the OR conditions. Here is an example of triggering a delete action when a user is logged in AND either admin OR event manager.
3. Conditional action with multiple branches (if > else if > else)
Instead of just having a simple true/false branch, you can now have multiple branches like if/else structures to add more complex and dynamic business logic within your app. For example, when the item is in stock, redirect a user to the cart page. If an item is not in stock but available for preorder, show a message and then open the cart page, and if both conditions fail, show an 'out of stock' message.
To use conditional actions with multiple branches, you first need to define conditions for the IF and all ELSEIF sections. After that, you can add actions under each branch. Lastly, you can add actions under the ELSE branch.
When executing the conditional action, the IF section is evaluated first. If its condition is met, the action under the IF branch will be executed. Otherwise, the next ELSEIF section is evaluated, and its condition is checked. If the condition is satisfied, the action under the ELSEIF branch will be executed. This process continues until either a condition is met or all ELSEIF sections are evaluated. If none of the conditions are satisfied, the action under the ELSE branch will be executed.
To add conditional action with multiple branches:
Select the Widget (e.g., Button) on which you want to add the action.
Select Actions from the Properties panel (the right menu), and click + Add Conditional Action.
Enable Multiple conditions.
In the First Condition (i.e., IF), click on UNSET and set either a single condition or multiple conditions or directly set a boolean variable.
To add one more branch, click on the + button. This will open one more branch called ELSEIF. Add condition here as well. Similarly, you can add more branches and define conditions for each one.
Now start adding actions under each branch, including the ELSE branch.
You don't need to define any condition for the ELSE branch. The action added under the ELSE branch will be executed if none of the conditions are met in IF and ELSEIF branches.
Terminate action
In some cases, it may be necessary to stop the action flow when it reaches a specific point. For instance, if you have a conditional action with multiple branches and some branches are merging in the next action. But, you may not want any action to merge with the next action and terminate without performing any further actions. This is where terminating an action can be useful. By adding a terminate action, you can halt the action flow at a particular point and prevent any subsequent actions from being executed.
To do so, simply click on the + button and select Add Terminate option.
Loop actions
Sometimes, you might want to trigger certain actions multiple times. Let's see an example where an app fetches data from a server, and you want to handle network errors by retrying the request up to a certain number of times.
Every loop requires a condition, and the actions added under the loop will continue to trigger as long as a condition holds true. Whenever the condition becomes false, the loop terminates, and the next actions in the workflow will trigger.
Be careful with loop actions because they can cause your app to enter an infinite loop if the condition never becomes false. Always ensure the condition will be met at some point so the loop can exit.
If the intended operation is completed before the condition becomes false, you must 'Add Loop Break' action in your workflow.
Let's see how to do that:
Open the Action Flow Editor and select + Add Loop.
Set the condition for the loop, e.g., retryCount (set to 0) is less than the maxRetries (set to 5).
Add the action you want to trigger as long as the condition is true. (e.g., make an API call).
On API call success, you must Add Loop Break action. This will come out of the loop as the API call succeeded.
On API failure, you can add some delay, and increament the retryCount.
By doing so, if the API call fails, it will continue to trigger until the retryCount reaches to maxRetries.
Add Parallel actions
Parallel actions refer to executing multiple tasks simultaneously rather than waiting for each one to complete before starting the next. This approach can significantly improve your app's performance and efficiency, especially when dealing with time-consuming operations like network requests or data processing.
For example, in the weather app that aggregates data from multiple weather APIs, parallel actions are particularly useful. Instead of sending a request to one API, waiting for the response, and then repeating the process for the other APIs, you can send all the requests at the same time. This way, you're not waiting for each individual response, and you can start processing the data as soon as all responses are received.
To use parallel actions, follow these steps:
Open the Action Flow Editor and select + Add Parallel Action to start a new parallel action block.
By default, two actions (Action 1 and Action 2) are added to the parallel block. To add more actions within this block, click on + Add Action on the right side.
Under each sub-tree, add the actions you want to execute in parallel.
You can add a final action that will be triggered after all the parallel actions have been completed. This can be an action that depend on the results of the parallel actions.
Action block
An Action Block is a set of actions that performs a specific task and can be reused in different parts of the app. If you find yourself performing a particular set of operations repeatedly in your app, it may be helpful to create an action block. It allows you to break down complex actions into smaller, manageable units of action, making it easier to understand and modify in the future.
Imagine you have an app that interacts with an API. Whenever an API call returns a response indicating invalid credentials, you want to navigate the user back to the login page to re-authenticate. Instead of repeating this logic in every API call, you can create an Action Block that encapsulates this behavior. Here's what it might look like:
Here's how you can add an Action Block:
First, create an action Action Block:
Select any widget on a page, select Actions from the Properties panel (the right menu), and then select Action Blocks.
Choose the Scope for your action block: App-level or Page-level. An App-level action block can be reused throughout your app, providing functionality across multiple pages. On the other hand, a Page-level action block is specific to the page where it is created, offering dedicated functionality for that particular page.
Click + Create Action Block.
Provide the Name of the action block.
If your Action Block returns any value (e.g., parsed data), enable the Return Value and then set the Output Type. If it returns a list of values, tickmark List. When you are sure, this will always return a value, tickmark Required.
If your Action Block requires input, enter the Name and Type of the parameter.
On the left side, add or copy-paste actions that you want to reuse.
Now to use the Action Block:
Inside the Action Flow Editor, click the "+" button and select Add Action Block.
Search and select the Action Block name.
Pass the input parameter(s) if it requires any.
If you need to refresh the page after executing the action block, simply enable the Update Page After option. This is particularly useful when a page displays a value that is expected to be updated by the action block.
You can view all the Action Blocks added at the App Level or Page Level from inside the Action Flow Editor. Tip: Click on any to open the Action Block in edit mode.
Return a value from action block
To return a value from anywhere in your action flow:
Click on the "+" button and select Add Return. Enable Add Return Value and set the value to return.
To access the return value, open the action flow editor where you have added the action block and provide the Action Output Variable Name.
Next, use the action output variable name from the Set Variable menu > Action Outputs > [action_output_variable_name] (from the action block).
Set action as 'non-blocking'
You can make some actions 'non-blocking', which means subsequent actions will keep executing even if the previous one isn't finished yet.
Non-blocking actions are great for situations such as preloading content in the background, synchronizing data with a cloud server, logging an analytics event, sending an API call where we don’t need the result immediately, sending an email or push notification, or starting a long-running server process.
To mark any action as 'non-blocking' just switch on the Non-Blocking toggle at the bottom.
Disable action
Sometimes, while working on a complex workflow, it can be beneficial to have the option to disable specific actions. For instance, you might want to test the action workflow by removing any action. But if you delete the action, it can be challenging to revert back without affecting other changes made across multiple pages. Having the ability to selectively disable or enable actions would simplify the process and save time.
To disable action, select the action tile, click the options menu icon, and then select Disable Action. Click again to re-enable.
Reordering actions
If you have added multiple actions, you can order them to specify which one should be triggered first, followed by the next one, and so on.
To reorder the actions, use the up and down arrow present on the top right side of the action tile.
Copying actions
While building your app, you may need to copy an action (probably the long or complex one) and paste/add it to the widget on the same or another page.
To copy actions:
To copy only the selected action, select Copy Action.
To copy all the actions under the selected actions, select Copy Action Chain.
Document an action
There's a high probability that you'll forget afterward how or why a specific action was introduced. Additionally, if you work in a team, other builders might want to know more about an action's existence or functioning, especially if it is a complicated one or a custom action.
By documenting an action, you may assist future you and others in remembering why it was included and learning more about the action. It helps you to make any change confidently and ultimately produces fewer bugs.
We will add the documentation inside the code as a comment.
Naming actions
To give a name to the action, click on the edit (pencil) icon and provide the name.
Deleting actions
To delete action(s) added to the widget:
To delete only the selected action, select Delete Action.
To delete all the actions under the selected actions, select Copy Action Chain.
Video guide
If you prefer watching a video tutorial, here's the one for you:
Last Updated Date: March 20, 2024
Last updated
