Embedded Application Properties

In this section, we cover:

How to define web component properties for embedded Vaadin applications.
How to handle property changes on the server side.
How to fire custom events on the client side.

See Creating an Embedded Application Tutorial for a detailed example of how to create an embedded Vaadin application.

Defining Web Component Properties

The WebComponentExporter class defines the properties that are exposed by the WebComponent public API.

Calling WebComponentDefinition`addProperty()# defines a property and adds it to the public API of the web component. The supported types are `Integer, Double, Boolean, String, and JsonValue.

Example: Using the addProperty() method to define web component properties.

public class PersonExporter
        extends WebComponentExporter<PersonComponent> {
    private PropertyConfiguration<PersonComponent,
              Boolean> isAdultProperty;

    public PersonExporter() {
        super("person-display");
        addProperty("name", "John Doe")
                .onChange(PersonComponent::setName);
        addProperty("age", 0)
                .onChange(PersonComponent::setAge);

        isAdultProperty = addProperty("is-adult",
                false);
    }

This example defines three properties: name, age, and is-adult. (The is-adult property is used in a later example in Updating Properties on the Client Side.)
The name property type is a String, and the age property type is an Integer.
The default values serve a dual purpose: they define the property type and set the default value. If no default value is provided, you need to define the type explicitly by calling definition.addProperty(String, Class<?extends Serializable>).

Property Event Attributes

Adding a property exposes a fluent API that you can use to configure the property.

Properties have two event attributes:

.onChange():
- registers a callback that is called when the value of the property changes on the client side;
- accepts the parameter, SerializableBiConsumer<C, P>, where C is the type of the Component being exported and P is the type of the property. The component’s associated setter method is a conventional choice.
.readOnly():
- sets the property to read-only mode; the value of the property cannot be changed on the client side.

addProperty() Method Return Type

The addProperty() method returns a PropertyConfiguration<C, P> object that provides the fluent API for configuring the property.

If you need to refer to the property later, you can use the received PropertyDefinition to identify the property in question.

Updating Properties on the Client Side

In this section, we cover how the host environment (server) communicates with the client, and explain how to update client-side property values from the server.

To update client-side property values, you need:

a reference to the web component that contains the exported component, and
a reference to the instance of the exported component itself.

You can implement the abstract configureInstance() method to update properties and fire client-side events.

The configureInstance() method receives references to WebComponent<PersonComponent> and PersonComponent, where PersonComponent is the exported component. WebComponent is used to communicate with the client side.

Example: Updating the is-adult boolean property when the age property changes in the PersonComponent instance.

    @Override
    protected void configureInstance(
            WebComponent<PersonComponent> webComponent,
            PersonComponent component) {
        component.setAdultAge(18); // initialization

        component.addAgeChangedListener(event -> {
            webComponent.setProperty(isAdultProperty,
                    component.isAdult());
        });

The WebComponent`setProperty()# method updates the property identified by the [classname]`PropertyConfiguration to the new value.

Note	The `configureInstance()` method can also be used to do further initialization on the `component` instance.

Now that the is-adult property is configured to update on the client side, the next step is to access and leverage this property.

Example: Embedding the person-display component in a web page and updating <span id='designator'>.

<person-display id="person" age=15></person-display>
<span id="designator">is a child</span>

<script>
    function updateDesignator() {
        var personComponent = document
                .querySelector("#person");
        if (personComponent["is-adult"]) {
            document.querySelector("#designator")
                    .innerText = "is an adult!";
        } else {
            setTimeout(updateDesignator, 1000);
        }
    }

    updateDesignator();
</script>

The script checks periodically whether or not the person has reached adulthood, and updates <span id="designator"> when this occurs.

Firing Custom Events on the Client Side

A WebComponent instance can also be used to fire custom events on the client side.

You can use the [methodname]`webComponent`fireEvent()# method to fire events for given parameters.

Example: Using the webComponent`fireEvent()# method to fire the `"retirement-age-reached" event.

        component.addAgeChangedListener(event -> {
            if (event.getAge() > 65) {
                webComponent.fireEvent(
                        "retirement-age-reached");
            }
        });
    }
}

This example uses custom logic and a custom event; if a person’s age reaches 66 or more, an event of type "retirement-age-reached" is fired on the client side.

The fireEvent() method has three variants:

fireEvent(String)
fireEvent(String, JsonValue)
fireEvent(String, JsonValue, EventOptions)

The parameters are:

String: the name or type of the event;
JsonValue: a custom JSON object set as the value of the detail key in the client-side event;
EventOptions: to configure the bubbles, cancelable, and composed event options.

See CustomEvent in the MDN documentation for more information about these parameters.

The final step is to update the <span> tag with the event results.

Example: updating <span id="designator"> with the "retirement-age-reached" event result.

<person-display id="person" age=15></person-display>
<span id="designator">is a child</span>

<script>
    var personComponent = document
            .querySelector("#person");

    personComponent.addEventListener(
            "retirement-age-reached", function(event) {
        document.querySelector("#designator")
                .innerText = "is allowed to retire!";
    });
</script>

B05162A1-925B-49C2-8550-E1FC8CDCC19D

Documentation