Skip to content

Managing Events

Overview

Bellini has no dedicated event type. Instead, events are a pattern built on exported Function declarations: when something meaningful happens inside a component — a button is clicked, an item is selected, a form is submitted — the component calls an exported function, and the consumer wires up a handler to respond.

This pattern mirrors how built-in components work. Properties like On Click and On Change on built-in components are exactly the same mechanism.

What You Will Learn

  • How to define a component event using an exported function declaration
  • How to fire the event from inside the component
  • How to handle the event as a consumer
  • A complete worked example from both perspectives

When To Use This

Use this pattern when a component needs to notify its consumer that something has happened — for example, a button was clicked, an item was selected, or a form was submitted — and the consumer needs to respond with its own logic.

Defining an Event

To define an event, create a Function declaration in the Component Editor and mark it as exported.

By convention, event declarations are named with an on prefix that describes what happened:

  • onSendClick
  • onItemSelected
  • onFormSubmit

If the event carries data that the consumer needs to act on, declare those as Parameters in the export configuration. The parameter names are shown to the consumer in the expression editor when they wire up their handler, so use descriptive names.

An event function typically does not have a return value — its purpose is to notify, not to compute. Because the function body is provided by the consumer, an exported function cannot have its own implementation inside the component. Do not try to give it one.

For the export configuration UI, see Declarations — Exported Declarations.

Firing an Event

To fire an event, call the exported function from inside the component — in a function body or expression — using $ctrl:

1
$ctrl.onSendClick();

If the event carries data, pass it as arguments:

1
$ctrl.onItemSelected(item);

Exported functions are always safe to call. They are never null or undefined, so no guard is needed.

Handling an Event

From the consumer's perspective, an event appears in the Properties view under the component's section, named after the exported function (e.g. "On Send Click"). The consumer wires up a function declaration from the current page or component as the handler.

By convention, handler functions are named with a handle prefix that mirrors the event name:

  • handleSendClick for onSendClick
  • handleItemSelected for onItemSelected

For the full UI details on wiring up function bindings, see Exported Properties and Functions — Setting Function Bindings.

Worked Example

The following example shows an OrderSummary component that fires an event when the user clicks a send button, passing the current order ID back to the page.

Component author: define and fire the event

  1. In the Declarations panel, add a Function declaration named onSendClick.
  2. Check Export and add a parameter named orderId.
  3. Add a Function declaration named handleButtonClick (not exported) with this body:
1
$ctrl.onSendClick($ctrl.orderId);
  1. Bind the internal button's On Click property to $ctrl.handleButtonClick().

Consumer: handle the event on the page

  1. On the page, inject an API service (e.g. OrdersApi) via the Declarations panel.
  2. Add a Function declaration named handleSendClick with a parameter orderId, and call the API service in the function body:
1
2
3
async function handleSendClick(orderId) {
  await $ctrl.ordersApi.sendOrder({ orderId });
}

Note: To use await in a function body, check the Async checkbox in the function editor dialog.

  1. Select the OrderSummary component on the page and open the Properties view.
  2. Locate On Send Click and click the edit icon to open the function picker.
  3. Select handleSendClick — Bellini generates the expression:
1
$ctrl.handleSendClick(orderId)

The orderId parameter defined on the event is automatically available in the expression editor's Parameters tab, ready to be passed through to the handler.

Best Practices

Prefix event declarations with on. This communicates intent immediately and is consistent with built-in component conventions. A consumer scanning the Properties view understands that onSendClick is something to react to, not a value to configure.

Prefix handler functions with handle. handleSendClick is clearly a response to a specific event, not a general utility function. It also makes the pairing between event and handler obvious at a glance.

Keep parameters descriptive and minimal. Only pass what the consumer actually needs to handle the event. A parameter named orderId tells the consumer exactly what to expect; a generic data or args does not.

Fire events from functions, not directly from UI bindings. Wiring a built-in button's On Click directly to $ctrl.onSendClick(orderId) works, but wrapping it in an internal function keeps the component's logic in one place and makes it easier to extend later (e.g. validate before firing).

Helpful Resources