Package com.vaadin.flow.component

Class AbstractField<C extends AbstractField<C,T>,T>

java.lang.Object
com.vaadin.flow.component.Component
com.vaadin.flow.component.AbstractField<C,T>
Type Parameters:
C - the source type for value change events
T - the value type
All Implemented Interfaces:
AttachNotifier, DetachNotifier, HasElement, HasEnabled, HasStyle, HasValue<AbstractField.ComponentValueChangeEvent<C,T>,T>, HasValueAndElement<AbstractField.ComponentValueChangeEvent<C,T>,T>, Serializable
Direct Known Subclasses:
AbstractSinglePropertyField, CustomField
public abstract class AbstractField<C extends AbstractField<C,T>,T> extends Component implements HasValueAndElement<AbstractField.ComponentValueChangeEvent<C,T>,T>
An abstract implementation of a field, or a Component allowing user input. Implements HasValue to represent the input value. Examples of typical field components include text fields, date pickers, and check boxes.

The field value is represented in two separate ways:

  1. A presentation value that is shown to the user. This is typically represented in the component's server-side DOM element or through child components.
  2. A model value that is available for programmatic use through the HasValue interface. This representation is handled by this class and should not be directly accessed by subclasses.

In order to keep the two value representations in sync with each other, subclasses must take care of the two following things:

  1. Listen to changes from the user, and call setModelValue(Object, boolean) with an updated value.
  2. Implement setPresentationValue(Object) to update the presentation value of the component so that the new value is shown to the user.
See the detailed documentation for the two methods for further details.

This class extends Component, which means that it cannot be used for adding field functionality to an existing component without changing the superclass of that component. As an alternative, you can use AbstractCompositeField to instead wrap an instance of the existing component.

Since:
1.0
Author:
Vaadin Ltd
See Also:

  • Constructor Details

    • AbstractField

      public AbstractField(T defaultValue)
      Creates a new field with an element created based on the Tag annotation of the sub class. The provided default value is used by getEmptyValue() and as the initial model value of this instance.
      Parameters:
      defaultValue - the default value for fields of this type

    • AbstractField

      public AbstractField(Element element, T defaultValue)
      Creates a new field with the given element instance. he provided default value is used by getEmptyValue() and as the initial model value of this instance.
      Parameters:
      element - the root element for the component
      defaultValue - the default value for fields of this type

  • Method Details

    • addValueChangeListener

      public Registration addValueChangeListener(HasValue.ValueChangeListener<? super AbstractField.ComponentValueChangeEvent<C,T>> listener)
      Description copied from interface: HasValue
      Adds a value change listener. The listener is called when the value of this HasValue is changed either by the user or programmatically.
      Specified by:
      addValueChangeListener in interface HasValue<C extends AbstractField<C,T>,T>
      Parameters:
      listener - the value change listener, not null
      Returns:
      a registration for the listener

    • setValue

      public void setValue(T value)
      Description copied from interface: HasValue
      Sets the value of this object. If the new value is not equal to getValue(), fires a value change event. May throw IllegalArgumentException if the value is not acceptable.

      Implementation note: the implementing class should document whether null values are accepted or not, and override HasValue.getEmptyValue() if the empty value is not null.

      Specified by:
      setValue in interface HasValue<C extends AbstractField<C,T>,T>
      Parameters:
      value - the new value

    • setPresentationValue

      protected abstract void setPresentationValue(T newPresentationValue)
      Updates the presentation of this field to display the provided value. Subclasses should override this method to show the value to the user. This is typically done by setting an element property or by applying changes to child components.

      If setModelValue(Object, boolean) is called from within this method, the value of the last invocation will be used as the model value instead of the value passed to this method. In this case setPresentationValue(Object) will not be called again. Changing the provided value might be useful if the provided value is sanitized.

      See AbstractField for an overall description on the difference between model values and presentation values.

      Parameters:
      newPresentationValue - the new value to show

    • setModelValue

      protected void setModelValue(T newModelValue, boolean fromClient)
      Updates the model value if the value has actually changed. Subclasses should call this method whenever the user has changed the value. A value change event is fired if the new value is different from the previous value according to valueEquals(Object, Object).

      If the value is from the client-side and this field is in readonly mode, then the new model value will be ignored. setPresentationValue(Object) will be called with the previous model value so that the representation shown to the user can be reverted.

      See AbstractField for an overall description on the difference between model values and presentation values.

      Parameters:
      newModelValue - the new internal value to use
      fromClient - true if the new value originates from the client; otherwise false

    • valueEquals

      protected boolean valueEquals(T value1, T value2)
      Compares to value instances to each other to determine whether they are equal. Equality is used to determine whether to update internal state and fire an event when setValue(Object) or setModelValue(Object, boolean) is called. Subclasses can override this method to define an alternative comparison method instead of Object.equals(Object).
      Parameters:
      value1 - the first instance
      value2 - the second instance
      Returns:
      true if the instances are equal; otherwise false

    • isEmpty

      public boolean isEmpty()
      Description copied from interface: HasValue
      Returns whether this HasValue is considered to be empty.

      By default this is an equality check between current value and empty value.

      Specified by:
      isEmpty in interface HasValue<C extends AbstractField<C,T>,T>
      Returns:
      true if considered empty; false if not

    • getValue

      public T getValue()
      Description copied from interface: HasValue
      Returns the current value of this object.

      Implementation note: the implementing class should document whether null values may be returned or not, and override HasValue.getEmptyValue() if the empty value is not null.

      Specified by:
      getValue in interface HasValue<C extends AbstractField<C,T>,T>
      Returns:
      the current value

    • getEmptyValue

      public T getEmptyValue()
      Description copied from interface: HasValue
      Returns the value that represents an empty value.

      By default HasValue is expected to support null as empty values. Specific implementations might not support this.

      Specified by:
      getEmptyValue in interface HasValue<C extends AbstractField<C,T>,T>
      Returns:
      empty value

    • bindValue

      public void bindValue(Signal<T> valueSignal, SerializableConsumer<T> writeCallback)
      Description copied from interface: HasValue
      Binds a Signal's value to the value state of this component and keeps the state synchronized with the signal value while the element is in attached state. When the element is in detached state, signal value changes have no effect.

      While a Signal is bound to a value state, any attempt to bind a new Signal while one is already bound throws BindingActiveException.

      While a Signal is bound to a value state and the element is in attached state, setting the value with HasValue.setValue(Object) or when a change originates from the client will invoke the write callback to propagate the value back. After the callback, the signal is re-consulted via Signal.peek() and if its value differs from what was being set, the new value is ignored and the signal's updated value is used instead, i.e. in cases where write callback has `signal.set("different")`, whereas a value being set is "a new value", the "different" value wins.

      If the write callback is null, the binding is read-only and any attempt to set the value while the element is attached will throw an IllegalStateException.

      Examples of usage: 

       // Simple binding to a signal holding the component value
 ValueSignal<String> signal = new ValueSignal<>("");
 Input component = new Input();
 add(component);
 component.bindValue(signal, signal::set);
 signal.set("Hello"); // The input's value changes

 // Binding to a property of an immutable record using updater helper
 record Person(String name, int age) {
     Person withName(String name) {
         return new Person(name, this.age);
     }
 }
 ValueSignal<Person> personSignal = new ValueSignal<>(
         new Person("Alice", 30));
 component.bindValue(personSignal.map(Person::name),
         personSignal.updater(Person::withName));

 // Binding to a property of a mutable bean using modifier helper
 class Person {
     private String name;

     public String getName() {
         return name;
     }

     public void setName(String name) {
         this.name = name;
     }
 }
 ValueSignal<Person> personSignal = new ValueSignal<>(new Person());
 component.bindValue(personSignal.map(Person::getName),
         personSignal.modifier(Person::setName));
      Specified by:
      bindValue in interface HasValue<C extends AbstractField<C,T>,T>
      Parameters:
      valueSignal - the signal to bind, not null
      writeCallback - the callback to propagate value changes back, or null for a read-only binding
      See Also: