> Markdown version of [Embedded Application Properties](https://vaadin.com/docs/v14/flow/integrations/embedding/tutorial-webcomponent-properties). Section index: [llms.txt](https://vaadin.com/docs/v14/flow/llms.txt)

# 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](https://vaadin.com/docs/v14/flow/integrations/embedding/tutorial-webcomponent-exporter.md) for a detailed example of how to create an embedded Vaadin application.

## <a id="defining-web-component-properties"></a>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.

```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 an example below in [Updating Properties on the Client Side](#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>)`.

### <a id="property-event-attributes"></a>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.

### <a id="addproperty-method-return-type"></a>`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.

## <a id="updating-properties-on-the-client-side"></a>Updating Properties on the Client Side

In this section we cover how the host environment (sever) 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](#firing-custom-events-on-the-client-side).

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.

```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 `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'>`.

```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 or not the person has reached adulthood, and updates `<span id="designator">` when this occurs.

## <a id="firing-custom-events-on-the-client-side"></a>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 `webComponent#fireEvent()` method to fire events for given parameters.

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

```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](https://developer.mozilla.org/en-US/docs/Web/API/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.

```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>
```

`915C594E-B04C-490C-B2EE-D6C8550A5572`
