` root element
`LabeledTextField.java`
```java
package com.vaadin.demo.reference.componentinternals.basics;
import com.vaadin.flow.component.Component;
import com.vaadin.flow.component.Tag;
import com.vaadin.flow.dom.Element;
@Tag("div")
public class LabeledTextField extends Component {
private final Element labelElement = new Element("label");
private final Element inputElement = new Element("input");
public LabeledTextField() {
getElement().appendChild(labelElement, inputElement);
}
}
```
This generates the following DOM-tree structure in the browser:
```html
```
###
Extending a Component
If you extend an existing component, the root element is inherited from the parent component class. You can still use the Element API to manipulate the root element or create and append child elements. However, you don’t need to use the `@Tag` annotation in this case.
Example 3. Extending the `LabeledTextField` component created above
`CustomTextField.java`
```java
package com.vaadin.demo.reference.componentinternals.basics;
import com.vaadin.flow.dom.Element;
public class CustomTextField extends LabeledTextField {
private final Element errorElement = new Element("span");
public CustomTextField() {
super();
getElement().appendChild(errorElement);
}
}
```
This generates the following DOM-tree structure in the browser:
```html
```
###
Composite Components
When you create a new component by combining existing components, you should extend the `Composite
` class, where `T` is the type of the root component. This does not affect the DOM structure, but prevents users of your component from accessing the API of the root component directly.
Example 4. Creating a `CompositeTextField` component with `Input` and `NativeLabel` components inside a `Div` root component
`CompositeTextField.java`
```java
package com.vaadin.demo.reference.componentinternals.basics;
import com.vaadin.flow.component.Composite;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.html.Input;
import com.vaadin.flow.component.html.NativeLabel;
public class CompositeTextField extends Composite {
private final NativeLabel label;
private final Input input;
public CompositeTextField(String labelText, String value) {
label = new NativeLabel();
label.setText(labelText);
input = new Input();
input.setValue(value);
// Users of CompositeTextField can't access the div directly since
// getContent() is protected.
var div = getContent();
div.add(label, input);
}
// Declare public API here.
}
```
This generates the following DOM-tree structure in the browser:
```html
```
##
Creating a Java API
The Element API provides low-level access to the client-side element. You typically want to create a higher-level Java API that hides these details from the users of your component.
A Vaadin component API consists of:
- Properties for accessing and setting values. This is covered in the [Component Properties](https://vaadin.com/docs/latest/flow/component-internals/properties.md) reference guide.
- Events and event listeners for reacting to user actions. This is covered in the [Declaring and Firing Component Events](https://vaadin.com/docs/latest/flow/component-internals/events.md) reference guide.
- Other methods that act on the component. Some of them may use the Element API to call JavaScript functions on the client side. This is covered in the [Remote Procedure Calls](https://vaadin.com/docs/latest/flow/component-internals/client-server-rpc.md) reference guide.
Example 5. An API for getting and setting the `value` property, and reacting to value changes
`TextField.java`
```java
@Synchronize("change")
public String getValue() {
return getElement().getProperty("value");
}
public void setValue(String value) {
getElement().setProperty("value", value);
fireEvent(new ChangeEvent(this, false));
}
public Registration addValueChangeListener(
ComponentEventListener
listener) {
return addListener(ChangeEvent.class, listener);
}
```
## eventHandler = this::onCartSummaryUpdate;
@Override
protected void onAttach(AttachEvent attachEvent) {
// This assumes the session already contains a ShopEventBus
var eventBus = attachEvent.getSession()
.getAttribute(ShopEventBus.class);
eventBus.register(eventHandler);
}
@Override
protected void onDetach(DetachEvent detachEvent) {
var eventBus = detachEvent.getSession()
.getAttribute(ShopEventBus.class);
eventBus.unregister(eventHandler);
}
private void onCartSummaryUpdate(EventObject event) {
// update cart summary ...
}
}
interface ShopEventBus {
void register(Consumer eventHandler);
void unregister(Consumer eventHandler);
}
```
You can also use the `Component.addDetachListener()` method to register a detach listener instead of overriding the `onDetach()` method. The listener is invoked after the `onDetach()` method. This is useful when you want to add detach behavior to an existing component without creating a subclass.
### handler = this::onCartSummaryUpdate;
eventBus.register(handler);
return () -> eventBus.unregister(handler);
});
}
private void onCartSummaryUpdate(EventObject event) {
// update cart summary ...
}
}
```
Because the cleanup closes over the local variables of the handler, no field is needed to carry state from an attach to the matching detach. The handler receives the `UI` the component was attached to, and it can return `null` when there is nothing to clean up.
Removing the returned registration removes the handler and also runs any cleanup still pending from the latest attach. An exception thrown by the handler is propagated to the caller, whereas one thrown by the cleanup is passed to the session error handler, so that a failing cleanup does not prevent the rest of the detach handling from running.
The same method is available on the element level as `Element.whenAttached()`. Both are public, so they can also be used from the outside to hook into the life cycle of another component.
##