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 UI 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.
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 with the starter code, and then click </> Copy to Editor.
- 7.Save the progress.
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 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.
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 our Code Copilot (powered by GPT-3.5 Turbo) 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.
- 5.Save the progress.
Add code manually
Add code using Code Copilot
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.
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:
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:
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.
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:
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).
- 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