Documentation

You are viewing documentation for Vaadin 23. View latest documentation

Documentation

Embedded Application Properties

This section covers the following:

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

Source code
Java
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’s 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 can’t 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

This section covers 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.

Source code
Java
    @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'>.

Source code
HTML
<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 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.

Source code
Java
        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.

Source code
HTML
<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