# 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](https://www.slf4j.org). 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](https://stackoverflow.com/questions/45997759/how-to-change-slf4j-logging-level). ## 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` (or `Set`). 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`. It is based on `CollectionField` and works with any field capable of displaying value of type `Map.Entry`. `MapEntryField` is a component that is a `CustomField` for `Map.Entry`. 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