Documentation

You are viewing documentation for Vaadin 23. View latest documentation

Documentation

Creating a Java API for a Web Component

While there are many ways to interact with a Web Component, the most typical are:

  • Use properties on the element to define how it should behave.

  • Listen to events on the element to be notified when the user does something.

  • Call functions on the element to perform specific tasks, for example to open a popup.

  • Add sub-elements to define child content.

The component class included with the Vaadin Add-on Starter, for example PaperSlider.java, is only a stub that handles the imports (see Integrating a Web Component for more). This section demonstrates how to add functionality to the included stub class to transform it into a functioning Java API.

Setting and Reading Properties

You can typically find the properties that an element supports in its JavaScript documentation on npm. See the <paper-slider> documentation, for example. The paper-slider has a boolean property named pin that defines whether a numeric-value label displays when the slider thumb is pressed.

You can add getters and setters to match any property to create a corresponding Java setter-getter API for the property.

Example: Adding a setter and getter for the pin property in the PaperSlider class.

public void setPin(boolean pin) {
    getElement().setProperty("pin", pin);
}
public boolean isPin() {
    return getElement().getProperty("pin", false);
}

  • The setter sets the given property to the requested value.

  • The getter returns the property value, or false as the default value, if the property hasn’t been set. The default value should match the default of the Web Component property.

When you set the pin to true (by updating the setter in the DemoView class), the pin appears when the slider thumb is pressed.

Example: Calling setPin(true) in the DemoView class.

public DemoView() {
    PaperSlider paperSlider = new PaperSlider();
    paperSlider.setPin(true);
    add(paperSlider);
}

One disadvantage of writing the getElement() methods directly is that you have to repeat the property name in the getter and the setter. You can avoid this by using the PropertyDescriptor helper. This helper, and the factory methods in PropertyDescriptors, allow you to define the property as a single static field in the component and reference it from the getter and the setter.

Example: Using the PropertyDescriptor helper and propertyWithDefault() factory method on the pin property.

public class PaperSlider extends AbstractSinglePropertyField<PaperSlider, Integer> {

    private static final PropertyDescriptor<Boolean, Boolean> pinProperty = PropertyDescriptors.propertyWithDefault("pin", false);

    public void setPin(boolean pin) {
        pinProperty.set(this, pin);
    }

    public boolean isPin() {
        return pinProperty.get(this);
    }
}

  • The pinProperty descriptor defines:

    • a property with the name pin and a default value of false (matches the Web Component);

    • both a setter and getter of type Boolean through generics (<Boolean, Boolean>).

  • The setter and getter code only invokes the descriptor with the component instance.

Synchronizing the Value

The paper-slider component allows the user to input a single value. To make it work automatically as a field, this kind of component should implement the HasValue interface. See Binding Data to Forms for more.

You need the value to be synchronized automatically from the client to the server when the user changes it, as well as from the server to the client when it’s updated programmatically. In addition, a value-change event should be fired on the server whenever the value changes.

In the common use case in which the getValue() method is based on a single-element property, the AbstractSinglePropertyField base class takes care of everything related to the value.

Example: Extending the AbstractSinglePropertyField base class in the PaperSlider class.

public class PaperSlider extends AbstractSinglePropertyField<PaperSlider, Integer> {

    public PaperSlider() {
        super("value", 0, false);
    }

}

  • The type parameters define the component type (PaperSlider) returned by the getSource() method in value change events, and the value type (Integer).

  • The constructor parameters define:

    • the name of the element property that contains the value ("value");

    • the default value to use if the property isn’t set (0);

    • whether setValue(null) should be allowed or throw an exception (false means that null isn’t allowed).

For more advanced cases that are still based on a one-element property, there is an alternative constructor that defines callbacks that convert between the low-level element property type and the high-level getValue() type. In cases where the value can’t be derived based on a single-element property, you can use the more generic AbstractField base class. You can test this in the DemoView class.

Example: Testing the use of the alternative constructor in the DemoView class.

public DemoView() {
    PaperSlider paperSlider = new PaperSlider();
    paperSlider.setPin(true);
    paperSlider.addValueChangeListener(e -> {
        String message = "The value is now " + e.getValue();
        if (e.isFromClient()) {
            message += " (set by the user)";
        }
        Notification.show(message, 3000, Position.MIDDLE);
    });
    add(paperSlider);

    Button incrementButton = new Button("Increment using setValue", e -> {
        paperSlider.setValue(paperSlider.getValue() + 5);
    });
    add(incrementButton);
}
Note
Properties not related to the HasValue interface
For some Web Components, you need to update other properties that aren’t related to the HasValue interface. See Creating A Simple Component Using the Element API for how to use the @Synchronize annotation to synchronize property values without automatically firing a value-change event.

Listening to Events

All web elements fire a click event when the user clicks them. To allow the user of your component to listen to the click event, you can extend ComponentEvent and use the @DomEvent and @EventData annotations.

Example: Extending ComponentEvent and using the @DomEvent and @EventData annotations in the ClickEvent class.

@DomEvent("click")
public class ClickEvent extends ComponentEvent<PaperSlider> {

    private int x, y;

    public ClickEvent(PaperSlider source,
                      boolean fromClient,
                      @EventData("event.offsetX") int x,
                      @EventData("event.offsetY") int y) {
        super(source, fromClient);
        this.x = x;
        this.y = y;
    }

    public int getX() {
        return x;
    }

    public int getY() {
        return y;
    }

}

  • ClickEvent uses the @DomEvent annotation to define the name of the DOM event to listen for (click in this case).

  • Like all other events fired by a Component, it extends ComponentEvent, which provides a typed getSource() method.

  • It uses two additional constructor parameters annotated with @EventData to get the click coordinates from the browser.

  • The expression inside each @EventData annotation is evaluated when the event is handled in the browser. It accesses DOM event properties using the event. prefix (for example event.offsetX) and element properties using the element. prefix.

Note
Constructor parameter requirements
The two first parameters of a ComponentEvent constructor must be PaperSlider source, boolean fromClient and these are filled automatically. All parameters following these two initial parameters must be annotated with @EventData.

You can now use the ClickEvent class as an argument when invoking the addListener() method on your PaperSlider component.

Example: Using the ClickEvent class in the addListener() method.

public Registration addClickListener(ComponentEventListener<ClickEvent> listener) {
    return addListener(ClickEvent.class, listener);
}

  • The addListener() method in the superclass sets up everything related to the event, based on the annotations in the ClickEvent class.

You can test the integration in the DemoView class.

Example: Testing the event integration in the DemoView class.

paperSlider.addClickListener(e -> {
    Notification.show("Clicked at " + e.getX() + "," + e.getY(), 1000, Position.BOTTOM_START);
});
Tip
Use the Vaadin-provided ClickEvent for production
The click event was used here for illustrative purposes. In a real use case, you should use the ClickEvent provided by Vaadin instead. This also provides additional event details.
Tip
Controlling propagation behavior
As the event data expression is evaluated as JavaScript, you can control propagation behavior using @EventData("event.preventDefault()") String ignored, for example. This is a workaround when there is no other API to control this behavior.

Calling Element Functions

In addition to properties and events, many elements offer methods that can be invoked for different reasons. For example vaadin-board has a refresh() method that’s called whenever a change is made that the Web Component itself isn’t able to detect automatically. To call a function on an element, you can use the callJsFunction() method in Element as a way of providing an API.

Example: Using the callJsFunction() method in the PaperSlider class to call the increment function on the paper-slider element.

public void increment() {
    getElement().callJsFunction("increment");
}

You can test this in the DemoView class.

Example: Using incrementJSButton in the DemoView class.

Button incrementJSButton = new Button("Increment using JS", e -> {
    paperSlider.increment();
});
add(incrementJSButton);

If you do this, and also add the value-change listener (described above), you get a notification with the new value after clicking the button. The notification also tells that the user changed the value. This is because isFromClient() checks that the change originates from the browser (rather than the server), but doesn’t differentiate between a user changing the value and a change resulting from a JavaScript call.

Note
increment() is typically called directly or from server-side logic
The example above is for demonstration purposes only and is somewhat artificial, in that it shows a server visit from a button click to call a JavaScript method on another element on client side. In practice, you would either call increment() directly from the client side, or from some other server-side business logic.
Tip
callJsFunction() parameters and return value
In addition to the method name, callJsFunction() accepts an arbitrary number of parameters of supported types. Current supported types are String, Boolean, Integer, Double, and the corresponding primitive types, JsonValue, and Element and Component references. It also returns a server-side promise for the JavaScript function’s return value. See the available methods in the Javadoc for more.

Paper-Slider Integration Result

After you have completed the steps previously described, your PaperSlider class should be similar to the example below.

Example: Java API provided by the PaperSlider class.

@Tag("paper-slider")
@NpmPackage(value = "@polymer/paper-slider", version = "3.0.1")
@JsModule("@polymer/paper-slider/paper-slider.js")
public class PaperSlider extends AbstractSinglePropertyField<PaperSlider, Integer> {

    private static final PropertyDescriptor<Boolean, Boolean> pinProperty = PropertyDescriptors.propertyWithDefault("pin", false);

    public PaperSlider() {
        super("value", 0, false);
    }

    public void setPin(boolean pin) {
        pinProperty.set(this, pin);
    }

    public boolean isPin() {
        return pinProperty.get(this);
    }

    public Registration addClickListener(ComponentEventListener<ClickEvent> listener) {
        return addListener(ClickEvent.class, listener);
    }

    public void increment() {
        getElement().callJsFunction("increment");
    }
    @DomEvent("click")
    public static class ClickEvent extends ComponentEvent<PaperSlider> {

        private int x, y;

        public ClickEvent(PaperSlider source,
                          boolean fromClient,
                          @EventData("event.offsetX") int x,
                          @EventData("event.offsetY") int y) {
            super(source, fromClient);
            this.x = x;
            this.y = y;
        }

        public int getX() {
            return x;
        }

        public int getY() {
            return y;
        }

    }
}

You can extend this class further to support additional configuration properties, for example min and max.

Adding Sub-elements to Define Child Content

Some Web Components can contain child elements. If the component is a layout type and you only want to add child components, implementing the HasComponents interface should be enough. This interface provides default implementations for the add(Component…​), remove(Component…) and removeAll() methods.

Example: Implementing HasComponents to implement your own <div> wrapper.

@Tag(Tag.DIV)
public class Div extends Component implements HasComponents {
}

You can then add and remove components using the provided methods.

Example: Using add() methods provided by the HasComponents interface.

Div root = new Div();
root.add(new Span("Hello"));
root.add(new Span("World"));
add(root);

If you don’t want to provide a public add/remove API, you have two options: use the Element API or create a new Component to encapsulate the internal element behavior.

As an example, assume you want to create a specialized Vaadin button that can only show a VaadinIcon.

Example: Using the available VaadinIcon enum (that lists the icons in the set).

@Tag("vaadin-button")
@NpmPackage(value = "@vaadin/button", version = "23.5.0")
@JsModule("@vaadin/button/vaadin-button.js")
public class IconButton extends Component {

    private VaadinIcon icon;

    public IconButton(VaadinIcon icon) {
        setIcon(icon);
    }

    public void setIcon(VaadinIcon icon) {
        this.icon = icon;

        Component iconComponent = icon.create();
        getElement().removeAllChildren();
        getElement().appendChild(iconComponent.getElement());
    }

    public void addClickListener(
            ComponentEventListener<ClickEvent<IconButton>> listener) {
        addListener(ClickEvent.class, (ComponentEventListener) listener);
    }

    public VaadinIcon getIcon() {
        return icon;
    }
}

  • The relevant part here is in the setIcon() method. VaadinIcon happens to include a feature that creates a component for a given icon (the create() call) that’s used here to create the child element.

  • After creating the element, all that’s necessary is to attach the root element of the child component by calling getElement().appendChild(iconComponent.getElement()).

If the VaadinIcon.create() method wasn’t available, you would need to either create the component yourself or use the Element API directly.

Example: Using the Element API to define the setIcon() method.

public void setIcon(VaadinIcon icon) {
    this.icon = icon;
    getElement().removeAllChildren();

    Element iconElement = new Element("vaadin-icon");
    iconElement.setAttribute("icon", "vaadin:" + icon.name().toLowerCase().replace("_", "-"));
    getElement().appendChild(iconElement);
}

  • The first part is the same as the previous example. However, in the second part, the element with the correct tag name, <vaadin-icon>, is created manually. The icon attribute is set to the correct value (as defined in @vaadin/icons/vaadin-iconset.js, for example icon="vaadin:check" for VaadinIcon.CHECK).

  • After creation, the element is attached to the <vaadin-button> element, after removing any previous content.

When using the second approach, you must also ensure that the vaadin-button.js dependency is loaded, otherwise it’s handled by the Icon component class.

Example: Importing vaadin-button.js, vaadin-iconset.js and vaadin-icon.js.

@NpmPackage(value = "@vaadin/button", version = "23.5.0")
@JsModule("@vaadin/button")
@NpmPackage(value = "@vaadin/icons", version = "23.5.0")
@JsModule("@vaadin/icons/vaadin-iconset.js")
@NpmPackage(value = "@vaadin/icon", version = "23.5.0")
@JsModule("@vaadin/icon")
public class IconButton extends Component {

You can test either approach in the DemoView class.

Example: Testing the icon button sub-element in the DemoView class.

IconButton iconButton = new IconButton(VaadinIcon.CHECK);
iconButton.addClickListener(e -> {
    int next = (iconButton.getIcon().ordinal() + 1) % VaadinIcon.values().length;
    iconButton.setIcon(VaadinIcon.values()[next]);
});
add(iconButton);

  • This shows the CHECK icon and then changes the icon on every click of the button.

Note
 You could extend Button directly (instead of Component), but you would then also inherit the entire public Button API.

AACDBA11-3ECD-4E3B-9A36-C64E3963C26C