Custom Actions

While building your app, you may encounter situations where you want to use a pre-built package or plugin 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 app builder.

Inside the editor, you can define incoming and outgoing parameters and easily check for any errors. With this, you can seamlessly integrate packages into your app without ever leaving our App builder.

Adding Custom Action

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:

1. Create Custom Action

To create a Custom Action:

  1. Click on the Custom Functions from the Navigation Menu (left side of your screen).

  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 with the starter code, and then click </> Copy to Editor.

  7. Save the progress.

2. Configure input and output

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.

    3. Set the Type of the incoming value to a suitable type.

    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 clear the Nullable option.

  3. Click the [</>] icon to view the boilerplate code; a popup will open with the updated code, and then click </> Copy to Editor.

  4. Save the progress.

3. Add dependency

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.

4. Add code

To add the code:

  1. Inside the code editor, add the import statement at the top (obtained in this step).

  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 our Code Copilot tab to generate code from text. Simply write 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 the 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, geoHasher.encode(98, -43) to geoHasher.encode(lat, lng)

  5. Save the progress.

5. Compile and save

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.

6. Trigger Custom Action

The newly created Custom Action will be available when you are adding the action. See how to trigger the Custom Action.

pageCustom Action

7. Optional: Use Custom Action result

To use the Custom Action result, ensure you provide 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:

Adding callback action

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:

1. Add action as a parameter

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.

2. Modify code

Before you proceed, make sure you add the dependency and basic code for the custom action.

Determine the place from where you want to trigger the callback action and write the name of the parameter followed by the (); like this:

showSnackbar();

Compile and Save the progress.

3. Adding 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:

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.

Supported Data Types

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 {"firstName":"John", "lastName":"Doe"}.

  • 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).

  • Uploaded File: To pass/receive locally uploaded files such as PDF, Audio (MP3), or any other file type.

  • Action: To pass/receive any action.


Last Updated Date: September 4, 2023

Last updated