From 2856714835f18350284acb78cbd6124e47d51595 Mon Sep 17 00:00:00 2001 From: Lauren Alamo Date: Tue, 26 Aug 2025 16:25:18 -0400 Subject: [PATCH 1/6] feat: expanding events section for elementcomposite --- docs/docs/building-ui/element-composite.md | 81 ++++++++++++++++++++-- 1 file changed, 77 insertions(+), 4 deletions(-) diff --git a/docs/docs/building-ui/element-composite.md b/docs/docs/building-ui/element-composite.md index 2e9c35856..68022d7c3 100644 --- a/docs/docs/building-ui/element-composite.md +++ b/docs/docs/building-ui/element-composite.md @@ -1,6 +1,7 @@ --- -sidebar_position: 4 +sidebar_position: 1 title: Element Composite +sidebar_class_name: has-new-content slug: element_composite --- @@ -68,11 +69,13 @@ height='250px' ## Event registration {#event-registration} -Events are a crucial part of web components, allowing communication between different parts of an application. The `ElementComposite` class simplifies event registration and handling. To register an event listener, use the `addEventListener()` method to register event listeners for specific event types. Specify the event class, the listener, and optional event options. +Events enable communication between different parts of your webforJ application. The `ElementComposite` class provides event handling with support for debouncing, throttling, filtering, and custom event data collection. + +Register event listeners using the `addEventListener()` method: ```java // Example: Adding a click event listener -addEventListener(ClickEvent.class, event -> { +addEventListener(ElementClickEvent.class, event -> { // Handle the click event }); ``` @@ -81,13 +84,83 @@ addEventListener(ClickEvent.class, event -> { The `ElementComposite` events are different than `Element` events, in that this doesn't allow any class, but only specified `Event` classes. ::: -In the demonstration below, a click event has been created and then added to the QR code component. This event, when fired, will display the "X" coordinate of the mouse at the time of clicking the component, which is provided to the Java event as data. A method is then implemented to allow the user to access this data, which is how it is displayed in the application. +### Built-in event classes {#built-in-event-classes} + +webforJ provides pre-built event classes with typed data access: + +- **ElementClickEvent**: Mouse click events with coordinates (`getClientX()`, `getClientY()`), button information (`getButton()`), and modifier keys (`isCtrlKey()`, `isShiftKey()`, etc.) +- **ElementDefinedEvent**: Fired when a custom element is defined in the DOM and ready for use +- **ElementEvent**: Base event class providing access to raw event data, event type (`getType()`), and event ID (`getId()`) + +### Event payloads {#event-payloads} + +Events carry data from the client to your Java code. Access this data through `getData()` for raw event data or use typed methods when available on built-in event classes. For more details on efficiently using event payloads, see the [Events guide](../building-ui/events). + +## Custom event classes {#custom-event-classes} + +For specialized event handling, create custom event classes with configured payloads using `@EventName` and `@EventOptions` annotations: + +In the example below, a click event has been created and then added to the QR code component. This event, when fired, will display the "X" coordinate of the mouse at the time of clicking the component, which is provided to the Java event as data. A method is then implemented to allow the user to access this data, which is how it is displayed in the application. + +## ElementEventOptions {#elementeventoptions} + +`ElementEventOptions` lets you customize event behavior by configuring what data to collect, when events fire, and how they're processed. Here's a comprehensive code snippet showing all the configuration options: + +```java +ElementEventOptions options = new ElementEventOptions() + // Collect custom data from the client + .addData("query", "this.value") + .addData("timestamp", "Date.now()") + .addData("isValid", "this.checkValidity()") + + // Execute JavaScript before event fires + .setCode("this.classList.add('processing');") + + // Only fire if conditions are met + .setFilter("this.value.length >= 2") + + // Delay execution until user stops typing (300ms) + .setDebounce(300, DebouncePhase.TRAILING); + +addEventListener("input", this::handleSearch, options); +``` + +### Performance control {#performance-control} + +Control when and how often events fire: + +**Debouncing** - Delays execution until activity stops: + +```java +options.setDebounce(300, DebouncePhase.TRAILING); // Wait 300ms after last event +``` + +**Throttling** - Limits execution frequency: + +```java +options.setThrottle(100); // Fire at most once per 100ms +``` + +Available debounce phases: + +- `LEADING`: Fire immediately, then wait +- `TRAILING`: Wait for quiet period, then fire (default) +- `BOTH`: Fire immediately and after quiet period + +## Options merging {#options-merging} + +Combine event configurations from different sources using `mergeWith()`. Base options provide common data for all events, while specific options add specialized configuration. Later options override conflicting settings. + +```java +ElementEventOptions merged = baseOptions.mergeWith(specificOptions); +``` + ## Interacting with Slots {#interacting-with-slots} Web components often use slots to allow developers to define the structure of a component from the outside. A slot is a placeholder inside a web component that can be filled with content when using the component. In the context of the `ElementComposite` class, slots provide a way to customize the content within a component. The following methods are provided to allow developers to interact with and manipulate slots: From 56b6e4cd820af611bafd7b5e1c5d483a440f10bc Mon Sep 17 00:00:00 2001 From: Hyyan Abo Fakher Date: Tue, 23 Sep 2025 11:35:51 +0200 Subject: [PATCH 2/6] Update docs/docs/building-ui/element-composite.md Co-authored-by: Garrison Osteen <95929849+gosteenBASIS@users.noreply.github.com> --- docs/docs/building-ui/element-composite.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/building-ui/element-composite.md b/docs/docs/building-ui/element-composite.md index 68022d7c3..e59fbc1f1 100644 --- a/docs/docs/building-ui/element-composite.md +++ b/docs/docs/building-ui/element-composite.md @@ -69,7 +69,7 @@ height='250px' ## Event registration {#event-registration} -Events enable communication between different parts of your webforJ application. The `ElementComposite` class provides event handling with support for debouncing, throttling, filtering, and custom event data collection. +Events enable communication between different parts of your webforJ app. The `ElementComposite` class provides event handling with support for debouncing, throttling, filtering, and custom event data collection. Register event listeners using the `addEventListener()` method: From d145bebad5474d5b525618f2e4c546947e2ba3b2 Mon Sep 17 00:00:00 2001 From: Hyyan Abo Fakher Date: Tue, 23 Sep 2025 11:36:55 +0200 Subject: [PATCH 3/6] Update docs/docs/building-ui/element-composite.md Co-authored-by: Garrison Osteen <95929849+gosteenBASIS@users.noreply.github.com> --- docs/docs/building-ui/element-composite.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/building-ui/element-composite.md b/docs/docs/building-ui/element-composite.md index e59fbc1f1..e0b9d748b 100644 --- a/docs/docs/building-ui/element-composite.md +++ b/docs/docs/building-ui/element-composite.md @@ -98,7 +98,7 @@ Events carry data from the client to your Java code. Access this data through `g ## Custom event classes {#custom-event-classes} -For specialized event handling, create custom event classes with configured payloads using `@EventName` and `@EventOptions` annotations: +For specialized event handling, create custom event classes with configured payloads using `@EventName` and `@EventOptions` annotations. In the example below, a click event has been created and then added to the QR code component. This event, when fired, will display the "X" coordinate of the mouse at the time of clicking the component, which is provided to the Java event as data. A method is then implemented to allow the user to access this data, which is how it is displayed in the application. From 8be32390a30e27a3eb2b5c2afb33f72b2bd29c90 Mon Sep 17 00:00:00 2001 From: Hyyan Abo Fakher Date: Tue, 23 Sep 2025 11:38:44 +0200 Subject: [PATCH 4/6] Update docs/docs/building-ui/element-composite.md Co-authored-by: Garrison Osteen <95929849+gosteenBASIS@users.noreply.github.com> --- docs/docs/building-ui/element-composite.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/building-ui/element-composite.md b/docs/docs/building-ui/element-composite.md index e0b9d748b..6ea32ff78 100644 --- a/docs/docs/building-ui/element-composite.md +++ b/docs/docs/building-ui/element-composite.md @@ -135,7 +135,7 @@ addEventListener("input", this::handleSearch, options); Control when and how often events fire: -**Debouncing** - Delays execution until activity stops: +**Debouncing** delays execution until activity stops: ```java options.setDebounce(300, DebouncePhase.TRAILING); // Wait 300ms after last event From be6399e49faf162c9c588e5c0a26dbe14c996dbc Mon Sep 17 00:00:00 2001 From: Hyyan Abo Fakher Date: Tue, 23 Sep 2025 11:38:52 +0200 Subject: [PATCH 5/6] Update docs/docs/building-ui/element-composite.md Co-authored-by: Garrison Osteen <95929849+gosteenBASIS@users.noreply.github.com> --- docs/docs/building-ui/element-composite.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/building-ui/element-composite.md b/docs/docs/building-ui/element-composite.md index 6ea32ff78..275149e6b 100644 --- a/docs/docs/building-ui/element-composite.md +++ b/docs/docs/building-ui/element-composite.md @@ -141,7 +141,7 @@ Control when and how often events fire: options.setDebounce(300, DebouncePhase.TRAILING); // Wait 300ms after last event ``` -**Throttling** - Limits execution frequency: +**Throttling** limits execution frequency: ```java options.setThrottle(100); // Fire at most once per 100ms From 7642e222c7141727272ca490788a55a5127e9f3d Mon Sep 17 00:00:00 2001 From: Hyyan Abo Fakher Date: Tue, 23 Sep 2025 11:42:22 +0200 Subject: [PATCH 6/6] minor tweaks --- docs/docs/building-ui/element-composite.md | 28 +++++++++++----------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/docs/building-ui/element-composite.md b/docs/docs/building-ui/element-composite.md index 275149e6b..d97ea8af4 100644 --- a/docs/docs/building-ui/element-composite.md +++ b/docs/docs/building-ui/element-composite.md @@ -8,15 +8,15 @@ slug: element_composite -The `ElementComposite` class serves as a versatile foundation for managing composite elements in webforJ applications. Its primary purpose is to facilitate the interaction with HTML elements, represented by the `Element` class, by providing a structured approach to handle properties, attributes, and event listeners. It allows for implementation and reuse of elements in an application. Use the `ElementComposite` class when implementing Web Components for use in webforJ applications. +The `ElementComposite` class serves as a versatile foundation for managing composite elements in webforJ applications. Its primary purpose is to facilitate the interaction with HTML elements, represented by the `Element` class, by providing a structured approach to handle properties, attributes, and event listeners. It allows for implementation and reuse of elements in an app. Use the `ElementComposite` class when implementing Web Components for use in webforJ applications. While using the `ElementComposite` class, using the `getElement()` method will give you access to the underlying `Element` component. Similarly, the `getNodeName()` method gives you the name of that node in the DOM. :::tip -It is possible to do everything with the `Element` class itself, without using `ElementComposite` class. However, the provided methods in the `ElementComposite` give users a way to reuse the work that's being done. +it's possible to do everything with the `Element` class itself, without using `ElementComposite` class. However, the provided methods in the `ElementComposite` give users a way to reuse the work that's being done. ::: -Throughout this guide, we'll be implementing the [Shoelace QR code web component](https://shoelace.style/components/qr-code) using the `ElementComposite` class. +This guide demonstrates how to implement the [Shoelace QR code web component](https://shoelace.style/components/qr-code) using the `ElementComposite` class. property, V value)` sets a property to a specified value. @@ -44,12 +44,12 @@ set(TITLE, "My Title"); set(VALUE, "My Value"); ``` -In addition to setting a property, utilize the `get()` method in the `ElementComposite` class to access and read properties. The `get()` method can be passed an optional `boolean` value, which is false by default, to dictate whether the method should make a trip to the client to retrieve the value. This impacts performance, but might be necessary if the property can be modified purely in the client. +In addition to setting a property, use the `get()` method in the `ElementComposite` class to access and read properties. The `get()` method can be passed an optional `boolean` value, which is false by default, to dictate whether the method should make a trip to the client to retrieve the value. This impacts performance, but might be necessary if the property can be modified purely in the client. A `Type` can also be passed to the method, which dictates what to cast retrieved result to. :::tip -This `Type` is not overtly necessary, and adds an extra layer of specification as the data is retrieved. +This `Type` isn't overtly necessary, and adds an extra layer of specification as the data is retrieved. ::: ```java @@ -100,7 +100,7 @@ Events carry data from the client to your Java code. Access this data through `g For specialized event handling, create custom event classes with configured payloads using `@EventName` and `@EventOptions` annotations. -In the example below, a click event has been created and then added to the QR code component. This event, when fired, will display the "X" coordinate of the mouse at the time of clicking the component, which is provided to the Java event as data. A method is then implemented to allow the user to access this data, which is how it is displayed in the application. +In the example below, a click event has been created and then added to the QR code component. This event, when fired, will display the "X" coordinate of the mouse at the time of clicking the component, which is provided to the Java event as data. A method is then implemented to allow the user to access this data, which is how it's displayed in the app. -## ElementEventOptions {#elementeventoptions} +## `ElementEventOptions` {#elementeventoptions} `ElementEventOptions` lets you customize event behavior by configuring what data to collect, when events fire, and how they're processed. Here's a comprehensive code snippet showing all the configuration options: ```java ElementEventOptions options = new ElementEventOptions() // Collect custom data from the client - .addData("query", "this.value") + .addData("query", "component.value") .addData("timestamp", "Date.now()") - .addData("isValid", "this.checkValidity()") + .addData("isValid", "component.checkValidity()") // Execute JavaScript before event fires - .setCode("this.classList.add('processing');") + .setCode("component.classList.add('processing');") // Only fire if conditions are met - .setFilter("this.value.length >= 2") + .setFilter("component.value.length >= 2") // Delay execution until user stops typing (300ms) .setDebounce(300, DebouncePhase.TRAILING); @@ -161,7 +161,7 @@ Combine event configurations from different sources using `mergeWith()`. Base op ElementEventOptions merged = baseOptions.mergeWith(specificOptions); ``` -## Interacting with Slots {#interacting-with-slots} +## Interacting with slots {#interacting-with-slots} Web components often use slots to allow developers to define the structure of a component from the outside. A slot is a placeholder inside a web component that can be filled with content when using the component. In the context of the `ElementComposite` class, slots provide a way to customize the content within a component. The following methods are provided to allow developers to interact with and manipulate slots: @@ -171,6 +171,6 @@ Web components often use slots to allow developers to define the structure of a 3. **`getFirstComponentInSlot()`**: This method is designed to fetch the first component assigned to the slot. Optionally pass a specific class type to filter the results of this method. -It is also possible to use the `add()` method with a `String` parameter to specify the desired slot in which to add the passed component. +it's also possible to use the `add()` method with a `String` parameter to specify the desired slot in which to add the passed component. These interactions allow developers to harness the power of web components by providing a clean and straightforward API for manipulating slots, properties, and handling events within the `ElementComposite` class. \ No newline at end of file