Documentation

CHANGELOG.md

@@ -11,8 +11,8 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 - Add methods to modify the text node of an element:
 
-  - `Elements.textNode(elemental2.dom.Element, java.lang.String)`
-  - `Elements.textNode(org.jboss.elemento.IsElement<E>, java.lang.String)`
+  - `Elements.textNode(elemental2.dom.Element, String)`
+  - `Elements.textNode(IsElement<E>, String)`
 
 - Add overloaded methods to bind events in `HasElement`:
 
@@ -21,6 +21,14 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 - Add `Logger.isEnabled(Level)` to check if a level is enabled for a logger.
 
+### Changed
+
+- Add debug log statements logger to attach/detach implementation
+
+### Fixed
+
+- Fix multiple attach/detach handlers for an element.
+
 ## [1.5.0] - 2024-05-06
 
 ### Added

README.md

@@ -334,6 +334,12 @@ class TodoItemElement implements IsElement<HTMLElement>, Attachable {
 
 Elemento uses the [`MutationObserver`](https://developer.mozilla.org/docs/Web/API/MutationObserver) API to detect changes in the DOM tree and passes an [`MutationRecord`](https://developer.mozilla.org/en-US/docs/Web/API/MutationRecord) instance to the `attach(MutationRecord)` and `detach(MutationRecord)` methods. This instance contains additional information about the DOM manipulation.
 
+> [!IMPORTANT]
+> The `attach(MutationRecord)` and `detach(MutationRecord)` methods are only called **once** after the attachable implementation has been registered with `Attachable.register(HTMLElement, Attachable)`. If you hold a reference to the element, and the element is attached to the DOM again, the callbacks are not called again, unless the element has been registered again. This is done for reasons of optimisation and performance.
+
+> [!TIP]
+> If you want to be notified every time your custom element is attached to the DOM it is recommended to add the call to `Attachable.register(HTMLElement, Attachable)` in the constructor like in the example above and recreate the custom element.
+
 ## Iterators / Iterables / Streams
 
 Elemento provides several methods to iterate over node lists, child elements or elements returned by a selector. There are methods which return `Iterator`, `Iterable` and `Stream`.

core/src/main/java/org/jboss/elemento/Attachable.java

@@ -30,7 +30,7 @@
  * The {@link #attach(MutationRecord)} / {@link #detach(MutationRecord)} methods are only called <strong>once</strong> after the
  * attachable implementation has been registered with {@link #register(HTMLElement, Attachable)}. If you hold a reference to the
  * element, and the element is attached to the DOM again, the callbacks are not called again, unless the element has been
- * registered again.
+ * registered again. This is done for reasons of optimisation and performance.
  * <p>
  * {@snippet class = Greeting region = attach}
  */