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.
Demo application of the latest release can be found at https://superfields.herokuapp.com/.
Source code for the app and for the components can be found at https://github.com/vaadin-miki/super-fields/.
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.
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:
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
Most of the components that can have a label allow positioning said label through
withLabelPosition(...)). This should work in most layouts, with
FormLayout being an obvious exception. Not all components support all possible values of
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.
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.
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.
An input field for entering localised
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.
An input field for entering localised
Long numbers. Supports thousands (grouping) separators.
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).
DateTimePicker that fetch month names and weekday names from Java
Locale. Those settings can be overwritten by resource bundle named
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
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.
MapField and related helpers
Almost out-of-the-box, fully configurable
CustomField for data of type
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.
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 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
MapEntryField is a component that is a
Map.Entry<K, V>. It allows custom layout and dedicated components for keys and values of the map.
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
CustomFieldthat 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
HasComponentsmethod 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).
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.
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
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.
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 (
EnumObjectTest) for details. Also please note that
ObjectFieldFactory will become a separate library at some point in the future.
It is known that
Checkbox does not support read-only mode. This component exists as a workaround and binds
readOnly as one: setting the checkbox to read-only will disable it.
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).
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.
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.
A wrapper for one instance of client-side
IntersectionObserver. It allows observing changes that happen to other components.
A simple wrapper to lazy load contents when the component gets into view.
A boolean field that changes its value (
false) depending on whether it is currently shown on the screen or not.
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.
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.
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).
0.15.0 - HasPositionableLabel
New features and enhancements
Changes to API
- #412 - SuperCheckbox should implement relevant marker interfaces
- #415 - CollectionField and Grid(Multi)Select should implement HasLabel