Creating a Simple Component Using the Element API

There are multiple ways you can create a component. This tutorial uses the Element API and a single DOM element. For other component tutorials, see:

• Creating a Component Based on Many Elements

• Creating a Component Using Existing Components

• Creating a Component Which Can Contain Other Components

• Creating a Simple Component Using the Template API

You can create a simple TextField component based on an <input> element as follows:

Java

@Tag("input")
public class TextField extends Component {
  public TextField(String value) {
    getElement().setProperty("value",value);
  }
}

The Component class will automatically create its root element based on the @Tag annotation, which can then be accessed using getElement(). The root element in the text field is in this example used to set the initial value of the field.

To make the component easier to use, you can add an API for getting and setting the value:

Java

  @Synchronize("change")
  public String getValue() {
    return getElement().getProperty("value");
  }
  public void setValue(String value) {
    getElement().setProperty("value", value);
  }

To make the framework send property changes from the browser to the server, an @Synchronize annotation is added to the getter. The annotation defines the name of DOM event which triggers synchronization, i.e. in this case a change event from the input element will cause the updated value property (deduced from the getter name) to be sent to the server.

Component Enabled

The setEnabled method will be available for any component implementing the HasEnabled interface (which comes also with HasValue, HasComponents and Focusable).

By default disabling the component will add a disabled property to the client element, but this can be modified by overriding Component:onEnabledStateChanged(boolean) method.

For instance if the component requires a custom disabled marking and that its items get updated the override could be created as:

Java

@Override
public void onEnabledStateChanged(boolean enabled) {
    setDisabled(!enabled);
    refreshButtons();
}