Package com.vaadin.flow.dom

Interface DomListenerRegistration

All Superinterfaces:
Registration, Serializable
public interface DomListenerRegistration extends Registration
A registration for configuring or removing a DOM event listener added to an element.
Since:
1.0
Author:
Vaadin Ltd
See Also:

  • Method Details

    • addEventData

      DomListenerRegistration addEventData(String eventData)
      Add a JavaScript expression for extracting event data. When an event is fired in the browser, the expression is evaluated and its value is sent back to the server. The expression is evaluated in a context where element refers to this element and event refers to the fired event. If multiple expressions are defined for the same event, their order of execution is undefined.

      The result of the evaluation is available in DomEvent.getEventData() with the expression as the key in the JSON object. An expression might be e.g.

      • element.value the get the value of an input element for a change event.
      • event.button === 0 to get true for click events triggered by the primary mouse button.
      Parameters:
      eventData - definition for data that should be passed back to the server together with the event, not null
      Returns:
      this registration, for chaining
      See Also:

    • setFilter

      DomListenerRegistration setFilter(String filter)
      Sets a JavaScript expression that is used for filtering events to this listener. When an event is fired in the browser, the expression is evaluated and an event is sent to the server only if the expression value is true-ish according to JavaScript type coercion rules. The expression is evaluated in a context where element refers to this element and event refers to the fired event.

      An expression might be e.g. event.button === 0 to only forward events triggered by the primary mouse button.

      Any previous filter for this registration is discarded.

      Parameters:
      filter - the JavaScript filter expression, or null to clear the filter
      Returns:
      this registration, for chaining

    • getFilter

      String getFilter()
      Gets the currently set filter expression.
      Returns:
      the current filter expression, or null if no filter is in use
      See Also:

    • setDisabledUpdateMode

      DomListenerRegistration setDisabledUpdateMode(DisabledUpdateMode disabledUpdateMode)
      Configure whether this listener will be called even in cases when the element is disabled.

      When used in combination with synchronizeProperty(String), the most permissive update mode for the same property will be effective. This means that there might be unexpected property updates for a disabled component if multiple parties independently configure different aspects for the same component. This is based on the assumption that if a property is explicitly safe to update for disabled components in one context, then the nature of that property is probably such that it's also safe to update in other contexts.

      Parameters:
      disabledUpdateMode - controls RPC communication from the client side to the server side when the element is disabled, not null
      Returns:
      this registration, for chaining

    • debounce

      DomListenerRegistration debounce(int timeout, DebouncePhase firstPhase, DebouncePhase... rest)
      Configures the debouncing phases for which this listener should be triggered. Debouncing is disabled and the set phases are ignored if timeout is set to 0 (the default).

      This methods overrides the settings previously set through debounce(int), throttle(int) or debounce(int, DebouncePhase, DebouncePhase...).

      The tested and supported combinations of phases are:

      DebouncePhase.TRAILING
      The server side is notified once after the event hasn't been triggered within the timeout. For example only the last keydown event is fired if a person continuously types without pauses longer than the timeout. This is the most commonly used mode. There is debounce(int) shorthand for this mode.
      DebouncePhase.LEADING
      In this case you only get notified of this event once right away on the server side. Other events of the same type will be ignored until the timeout has passed.
      DebouncePhase.LEADING + DebouncePhase.TRAILING
      This works like with the basic DebouncePhase.TRAILING, but in addition the first event of the burst gets reported rightaway. This is good if your want normal debouncing, but you are also interested to know if the user input has started.
      DebouncePhase.TIMEOUT
      In this case the listener is triggered only after the given timeout. If there are multiple events during that period, only the last one is reported.
      DebouncePhase.LEADING + DebouncePhase.TIMEOUT
      In this case the listener is triggered when an event burst starts, but afterwards only after the given timeout has passed. There is throttle(int) shorthand for this mode.

      In case another event in the UI triggers a "server roundtrip" from the client-side, events possibly queued by the debouncer are fired before that. Thus, events may occur before than expected. Also in the otherway around, due to the client-server nature of the web apps, events may arrive bit late. Do not expect debouncing to be perfectly deterministic!

      Also note that due to the client-side implementation, de-bounce settings are global for keys formed of "element-to-event-type-to-timeout". Behavior is unspecified if you configure multiple debouncing rules for the same event on the same element.

      Parameters:
      timeout - the debounce timeout in milliseconds, or 0 to disable debouncing
      firstPhase - the first phase to use. If you are interested about the first event in the burst, you should give DebouncePhase.TRAILING as a parameter here. Otherwise either DebouncePhase.TRAILING or DebouncePhase.INTERMEDIATE.
      rest - any remaining phases to use. In practice, only either DebouncePhase.TRAILING and DebouncePhase.INTERMEDIATE should be given here, if DebouncePhase.LEADING is given as a firstPhase.
      Returns:
      this registration, for chaining
      See Also:

    • debounce

      default DomListenerRegistration debounce(int timeout)
      Configures this listener to be notified only when at least timeout milliseconds has passed since the last time the event was triggered. This is useful for cases such as text input where it's only relevant to know the result once the user stops typing.

      This is a shorthand for debounce(int, DebouncePhase, DebouncePhase...) with only DebouncePhase.TRAILING specified. See debounce(int, DebouncePhase, DebouncePhase...) for complete documentation!

      Parameters:
      timeout - the debounce timeout in milliseconds, or 0 to disable debouncing
      Returns:
      this registration, for chaining

    • throttle

      default DomListenerRegistration throttle(int period)
      Configures this listener to not be notified more often than period milliseconds.

      Throttling is disabled if the period is set to 0.

      This is a shorthand for debounce(int, DebouncePhase, DebouncePhase...) with DebouncePhase.LEADING and DebouncePhase.INTERMEDIATE specified. See debounce(int, DebouncePhase, DebouncePhase...) for complete documentation!

      Parameters:
      period - the minimum period between listener invocations, or 0 to disable throttling
      Returns:
      this registration, for chaining

    • getDebounceTimeout

      default int getDebounceTimeout()
      Gets the debounce timeout that is configured by debounce or throttle.
      Returns:
      timeout in milliseconds, or 0 if debouncing is disabled
      See Also:

    • getDebouncePhases

      default Set<DebouncePhase> getDebouncePhases()
      Gets the debouncing phases for which this listener should be triggered.
      Returns:
      debounce phases
      See Also:

    • getEventType

      default String getEventType()
      Gets the event type that the listener is registered for.
      Returns:
      DOM event type of the listener

    • onUnregister

      default DomListenerRegistration onUnregister(SerializableRunnable unregisterHandler)
      Adds a handler that will be run when this registration is removed.
      Parameters:
      unregisterHandler - the handler to run when the registration is removed, not null
      Returns:
      this registration, for chaining
      Since:
      1.3

    • synchronizeProperty

      default DomListenerRegistration synchronizeProperty(String propertyName)
      Marks that the DOM event of this registration should trigger synchronization for the given property.
      Parameters:
      propertyName - the name of the property to synchronize, not null or ""
      Returns:
      this registration, for chaining

    • mapEventTargetElement

      default DomListenerRegistration mapEventTargetElement()
      Marks that the DOM event should map the event.target to the closest corresponding Element on the server side, to be returned by DomEvent.getEventTarget().
      Returns:
      this registration, for chaining
      Since:
      9.0

    • addEventDataElement

      default DomListenerRegistration addEventDataElement(String eventData)
      Add a JavaScript expression for extracting an element as event data. When an event is fired in the browser, the expression is evaluated and if it returns an element from DOM, the server side element or closest parent element is sent to server side. The expression is evaluated in a context where element refers to this element and event refers to the fired event. If multiple expressions are defined for the same event, their order of execution is undefined.

      The result of the evaluation is available in DomEvent.getEventDataElement(String) with the expression as the key in the JSON object.

      In case you want to get the event.target element to the server side, use the mapEventTargetElement() method to get it mapped and the DomEvent.getEventTarget() to fetch the element.

      Parameters:
      eventData - definition for element that should be passed back to the server together with the event, not null
      Returns:
      this registration, for chaining
      Since:
      9.0
      See Also:

    • stopPropagation

      default DomListenerRegistration stopPropagation()
      Stops propagation of the event to upper level DOM elements.

      When used with setFilter(String), stopPropagation will only be called when the filter condition is met. For example, if you set a filter for specific keys, stopPropagation will only apply to those keys.

      Returns:
      the DomListenerRegistration for further configuration
      See Also:

    • preventDefault

      default DomListenerRegistration preventDefault()
      Tries to prevent the default behavior of the event in the browser, such as shortcut action on key press or context menu on "right click". This might not be possible for some events.

      When used with setFilter(String), preventDefault will only be called when the filter condition is met. For example, if you set a filter for specific keys, preventDefault will only apply to those keys.

      Returns:
      the DomListenerRegistration for further configuration
      See Also:

    • addEventData

      default DomListenerRegistration addEventData(Class<?> type)
      Automatically adds event data expressions for all properties of the given class. This method uses Java Bean introspection to discover the properties of the class and adds event data expressions for each field path.

      This is particularly useful with Java records that mirror the JavaScript event structure. For example: 

       record MouseEventData(EventDetails event) {
     record EventDetails(int button, int clientX, int clientY) {
     }
 }

 element.addEventListener("click", e -> {
     MouseEventData data = e.getEventData(MouseEventData.class);
     System.out.println("Button: " + data.event().button());
 }).addEventData(MouseEventData.class);
      The above will automatically add event data expressions for event.button, event.clientX, event.clientY, and type.
      Parameters:
      type - the class whose properties should be captured from the event data, not null
      Returns:
      this registration, for chaining
      See Also:

    • addEventData

      default DomListenerRegistration addEventData(tools.jackson.core.type.TypeReference<?> typeReference)
      Automatically adds event data expressions for all properties of the type specified by the given type reference. This method uses Java Bean introspection to discover the properties and adds event data expressions for each field path.

      For generic types like List<MyBean>, this method will attempt to extract the raw class type for introspection.

      Parameters:
      typeReference - the type reference whose properties should be captured from the event data, not null
      Returns:
      this registration, for chaining
      See Also:

    • addEventDetail

      default DomListenerRegistration addEventDetail()
      Adds the event.detail property to the event data. This is a convenience method equivalent to addEventData("event.detail").

      The event.detail property is commonly used in custom events to pass event-specific data. The returned detail object can be retrieved on the server side using DomEvent.getEventDetail(Class) or DomEvent.getEventDetail(TypeReference).

      Example usage: 

       record RgbColor(int r, int g, int b) {
 }

 element.addEventListener("color-change", e -> {
     RgbColor newValue = e.getEventDetail(RgbColor.class);
     setModelValue(newValue, true);
 }).addEventDetail();
      Returns:
      this registration, for chaining
      See Also:

    • addEventDetail

      default DomListenerRegistration addEventDetail(Class<?> type)
      Adds specific properties from the event.detail object to the event data based on the given class structure. Only the properties defined in the class will be included, reducing data transfer.

      This method uses Java Bean introspection to discover the properties of the class and adds event data expressions for each property path within event.detail.

      Example usage: 

       record RgbColor(int r, int g, int b) {
 }

 element.addEventListener("color-change", e -> {
     RgbColor color = e.getEventDetail(RgbColor.class);
     setModelValue(color, true);
 }).addEventDetail(RgbColor.class);
      This will add expressions for event.detail.r, event.detail.g, and event.detail.b, rather than sending the entire event.detail object.
      Parameters:
      type - the class whose properties should be captured from event.detail, not null
      Returns:
      this registration, for chaining
      See Also:

    • allowInert

      DomListenerRegistration allowInert()
      Configures the event listener to bypass the server side security checks for modality. Handle with care! Can be ok when transferring data from "non-ui" component events through the Element API, like e.g. geolocation events.
      Returns:
      the DomListenerRegistration for further configuration