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.
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
, andis-adult
. (Theis-adult
property is used in a later example in Updating Properties on the Client Side.) -
The
name
property type is aString
, and theage
property type is anInteger
. -
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>
, whereC
is the type of theComponent
being exported andP
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.
-
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.
@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 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 ortype
of the event; -
JsonValue
: a custom JSON object set as the value of thedetail
key in the client-side event; -
EventOptions
: to configure thebubbles
,cancelable
, andcomposed
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