Events

Events in Hologram are user interactions that can trigger actions or commands. They are the primary way to make your application interactive and responsive to user input.

Event Types

Hologram supports various event types that you can bind to elements in your templates (more are coming soon):

• blur - triggered when an element loses focus
• change - triggered when the value of an input element changes
• click - triggered when an element is clicked
• focus - triggered when an element receives focus
• pointerdown - triggered when a pointer (mouse, touch, pen) is pressed down on an element
• pointerup - triggered when a pointer (mouse, touch, pen) is released from an element
• select - triggered when text is selected in an input or textarea element
• submit - triggered when a form is submitted
• transitioncancel - triggered when a CSS transition is cancelled before it completes
• transitionend - triggered when a CSS transition has finished
• transitionrun - triggered when a CSS transition is created
• transitionstart - triggered when a CSS transition has started

Event Data

When an event occurs, Hologram provides event data that you can access in the action or command that was bound to handle that event. This data is available in the params argument under the :event key. The event data structure varies depending on the event type:

Change Event

The change event includes:

• value - the current value of the form element as a string

Pointer Events

Pointer events (like click, pointerdown, pointerup) include:

• page_x - X coordinate relative to the page
• page_y - Y coordinate relative to the page
• pointer_type - the type of pointer that triggered the event, as an atom (:mouse, :touch, or :pen), or nil if the device type cannot be detected by the browser

Pointer events are ignored in the following cases:

• When the ⌃ Ctrl key is pressed
• When the ⌘ Command key is pressed
• When the ⇧ Shift key is pressed
• When the middle mouse button is clicked

Select Event

The select event includes:

• value - the selected text value

Submit Event

The submit event includes form field values directly under the :event key. For example, if your form has fields named "email" and "password", the event data will look like:

%{email: "user@example.com", password: "secret"}

Event Binding Syntax

When binding events to elements in your templates, prefix the event name with a dollar sign ($). You can bind events using several syntax options. Note that text and shorthand syntax are only available for actions. To trigger a command, you must use the longhand syntax with the command: key.

Text Syntax (Actions Only)

The simplest way to bind an event to an action:

<button $click="my_action">Click me</button>

Expression Shorthand Syntax (Actions Only)

Use this syntax when you need to pass parameters to the action:

<button $click={:my_action, param_1: 1, param_2: 2}>Click me</button>

Expression Longhand Syntax

For complete control, including targeting specific components and triggering commands:

<button $click={action: :my_action, target: "other_component", params: %{key: value}}>Click me</button>

To trigger a command, use the command: key instead of action:

<button $click={command: :my_command, params: %{key: value}}>Click me</button>

Event Targets

By default, events are handled by the component that contains them. If the component is stateless (doesn't have a CID specified), the closest stateful component higher in the hierarchy is used. You can specify a different component for handling the event using the target parameter:

<button $click={action: :my_action, target: "other_component"}>Click me</button>

Valid targets include:

• "page" - targets the current page
• "layout" - targets the current layout component
• a string representing a component ID (CID) - targets a specific component by its unique identifier within the application

Event Flow

When an event occurs, it can trigger either an action or a command:

• Actions - client-side operations that can update component state, trigger commands, and more. See Actions for more details.
• Commands - server-side operations that can access server resources, trigger actions, and more. See Commands for more details.

Best Practices

When working with events in Hologram, consider these best practices:

• Use meaningful action and command names that describe what they do
• Keep event handlers focused on a single responsibility
• Use the appropriate event type for the interaction you want to handle
• Be mindful of event bubbling and use event targets appropriately
• Use keyboard events for accessibility and keyboard navigation
• Handle form events properly to ensure good user experience