SuperFields

Localised number fields, positionable labels, form generator, collection/map field, server-side text selection, date pickers with date pattern, configurable select components (tabs, GridSelect and ItemGrid), multi-click button, a LazyLoad, a ComponentObserver and even an UnloadListener. Plus fluid API, good JavaDocs and general Java-friendliness.

View larger

Close

View larger

Close

View larger

Close

View larger

Close

View larger

Close

Now in Maven Central

From version 0.18.0 SuperFields work with Java 17 and Vaadin 24.

From version 0.16.0 onwards all new releases for Vaadin 23+ are available in Maven Central.

From version 0.17.0-vaadin14 all new releases for Vaadin 14 are also available in Maven Central.

Use group id pl.unforgiven and artifact id superfields.

Demo app

Demo application of the latest release can be found at https://demo.unforgiven.pl/superfields.

Source code for the app and for the components can be found at https://github.com/vaadin-miki/super-fields/.

SuperFields

All SuperFields are Java-friendly. There is as little client-side code as possible ;) In addition to that, any client-side code is considered implementation detail and may change at any time.

Fluid API

All SuperFields feature fluid API (or method chaining), at least to some extent. For example, instead of doing:

  SuperDatePicker datePicker = new SuperDatePicker();
  datePicker.setId("super-date-picker");
  datePicker.setValue(LocalDate.today());

you can do a magic one-liner: new SuperDatePicker().withId("super-date-picker").withValue(LocalDate.today()).

Text selection

Some components contain server-side methods to control text selection in their web component part. In addition, they can optionally listen to text-selection events happening in the browser and broadcast them to the server.

The web components listen to each key press and mouse click. If text selection changes as a result of that action, they send an event to the server-side component. This may happen quite often and increase server load, so the feature is turned off by default. To turn it on simply call setReceivingSelectionEventsFromClient(true) (or withReceivingSelectionEventsFromClient(true)).

Label position

Most of the components that can have a label allow positioning said label through setLabelPosition(...) (or withLabelPosition(...)). This should work in most layouts, with FormLayout being an obvious exception. Not all components support all possible values of LabelPosition (SuperCheckbox ignores vertical alignment). In addition, things might work weird when using right-to-left languages - if that happens, please report the problem in GitHub.

Log messages

Quite a few components log their state using SLF4J. Critical information is logged as error or warning, debugging messages are, well, debug or trace. Information about how to configure which log messages get displayed can be found e.g. on Stack Overflow.

Number fields

None of the number fields support range checking, so if you allow too many digits, overflows will occur.

All number fields support text selection API.

SuperDoubleField and SuperBigDecimalField

An input field for entering localised Double and BigDecimal numbers. Supports thousands (grouping) separators for the integer part and optional decimal separator.

Both fields allow the integer part of the number to be optional (thus omitted and defaulted to zero - .27 parsed as 0.27). This feature is turned off by default (meaning the integer part is required).

In addition to that SuperBigDecimalField supports (optionally) entering numbers with scientific notation, e.g. 12.34e-1.

SuperIntegerField and SuperLongField

An input field for entering localised Integer and Long numbers. Supports thousands (grouping) separators.

Text fields

SuperTextField and SuperTextArea

These are the same components as their Vaadin counterparts, except they fully support text selection API. This means that the text contained in the components can be selected from server-side code and that changes to selection in the browser are sent to the server as events.

In addition to that, both components allow server-side initiated text change at caret position (or any selected range).

Date fields

SuperDatePicker and SuperDateTimePicker

Fully localised DatePicker and DateTimePicker that fetch month names and weekday names from Java Locale. Those settings can be overwritten by resource bundle named superdatepickeri18n.

In addition to the above, both components allow setting custom date display pattern. This pattern should survive setting locale or i18n object, so keep that in mind.

Please note: Vaadin's DatePicker and DateTimePicker allow setting custom date display patterns since version 14.8. It is achieved through DatePickerI18n.setDateFormat. That method executes in SuperDatePickerI18n, but it logs a warning message. If you intend to set formatting through i18n, please use default Vaadin's components.

Both components behave funky when changing locale at runtime if their calendars were already shown. That is mostly due to some weird caching on the client side and is also a Vaadin bug.

Please note: only SuperDatePicker has support for text selection API.

CollectionField, MapField and related helpers

CollectionField

Almost out-of-the-box, fully configurable CustomField for data of type List<X> (or Set<X>). Supports custom layouts, fields, removing individual or all elements and adding at specified indices.

To help navigate around functional interfaces CollectionComponentProviders contains some common use cases, like buttons for removing, clearing or adding elements. Please check the demo app (CollectionFieldProvider) for an example.

HasIndex and IndexedButton

While intended to work with CollectionField, here is a general interface for anything that needs an index (an integer number). IndexedButton does nothing by itself, but it is a Button that implements HasIndex. It is used e.g. to represent a button that removes an element from a collection.

MapField and MapEntryField

MapField is a customisable CustomField for data of type Map<K, V>. It is based on CollectionField and works with any field capable of displaying value of type Map.Entry<K, V>.

MapEntryField is a component that is a CustomField for Map.Entry<K, V>. It allows custom layout and dedicated components for keys and values of the map.

HasHeader, HasFooter and layout helpers

A three-part layout, with header, content and footer, is quite common in UX design. Two helper classes are offered:

• HeaderFooterFieldWrapper - a fully functional CustomField that has a header and a footer, and the content is just the field;
• HeaderFooterLayoutWrapper - a fully functional layout (HasComponents) that has a header and a footer, and the content is a layout to which HasComponents method calls are delegated.

Both wrappers attempt to be API-transparent and can replace already existing layouts or fields (for example, replacing a SuperTextField with a HeaderFooterFieldWrapper should just result in a header and footer around the text field, and no other changes should be needed).

Other fields

LabelField

This is an always read-only field. Basically, it is a CustomField that uses a Text to display String representation of the value. It is possible to customise how that representation is created and what text to show when the value is null. Note that the readonlyness of this component applies only to the UI.

VariantField

A CustomField<Object>. It checks the type of the value passed to it and attempts to display it using a known mapping to a field (e.g. by registering SuperIntegerField and SuperDatePicker it will be able to show integers and dates). No events or details - other than value change - are propagated or exposed from the inner field.

ObjectField

A CustomField<T> capable of building components and matching them with object's properties. Once configured it is basically an automated form generator. This component is highly configurable and details on how to use it are present in the project's wiki.

In most common cases one would use ObjectFieldFactory to create and configure ObjectField, and then annotate data model class with the additional information. Please consult the demo application or the tests (ObjectFieldTest, NestedObjectFieldTest and EnumObjectTest) for details. Also please note that ObjectFieldFactory will become a separate library at some point in the future.

SuperCheckbox

It is known that Checkbox does not support read-only mode. This component exists as a workaround and binds enabled and readOnly as one: setting the checkbox to read-only will disable it.

Select fields

ItemGrid

A highly configurable grid that allows single selection. Each cell in the grid corresponds to one item (in contrast to Vaadin Grid, which displays one item per row).

GridSelect and GridMultiSelect

A single- and multi-selection Grids that are value components, meaning they broadcast value change events (rather than selection events). Both allow access to the underlying Grid, except changing selection mode.

GridMultiSelect operates on Set and has an option to limit the size of the selection.

SuperTabs

A customisable tabbed pane (something like TabSheet in the Vaadin 8 era) that also serves as a value component (current value corresponds to the selected tab).

Components that rely on Intersection Observer API

Please note: the underlying API is experimental. It means its support in browsers may vary. For example, it is not supported by Internet Explorer and mobile browsers. Please check browser support before using these components.

Please also note: apparently the API does not handle style-controlled visibility (at least in Firefox), so if the component gets hidden through CSS display: none, related events may not trigger. For resizing browser windows, scrolling and adding components into DOM things seem to work pretty ok.

Finally please note: I did my best to keep the components Java-friendly, but it may happen that their client state gets out of sync. If that happens, please file a bug report.

ComponentObserver

A wrapper for one instance of client-side IntersectionObserver. It allows observing changes that happen to other components.

LazyLoad

A simple wrapper to lazy load contents when the component gets into view.

ObservedField

A boolean field that changes its value (true or false) depending on whether it is currently shown on the screen or not.

Other components

MultiClickButton

A button that needs to be clicked many times before it notifies its click listeners. Each transition is stored as a state with text, icon, class names and theme names.

UnloadObserver

A component that listens and reacts to browser's beforeunload events that happen for example when browser window/tab is closed. The support varies between browsers, but in general is quite good. This should work with at least the major browsers.

Please note: This component is basically a UI-scoped singleton - there can be only one instance of it per active UI. As such, please refrain from adding the same instance into multiple layouts.

The code is based on solution posted by Kaspar Scherrer and Stuart Robinson (with invaluable feedback from Jean-François Lamy). It does not work with <a href> or Anchor as download links, so please use FileDownloadWrapper for that.

ContentAware

This is an extension of a Div that is aware (through mutation observers) of changes happening to any of its contents (including deeply nested elements).

Links

• View on GitHub
• Online Demo
• Issue tracker

Compatibility