Enabled State

Components that allow user interaction, such as TextField or Button, can have three different enabled states:

  • Enabled: An enabled component allows the user to interact with it. This is the default state.

  • Explicitly disabled: A component is explicitly disabled when setEnabled(false) is called directly on it. The user cannot interact with the component, and communication from the client to the server is blocked.

  • Implicitly disabled: A component is implicitly disabled when it is a child of a explicitly disabled container. The component behaves exactly like an explicitly disabled component, except it is automatically enabled again as soon as it detaches from the disabled container.

Explicitly Enabling and Disabling Components

Any component that implements the HasEnabled interface can be explicitly enabled or disabled.

Example: Disabling a component using the component.setEnabled method.

Java

  1. TextField name = new TextField("Name");
  2. name.setEnabled(false);

  • This disables the name field:

    • Users cannot interact with it, and

    • Events from the client to the server are blocked.

  • The server does not handle status updates from the component, even if the component is changed manually on the browser, for example by a client-side script or via a developer console.

Example: Disabling all components in a container by using the same API:

Java

  1. FormLayout form = new FormLayout();
  3. TextField name = new TextField("Name");
  4. TextField email = new TextField("E-mail");
  5. Button submit = new Button("Submit");
  7. form.add(name, email, submit);
  8. // all children are implicitly disabled
  9. form.setEnabled(false);
  10. System.out.println(name.isEnabled()); // prints false

Implicitly Enabled and Disabled Components

When an implicitly disabled component is detached from a disabled container, it is automatically enabled again. Similarly, if an enabled component is attached to a disabled container, it is automatically implicitly disabled.

Examples: Implicitly enabled and disabled components

Java

  1. FormLayout form = new FormLayout();
  2. form.setEnabled(false); // the entire form is disabled
  4. TextField name = new TextField("Name");
  5. // prints true, since it is not attached yet
  6. System.out.println(name.isEnabled());
  8. Button submit = new Button("Submit");
  9. // the submit button is explicitly disabled
  10. submit.setEnabled(false);
  11. System.out.println(submit.isEnabled()); // prints false
  13. form.add(name, submit); // attaches children
  15. System.out.println(name.isEnabled()); // prints false
  16. System.out.println(submit.isEnabled()); // prints false
  18. form.remove(name); // the name field gets detached
  19. System.out.println(name.isEnabled()); // prints true
  21. form.remove(submit); // the submit button gets detached
  23. // prints false, since it was explicitly disabled
  24. System.out.println(submit.isEnabled());

Overriding Default Disabled Behavior

By default, disabled components do not allow user interaction from the client side. However, it is sometimes necessary for complex (composite) components to remain partially functional, even in the disabled state. For example, you may want to only fully enable a registration form after a user selects a checkbox to accept a license agreement.

Enabling Property Changes

You can override the default disabled behavior by enabling certain RPC-client-side calls that would normally be blocked for disabled components.

The first way to do this is to use the synchronizeProperty method with the DisabledUpdateMode.ALWAYS argument value.

Example: This Polymer template component controls its own enabled state via the checkbox. The checkbox is never disabled, and it enables and disables the component.

Java

  1. @Tag("registration-form")
  2. @JsModule("./src/registration-form.js")
  3. public class RegistrationForm
  4.         extends PolymerTemplate<TemplateModel>
  5.         implements HasEnabled {
  7.     @Id
  8.     private TextField name;
  10.     @Id
  11.     private TextField email;
  13.     @Id
  14.     private Button submit;
  16.     @Id
  17.     private Element enable;
  19.     public RegistrationForm() {
  20.         enable.synchronizeProperty("checked",
  21.                 "checked-changed",
  22.                 DisabledUpdateMode.ALWAYS);
  23.         enable.addPropertyChangeListener("checked",
  24.                 this::handleEnabled);
  25.         setEnabled(false);
  26.     }
  28.     private void handleEnabled(
  29.             PropertyChangeEvent event) {
  30.         setEnabled((Boolean) event.getValue());
  31.     }
  33.     @EventHandler
  34.     private void register() {
  35.         String userName = name.getValue();
  36.         String userEmail = email.getValue();
  37.         System.out.println("Register user with name='"
  38.                 + userName
  39.                 + "' and email='" + userEmail + "'");
  40.     }
  41. }

Here is its template file:

js

  1. class RegistrationForm extends PolymerElement {
  3.     static get template() {
  4.         return html`
  5.             <vaadin-text-field id='name'>
  6.                 {{name}}
  7.             </vaadin-text-field>
  8.             <vaadin-text-field id='email'>
  9.                 {{email}}
  10.             </vaadin-text-field>
  11.             <vaadin-button id='submit'
  12.                 on-click='register'>
  13.                 Register
  14.             </vaadin-button>
  15.             <vaadin-checkbox id='enable'>
  16.                 Accept License Agreement
  17.             </vaadin-checkbox>`;
  18.     }
  20.     static get is() {
  21.         return 'registration-form';
  22.     }
  23. }
  25. customElements.define(RegistrationForm.is,
  26.         RegistrationForm);

  • The checkbox is implicitly disabled if the template (which is its parent) is disabled. As a result, no RPC is allowed for the checkbox.

  • The synchronizeProperty method (with extra arguments) is used to synchronize the checked property.

    • The argument, DisabledUpdateMode.ALWAYS, is an enum value that allows updates for this property, even if the element is disabled.

  • The folowing RPC communications are blocked for the disabled element:

    • Property changes.

    • DOM events.

    • Event handler methods (annotated with @EventHandler). For example, the register() method is an event handler method that is blocked when the component is disabled.

    • Client delegate methods (annotated with @ClientCallable).

As an alternative, you can use the @Synchronize annotation with the DisabledUpdateMode.ALWAYS argument value.

Example: Using the @Synchronize annotation for the property getter in your component.

Java

  1. @Synchronize(property = "prop", value = "prop-changed",
  2.              allowUpdates = DisabledUpdateMode.ALWAYS)
  3. public String getProp() {
  4.     return getElement().getProperty("prop");
  5. }

Enabling DOM Events

There are two ways to enable DOM events. You can use:

  1. An addEventListener overload method in the Element API, or

  2. The @DomEvent annotation.

Example: Unblocking a DOM event for a disabled element using the addEventListener overload method that accepts the DisabledUpdateMode.ALWAYS parameter.

Java

  1. public Notification() {
  2.     getElement().addEventListener("opened-changed",
  3.             event -> System.out.println("Opened"))
  4.       .setDisabledUpdateMode(DisabledUpdateMode.ALWAYS);
  5. }

Example: Unblocking a DOM event for a disabled component using the @DomEvent annotation with the parameter value allowUpdates = DisabledUpdateMode.ALWAYS ):

Java

  1. @DomEvent(value = "click",
  2.           allowUpdates = DisabledUpdateMode.ALWAYS)
  3. public class CustomEvent
  4.         extends ComponentEvent<Component> {
  5. }

Enabling Server-Handler Methods

If there are server-handler methods annotated with @ClientCallable or @EventHandler, you can unblock them for disabled components by specifying DisabledUpdateMode.ALWAYS as a value.

Example: Specifying DisabledUpdateMode.ALWAYS

Java

  1. @EventHandler(DisabledUpdateMode.ALWAYS)
  2. private void eventHandler() {
  3. }
  5. @ClientCallable(DisabledUpdateMode.ALWAYS)
  6. private void clientRequest() {
  7. }