Extending Components

You can create a new component by extending any existing component.

For most components, there is a client-side component and a corresponding server-side component:

  • Client-side component: Contains the HTML, CSS, and JavaScript, and defines a set of properties that determine the behavior of the component on the client side.

  • Server-side component: Contains Java code that allows for changing of the client-side properties, and manages the component behavior on the server side.

You can extend a component on either the server or client side. Note that these are alternative approaches that are mutually exclusive.

In this section we demonstrate the two different approaches to achieve the same changes to the prebuilt text field component.

Extending a Component Using the Server-side Approach

Extending a server-side component is useful when you want to add new functionality (as opposed to visual aspects) to an existing component. Suitable examples include automatically processing data, adding default validators, and combining multiple simple components into a field that manages complex data.

Tip
If your component contains a lot of logic that could easily be done on the client side, consider implementing it as a Web Component and creating a wrapper for it. This approach may offer a better user experience and result in less load on the server.

In this example, we create a NumericField component by extending the TextField component. The new component contains a default number that the user can change using + and - controls.

vaadin-numeric-field

Example: Creating a NumericField component by extending the TextField component.

Java

  1. @CssImport("./styles/numeric-field-styles.css")
  2. public class NumericField extends TextField {
  4.     private Button substractBtn;
  5.     private Button addBtn;
  7.     private static final int DEFAULT_VALUE = 0;
  8.     private static final int DEFAULT_INCREMENT = 1;
  10.     private int numericValue;
  11.     private int incrementValue;
  12.     private int decrementValue;
  14.     public NumericField() {
  15.         this(DEFAULT_VALUE, DEFAULT_INCREMENT,
  16.                 -DEFAULT_INCREMENT);
  17.     }
  19.     public NumericField(int value, int incrementValue,
  20.                         int decrementValue) {
  21.         setNumericValue(value);
  22.         this.incrementValue = incrementValue;
  23.         this.decrementValue = decrementValue;
  25.         setPattern("-?[0-9]*");
  26.         setPreventInvalidInput(true);
  28.         addChangeListener(event -> {
  29.             String text = event.getSource().getValue();
  30.             if (StringUtils.isNumeric(text)) {
  31.                 setNumericValue(Integer.parseInt(text));
  32.             } else {
  33.                 setNumericValue(DEFAULT_VALUE);
  34.             }
  35.         });
  37.         substractBtn = new Button("-", event -> {
  38.             setNumericValue(numericValue +
  39.                     decrementValue);
  40.         });
  42.         addBtn = new Button("+", event -> {
  43.             setNumericValue(numericValue +
  44.                     incrementValue);
  45.         });
  47.         getElement().setAttribute("theme", "numeric");
  48.         styleBtns();
  50.         addToPrefix(substractBtn);
  51.         addToSuffix(addBtn);
  52.     }
  54.     private void styleBtns() {
  55.         // Note: The same as addThemeVariants
  56.         substractBtn.getElement()
  57.                 .setAttribute("theme", "icon");
  58.         addBtn.getElement()
  59.                 .setAttribute("theme", "icon");
  60.     }
  62.     public void setNumericValue(int value) {
  63.         numericValue = value;
  64.         setValue(value + "");
  65.     }
  67.     // getters and setters
  68. }

As an alternative, you can extend the Composite class that has a minimal API. This hides methods available in the more extensive API that is exposed when your custom components extends an implementation of Component.

Note
The Element API contains methods to update and query various parts of the element, such as the attributes. Every component has a getElement() method that allows you to to access it. See Creating a Component Using Multiple Elements for more.

We import additional styles for the component using the @CssImport annotation. These styles apply only to our NumericField component, and not to all TextField components.

Example: Creating numeric-field-styles.css to customize the appearance of the vaadin-text-field component.

styles/numeric-field-styles.css

  1. :host([theme~="numeric"]) [part="input-field"] {
  2.     background-color: var(--lumo-base-color);
  3.     border: 1px solid var(--lumo-contrast-30pct);
  4.     box-sizing: border-box;
  5. }
  7. :host([theme~="numeric"]) [part="value"]{
  8.     text-align: center;
  9. }

See Styling Components for more information.

Extending a Component Using the Client-side Approach

Vaadin client-side components are based on Polymer 3 that supports extending existing components. You can use the extends property to extend existing Polymer elements.

There are five ways to inherit a template from another Polymer element:

  1. Inheriting a base class template without modifying it.

  2. Overriding a base class template in a child class.

  3. Modifying a copy of a superclass template.

  4. Extending a base class template in a child class.

  5. Providing template-extension points in a base class for content from a child class.

Extending by Modifying a Copy of a Superclass Template

In this example, we demonstrate how to create a new component by modifying a copy of a superclass template. We build a NumberFieldElement by extending Vaadin.TextFieldElement. The new component contains a default number that the user can change using + and - controls.

vaadin-number-field

It is important to remember that when a component template is extended, the properties and methods of the parent template become available to the child template.

Note
By default, a child component uses the template of the parent component, unless the child component provides its own template by overriding the static getter method template. The parent’s template is accessed using super.template.

Next, specify the element from which the child component inherits. In this case we specify that NumberFieldElement inherits (including the properties and methods) from Vaadin.TextFieldElement:

js

  1. import {html} from
  2.    '@polymer/polymer/lib/utils/html-tag.js';
  3. import {TextFieldElement} from
  4.    '@vaadin/vaadin-text-field/src/vaadin-text-field.js';
  6. let memoizedTemplate;
  8. class NumberFieldElement extends TextFieldElement {
  10.     static get template() {
  11.         if (!memoizedTemplate) {
  12.             const superTemplate = super.template
  13.                     .cloneNode(true);
  14.             const inputField = superTemplate.content
  15.                 .querySelector('[part="input-field"]');
  16.             const prefixSlot = superTemplate.content
  17.             .querySelector('[name="prefix"]');
  18.             const decreaseButton = html`<div
  19.                 part="decrease-button"
  20.                 on-click="_decreaseValue"></div>`;
  21.             const increaseButton = html`<div
  22.                 part="increase-button"
  23.                 on-click="_increaseValue"></div>`;
  24.             inputField.insertBefore(
  25.                 decreaseButton.content, prefixSlot);
  26.             inputField.appendChild(
  27.                 increaseButton.content);
  28.             memoizedTemplate = html`<style>
  29.                  [part="decrease-button"]::before {
  30.                    content: "−";
  31.                  }
  33.                  [part="increase-button"]::before {
  34.                    content: "+";
  35.                  }
  36.                </style>
  37.                ${superTemplate}`;
  38.         }
  39.         return memoizedTemplate;
  40.     }
  42.     static get is() {
  43.         return 'vaadin-number-field';
  44.     }
  46.     static get properties() {
  47.         return {
  48.             decrementValue: {
  49.               type: Number,
  50.               value: -1,
  51.               reflectToAttribue: true,
  52.               observer: '_decrementChanged'
  53.             },
  54.             incrementValue: {
  55.               type: Number,
  56.               value: 1,
  57.               reflectToAttribue: true,
  58.               observer: '_incrementChanged'
  59.             }
  61.             // Note: the value is stored in the
  62.             // TF's value property.
  63.         };
  64.     }
  66.     _decreaseValue() {
  67.         this.__add(this.decrementValue);
  68.     }
  70.     _increaseValue() {
  71.         this.__add(this.incrementValue);
  72.     }
  74.     __add(value) {
  75.         this.value = parseInt(this.value, 10) + value;
  76.         this.dispatchEvent(
  77.             new CustomEvent('change', {bubbles: true}));
  78.     }
  80.     _valueChanged(newVal, oldVal) {
  81.         this.value = this.focusElement.value;
  82.         super._valueChanged(this.value, oldVal);
  83.     }
  85.     /* ... */
  86. }

To modify the template we override the template static getter. Note that the expression ${super.template} inserts the base class template into the newly constructed template. The newly constructed template is memoized for further invocations of template.

See Inherit a template from another Polymer element in the Polymer documentation for more.