added new sections to the element-composite article. #429

EHandtkeBasis · 2025-07-17T12:26:54Z

github-actions · 2025-07-17T12:27:10Z

docs/docs/building-ui/element-composite.md

 :::

-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.
+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 app.


📝 [vale] _{reported by reviewdog 🐶}
[Google.Contractions] Use 'it's' instead of 'it is'.

MatthewHawkins · 2025-07-21T13:25:35Z

docs/docs/building-ui/element-composite.md


-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 apps. 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 apps.


This needs a rework to be more meaningful with less filler

docs/docs/building-ui/element-composite.md

MatthewHawkins · 2025-07-21T13:28:42Z

docs/docs/building-ui/element-composite.md

 ## 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 are a crucial part of web components, allowing communication between different parts of an app. 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.


I feel this sentence could use a bit of a rewrite to say more with fewer words.

MatthewHawkins

Might need to handle any conflicts, but otherwise looks good!

bbrennanbasis · 2025-08-25T17:50:58Z

docs/docs/building-ui/element-composite.md

+
+## `ElementCompositeContainer` for components with slots
+
+For components that need to manage child components in named slots (such as headers, footers, or content areas), extend <JavadocLink type="foundation" location="com/webforj/component/element/ElementCompositeContainer" code='true' >ElementCompositeContainer</JavadocLink> instead of `ElementComposite`.


Suggested change

For components that need to manage child components in named slots (such as headers, footers, or content areas), extend <JavadocLink type="foundation" location="com/webforj/component/element/ElementCompositeContainer" code='true' >ElementCompositeContainer</JavadocLink> instead of `ElementComposite`.

For web components that have slots (such as headers, footers, or content areas), extend <JavadocLink type="foundation" location="com/webforj/component/element/ElementCompositeContainer" code='true' >ElementCompositeContainer</JavadocLink> instead of `ElementComposite` to manage the child components within the named slots.

bbrennanbasis

@EHandtkeBasis I've made some edits, and left some suggestions for the ElementCompositeContainer section.

bbrennanbasis · 2025-08-25T17:59:12Z

docs/docs/building-ui/element-composite.md

+## 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:

-1. **`findComponentSlot()`**: This method is used to search for a specific component across all slots in a component system. It returns the name of the slot where the component is located. If the component is not found in any slot, an empty string is returned.
+1. **`findComponentSlot()`**: This method is used to search for a specific component across all slots in a component system. It returns the name of the slot where the component is located. If the component isn't found in any slot, an empty string is returned.

 2. **`getComponentsInSlot()`**: This method retrieves the list of components assigned to a given slot in a component system. Optionally, pass a specific class type to filter the results of the method.

 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.


If you're suppose to use the ElementCompositeContainer class for components with slots, does this section need to be updated to reference ElementCompositeContainer instead of ElementComposite?

bbrennanbasis · 2025-08-25T18:01:14Z

docs/docs/building-ui/element-composite.md

+
+## `ElementCompositeContainer` for components with slots
+
+For components that need to manage child components in named slots (such as headers, footers, or content areas), extend <JavadocLink type="foundation" location="com/webforj/component/element/ElementCompositeContainer" code='true' >ElementCompositeContainer</JavadocLink> instead of `ElementComposite`.
+
+`ElementCompositeContainer` provides a structured way to add, remove, and manage components in specific slots:
+
+```java
+@NodeName("my-container")
+public final class MyContainer extends ElementCompositeContainer
+    implements HasClassName<MyContainer>, HasStyle<MyContainer> {
+    private static final String HEADER_SLOT = "header";
+    private static final String CONTENT_SLOT = "content";
+    private static final String FOOTER_SLOT = "footer";
+
+    public MyContainer() {
+        super();
+    }
+
+    public MyContainer addToHeader(Component... components) {
+        getElement().add(HEADER_SLOT, components);
+        return this;
+    }
+
+    public MyContainer addToContent(Component... components) {
+        add(components); // Default slot
+        return this;
+    }
+
+    public MyContainer addToFooter(Component... components) {
+        getElement().add(FOOTER_SLOT, components);
+        return this;
+    }
+}
+```
+
+Use `ElementCompositeContainer` whenever your component needs to support multiple content areas or slots, such as layouts, dialogs, or toolbars.


Suggestion:
Move this section to later in the article, right before Interacting with slots. If this section won't be moved, include a link/reference to Interacting with slots.

hyyan · 2025-10-07T08:19:11Z

@EHandtkeBasis Fix conflicts please

hyyan

@EHandtkeBasis In general, this is a good start. But it still feels patched together and a bit rushed. I would expect to read this document and learn everything I need to start working with ElementComposite. Right now, that is not the case. The content does not follow a logical order and the sections do not build on each other yet.

hyyan · 2025-10-27T13:51:35Z

docs/docs/building-ui/element-composite.md

+The `ElementComposite` class provides a structured base for building reusable web components in webforJ. It allows you to easily define properties, attributes, and event listeners of the underlying HTML elements in a type-safe, maintainable way. Use `ElementComposite` to encapsulate and integrate custom elements or third-party web components within your app.
+

 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. 


This section seems a bit out of place.

hyyan · 2025-10-27T13:51:56Z

docs/docs/building-ui/element-composite.md

 :::

-This guide demonstrates how to implement the [Shoelace QR code web component](https://shoelace.style/components/qr-code) using the `ElementComposite` class.
+:::info


This tip seems out of place too.

hyyan · 2025-10-27T13:53:37Z

docs/docs/building-ui/element-composite.md

+- **@StyleSheet**: Loads external CSS files for your component:
+
+  ```java
+  @StyleSheet(url = "https://cdn.example.com/library.css")


The url param is not supported , it should be value

hyyan · 2025-10-27T13:56:26Z

docs/docs/building-ui/element-composite.md

 />

+## Concern Interfaces
+


This also doesn't feel like a logical next learning step. The concern interfaces should probably be a separate article, because they apply to building UI in webforJ in general, not specifically to ElementComposite.

hyyan · 2025-10-27T14:00:30Z

docs/docs/building-ui/element-composite.md

+String title = get(TITLE, false, String.class);
+```
+
+### Best practices for validating properties


remove it please

hyyan · 2025-10-27T14:03:11Z

docs/docs/building-ui/element-composite.md

+```
+This approach helps prevent an invalid state.
+
+### Enum-style properties


Why are you only explaining enum properties and not other object property types and how they are converted? There should be a dedicated section that goes in depth on both basic and complex types, such as enums, maps, and lists and explains how webforJ serializes them when sending data to the client, and how it deserializes the values on the way back.

hyyan · 2025-10-27T14:05:35Z

docs/docs/building-ui/element-composite.md

 height='250px'
 />

 ## Event registration {#event-registration}


This section feels a bit shallow. There is a lot more you can explain here. For example, you haven't covered how to create custom events for your components or how to wrap them in classes or how to deal with payloads..

hyyan · 2025-10-27T14:08:54Z

docs/docs/building-ui/element-composite.md

+The `ElementComposite` events are different from `Element` events, in that this doesn't allow any class, but only specified `Event` classes.
 :::

 ### Built-in event classes {#built-in-event-classes}


This section doesn't really add much value

ElementDefinedEvent is internal, it cannot be used directly anyway

hyyan · 2025-10-27T14:11:40Z

docs/docs/building-ui/element-composite.md

 ElementEventOptions merged = baseOptions.mergeWith(specificOptions);
 ```

 ## Interacting with slots {#interacting-with-slots}


This section needs a bit more explanation about what slots are. You can refer to the MDN documentation for more details.

hyyan · 2025-10-27T14:13:00Z

docs/docs/building-ui/element-composite.md

+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.
+```java


This sample doesn't add much value. Can we come up with something runnable and more useful?

added new sections to the element-composite article.

8ec595f

EHandtkeBasis requested review from MatthewHawkins, bbrennanbasis, hyyan, mschned and nmlynx as code owners July 17, 2025 12:26

This was linked to issues Jul 17, 2025

Add Annotations, Interfaces, and ElementCompositeContainer sections to ElementComposite article #376

Open

Add information about Property and Attribute Management with PropertyDescriptor #378

Open

github-actions bot reviewed Jul 17, 2025

View reviewed changes

Removed vale issues.

4ca234b

hyyan assigned MatthewHawkins and bbrennanbasis Jul 21, 2025

MatthewHawkins requested changes Jul 21, 2025

View reviewed changes

EHandtkeBasis added 2 commits July 30, 2025 15:12

Merge branch 'main' into element-composite-clean

7aa6d00

Addressed feedback.

7323641

EHandtkeBasis requested a review from MatthewHawkins July 30, 2025 13:18

hyyan added this to the 25.03 milestone Aug 4, 2025

MatthewHawkins previously approved these changes Aug 25, 2025

View reviewed changes

chore: Revision edits to PR #429

ea26f06

bbrennanbasis reviewed Aug 25, 2025

View reviewed changes

bbrennanbasis requested changes Aug 25, 2025

View reviewed changes

bbrennanbasis mentioned this pull request Aug 26, 2025

feat: expanding events section for elementcomposite #514

Merged

hyyan removed this from the 25.03 milestone Aug 27, 2025

EHandtkeBasis self-assigned this Sep 4, 2025

EHandtkeBasis added 2 commits September 4, 2025 10:49

Merge branch 'main' into element-composite-clean

9a96c92

Adjusted according to feedback with the rebased version.

e1d8d3f

EHandtkeBasis requested a review from bbrennanbasis September 4, 2025 09:12

Merge branch 'main' into element-composite-clean

f1a25c0

EHandtkeBasis requested a review from gosteenBASIS as a code owner October 8, 2025 07:07

EHandtkeBasis dismissed MatthewHawkins’s stale review via f1a25c0 October 10, 2025 12:04

hyyan added the status: waiting-for-review The PR is ready. Waiting for team members to review. label Oct 27, 2025

hyyan requested changes Oct 27, 2025

View reviewed changes

hyyan added status: waiting-for-author Review is done. Waiting for the PR author to apply changes or respond. and removed status: waiting-for-review The PR is ready. Waiting for team members to review. labels Oct 27, 2025


		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 apps. 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 apps.


		## `ElementCompositeContainer` for components with slots

		For components that need to manage child components in named slots (such as headers, footers, or content areas), extend <JavadocLink type="foundation" location="com/webforj/component/element/ElementCompositeContainer" code='true' >ElementCompositeContainer</JavadocLink> instead of `ElementComposite`.

	For components that need to manage child components in named slots (such as headers, footers, or content areas), extend <JavadocLink type="foundation" location="com/webforj/component/element/ElementCompositeContainer" code='true' >ElementCompositeContainer</JavadocLink> instead of `ElementComposite`.
	For web components that have slots (such as headers, footers, or content areas), extend <JavadocLink type="foundation" location="com/webforj/component/element/ElementCompositeContainer" code='true' >ElementCompositeContainer</JavadocLink> instead of `ElementComposite` to manage the child components within the named slots.

		The `ElementComposite` class provides a structured base for building reusable web components in webforJ. It allows you to easily define properties, attributes, and event listeners of the underlying HTML elements in a type-safe, maintainable way. Use `ElementComposite` to encapsulate and integrate custom elements or third-party web components within your app.


		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.

Uh oh!

added new sections to the element-composite article. #429

Are you sure you want to change the base?

added new sections to the element-composite article. #429

Uh oh!

Conversation

EHandtkeBasis commented Jul 17, 2025

Uh oh!

github-actions bot Jul 17, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MatthewHawkins left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bbrennanbasis left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hyyan commented Oct 7, 2025

Uh oh!

hyyan left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants