While building your app, you may come across situations where you want to use a pre-built package or plugin that's available on pub.dev. It could be anything from a utility package to a full-fledged UI kit. With our Custom Actions editor, integrating these packages becomes much easier. You can define or write the required Dart code to use a package right within our UI builder.
Our Custom Actions editor allows you to define incoming and outgoing parameters, and you can easily check for any errors right within the editor. This means you can seamlessly integrate packages into your app without ever leaving our App builder. It's a simple, streamlined process that ensures your app has all the functionality you need.
Let's see how to add a Custom Action by building an example that calculates the Geohash (Geohash is a special code that helps you find where something is located on a map) from lat,lng values using a dart package. Here's how it looks:
Here are the steps:
To create a Custom Action:
- 2.Click + Add and select Action. This will add the default newCustomAction.
- 3.Set the Action Name.
- 4.In case you want to run a project, even if this action has an error, checkmark the Exclude from compilation (see on the right).
- 5.You might need a BuildContext of a widget for the custom action code to work. To do so, tick the Include BuildContext (see on the right). It will be available as an argument to the Custom Action.
- 6.Click the [</>] icon to view the boilerplate code; a popup will open showing the starter code, and then click </> Copy to Editor.
- 7.Save the progress.
Creating Custom Action
Your custom action might need some data to process and return the result. You can do so by configuring the input and output. For this example, the input will be lat and long values, and the output will be the Geohash. Here's how you do it:
- 1.To get output from Custom Action, turn on the Return Value.
- 1.Under the Return Value section,
- 1.Set the Type of return value to a suitable type. For example, if the Custom Action returns a text, set the Type to String.
- 1.If your Custom Action returns a list of data, such as a list of numbers or a list of fruits' names, tick the List option.
- 2.To pass input:
- 1.Click on the + Add Argument (under the Define Arguments section).
- 2.Enter the Name of the first parameter in the Argument 1 input box.
- 4.Determine whether you need to pass a single item or multiple and set the List accordingly.
- 5.When you are sure this argument will always have a value and will not be null, you can uncheck the Nullable option.
- 3.Click the [</>] icon to view the boilerplate code; a popup will open showing the updated code, and then click </> Copy to Editor.
- 4.Save the progress.
Configure input and output
To access the dependency code, you must add the dependency name in our code editor. To do so, click on + Add Dependency and paste the dependency name obtained in this step and click the refresh button and then Save the progress.
A dependency might depend on other dependencies to work. So make sure to add all the other dependencies as well.
To add the code:
- 2.Add the code snippet of your custom action. Most dependencies on pub.dev will have a sample code in Readme or Example section. You can copy the code snippet and only keep the required parameters.
- 3.Alternatively, you can also use OpenAPI Codex to generate code from text. Simply tell Codex what kind of action you need, for example, 'calculate geohash from latitude and longitude,' and it will generate a sample code you can use. Note that it will generate code based on the dependencies you added. If you generate code without adding any dependencies, you may need to figure out the dependencies (used in generated code) on your own and then add them in the code editor.
- 1.To get the code, click Copy Action.
- 2.To regenerate code with another variation, click the refresh button.
- 4.You must replace the hard-coded parameter values in the code with the ones you defined in this step. For example,
- 5.Save the progress.
Add code manually
Add code using Codex
Add code manually
Add code using Codex
When you are done adding the code, you can compile it to ensure there are no errors. To do so, click Compile Code button. If everything is ok, you'll see the No Errors! button, otherwise, you'll see the Has Errors button (click on it to see errors).
Once compiled, you can click Save button.
The newly created Custom Action will be available when you are adding the action. See how to trigger the Custom Action.
To use the Custom Action result, ensure you have provided the Action Output Variable Name while adding the action, and then you can access it via the Set from Variable menu > Action Outputs > [Action Output Variable Name].
Here's how you do it:
Use Custom Action result
A callback action is an action that is passed as a parameter to a custom action and is triggered at some point in the future when a certain event occurs.
This is especially helpful when you want to trigger actions from inside the custom action logic and include them as a part of a custom action. For example, when some error occurs inside the custom action logic, you could trigger an action immediately to inform the user about the error and then continue the execution or end with a default value to return.
We don't support sending any data with callback action (e.g., a message from a custom action to be displayed inside the snackbar callback action). Still, you can utilize the App State variable to save the data processed/emitted by the custom action and use it where required.
Let's see an example of a custom action that extracts the image URL from the XML data. If parsing XML data is successful, we show the picture in the Image widget, and if it fails, we immediately display a failure message and show the default image.
Here is how it looks:
Here are the steps to build such an example:
Adding a parameter of type Action helps you trigger any supported action from within the custom action.
First, ensure you have created a custom action and then add a parameter with any name of Type Action.
For this example, we'll add an action as a parameter named 'showSnackbar' so that we can trigger the snackbar action from inside our custom action code.
Add action as a parameter
Determine the place from where you want to trigger the callback action and write the name of the parameter followed by the
Compile and Save the progress.
Trigger callback action
At this point, we are done with modifying the custom action. Now add the custom action as you would normally do, and you will see that the callback action parameter will be displayed. Here you can add any action to let users know about the error. For this example, let's add a Snackbar action. This will be triggered whenever parsing the XML data fails.
Here's how you do it:
Adding callback action
Going further, you can use custom action output variable to store the image URL in a page state variable and then use it to display on the Image widget.
The following data types are available while defining the parameters for Custom Actions.
- Integer: To pass/receive numbers such as 100, 4302, 50000, etc.
- Double: To pass/receive a decimal number such as 12.43, 3233.50, 65.5666, etc.
- Boolean: To pass/receive either a true or false value.
- String: To pass/receive plain text such as title, description, etc.
- Image Path: To pass/receive the URL of the uploaded image.
- Video Path: To pass/receive the URL of the uploaded video.
- Audio Path: To pass/receive the URL of the uploaded audio.
- Color: To pass/receive color value.
- Document Reference: To pass/receive a reference of a document.
- Document: To pass/receive the actual record, i.e., a Firestore document.
- JSON: To pass/receive the JSON value such as
- DateTime: To pass/receive date and time value.
- TimestampRange: To pass/receive the start date-time and end date-time values.
- Lat Lng: To pass/receive the latitude and longitude of a particular place.
- GooglePlace: To pass/receive the GooglePlace data.
- Data Type: To pass/receive custom data type (aka Firestore Map).
- Supabase Row: To pass/receive actual row data from a Supabase table.