Docs

Docs

Listening to Element Events

Listen to any browser events on the server.

The Element API contains methods to receive events and event data from the browser and handle them on the server side.

Registering Event Listeners

Use the Element.addEventListener() method to listen to any browser event.

Example 1. Using the addEventListener() method to react to a click event
Source code
Java
Element helloButton = ElementFactory.createButton("Say hello");
helloButton.addEventListener("click", e -> { 1
    Element response = ElementFactory.createDiv("Hello!");
    getElement().appendChild(response); 2
});
getElement().appendChild(helloButton);

  1. Clicking the "Say hello" button in the browser sends the event to the server for processing.

  2. A new <div>Hello!</div> element is added to the DOM.

Accessing Data from Events

You can get more information about the element or user interaction by defining the required event data on the DomListenerRegistration returned by the addEventListener() method.

Example 2. Using the addEventData() method to define the required event data
Source code
Java
helloButton.addEventListener("click", this::handleClick)
    .addEventData("event.shiftKey") 1
    .addEventData("element.offsetWidth");

private void handleClick(DomEvent event) {
    JsonNode eventData = event.getEventData(); 2
    boolean shiftKey = eventData
            .get("event.shiftKey").asBoolean(); 3
    double width = eventData
            .get("element.offsetWidth").asDouble();

    String text = "Shift " + (shiftKey ? "down" : "up");
    text += " on button whose width is " + width + "px";

    Element response = ElementFactory.createDiv(text);
    getElement().appendChild(response);
}

  1. The requested event data values are sent as a JSON object from the client.

  2. You can retrieve the event data using the DomEvent.getEventData() method in the listener. It returns a Jackson JsonNode (from tools.jackson.databind).

  3. Look up each value by the same key you passed to addEventData(), then read it with the accessor that matches its type — for example asBoolean(), asInt(), asDouble(), or asText().

Note
Return Type Changed from Elemental JSON
DomEvent.getEventData() now returns a Jackson JsonNode (tools.jackson.databind.JsonNode) instead of the previous Elemental JsonObject. Code written for earlier versions no longer compiles: replace JsonObject with JsonNode, and the Elemental getters such as getString(key), getBoolean(key), and getNumber(key) with get(key).asText(), get(key).asBoolean(), and get(key).asDouble(). See the upgrade guide for the full list of Elemental-to-Jackson changes.

Filtering and Debouncing

Filtering and debouncing are covered in detail in Declaring and Firing Component Events, in the context of the @DomEvent annotation. However, you can configure the exact same settings through the DomListenerRegistration object.

465CAE8B-8B0D-426B-818F-1CF58A9BD034

Updated –