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). In this section, we demonstrate 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 documentation, for example. The paper-slider has a boolean property named pin that defines whether or not 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 PaperSlider class.

Java

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 has not 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.

Java

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.

Java

public class PaperSlider extends Component {
    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 in Binding Data to Forms for more.

We 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 is 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.

Java

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), and whether setValue(null) should be allowed or throw an exception (false means that null is not 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 cannot 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.

Java

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);
}

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.

Java

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

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.

Java

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.

Java

paperSlider.addClickListener(e -> {
    Notification.show("Clicked at " + e.getX() + "," + e.getY(), 1000, Position.BOTTOM_START);
});

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 is called whenever a change is made that the Web Component itself is not 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.

Java

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

You can test this in the DemoView class.

Example: Using incrementJSButton in the DemoView class.

Java

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 indicates that the user changed the value. This is because isFromClient checks that the change originates from the browser (as opposed to from the server), but does not differentiate between a user changing the value and a change resulting from a JavaScript call.

Paper-slider Integration Result

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

Example: Java API provided by the PaperSlider class.

Java

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

Java

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

Java

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

If you do not 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).

Java

@Tag("vaadin-button")
@NpmPackage(value = "@vaadin/vaadin-button", version = "2.1.5")
@JsModule("@vaadin/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 is used here to create the child element.

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

If the VaadinIcon.create() method was not 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.

Java

public void setIcon(VaadinIcon icon) {
    this.icon = icon;
    getElement().removeAllChildren();
    Element iconElement = new Element("iron-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, <iron-icon>, is created manually and the icon attribute is set to the correct value (as defined in vaadin-icons.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 is handled by the Icon component class.

Example: Importing both the vaadin-button and vaadin-icons Web Components.

Java

@NpmPackage(value = "@vaadin/vaadin-button", version = "2.1.5")
@JsModule("@vaadin/vaadin-button/vaadin-button.js")
@NpmPackage(value = "@vaadin/vaadin-icons", version = "4.3.1")
@JsModule("@vaadin/vaadin-icons/vaadin-icons.js")
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.

Java

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.