Bubble Docs

Using Custom Events

Custom events are a way to define a workflow in your page that can be reused multiple times ("functions" in a code-driven language).

When to use custom events

As a general rule in programming, whether it's on Bubble or in a traditional, code-driven language, you want to limit as much as you can redundant instructions, workflows, or lines of code. This helps having a leaner application and makes debugging, modifications, and maintenance much easier.
If you find yourself repeating the same logic, in other words the same sequence of actions, in more than one workflow, you can optimize your design by using a "custom event" that you will trigger in more than one workflow. For instance, if a user has two ways to sign up to a service, and the sign up flow does more than simply signing the user up, but also sends an email, some analytics, etc., this would be great candidate for a custom event. You would move the repeated sequence of actions into a custom event and use a Trigger custom event action in both workflows that sign the user up.

Defining a custom event

Defining a custom event is similar to defining a regular workflow. You pick an event and then add some actions. The event type here is 'Custom event', which is similar to other events, and can have a condition applied to it. One particular field is the ability to define at least one parameter for this workflow. For people familiar with traditional programming languages, the custom event is the function and accepts the parameters in its definition. The type of parameter for the custom event can be a database type you have defined in your app, or a simple type like text, number, etc. Moreover, you can specify whether the parameter is a list/array or optional.
As soon as you have defined at least one parameter for the custom event, you will be able to access the parameter in the Expression Composer in the following actions. For instance, if a custom event takes a user, you will be able to send an email to 'This Workflow User's email'. This expression will be evaluated with the user that was actually sent with the triggering action. If you want to reuse the same custom event in more than one page, you can add the custom event in a reusable element. Doing so, any page that has this reusable element will have access to the custom event.

Triggering a custom event

Once a custom event has been defined, you can add some actions to your workflows to use this workflow. Just pick the 'Trigger custom event action' (or the 'Trigger custom event action from a reusable element' action if you added the event in a reusable element).
If at least one parameter has been defined, you will have to pick a thing to send for each action. The type of the thing needs to match the type of the parameter that was defined as the workflow level, and type inconsistencies will be flagged as issues.

Scheduling a custom event

You can also schedule a custom event to occur at a later time.

Triggering vs scheduling custom events

You may wonder whether there's a difference between triggering a custom event and scheduling a custom event to occur with 0 delay. Yes, there is.
Let's say you have a parent workflow that has some actions, then a "Trigger a custom event" action, then some more actions. When the parent runs that Trigger action, the parent will pause and wait for the custom event to complete before running the actions that come after it. This is convenient in part because the custom event will be able to see the context of what happened in the actions before it in the parent workflow.
In contrast, if you schedule the custom event to occur with delay 0, that custom event could end up running in parallel to the rest of the parent workflow.

Execution of a custom event

When a workflow is triggered in Run-mode and hits a trigger a custom event action, the first workflow will pause, the custom event will be run till completion, and the first workflow will resume. Using the debugger can be very helpful to understand the flow of actions if you are hitting some difficulties setting things up. For more detail about our execution rules, please refer to here.