Utility functions missing from Vaadin 14+, for your Kotlin-based projects.
The jar is in Maven Central, so it's easy to add this library to your project.
Gradle:
repositories {
mavenCentral()
}
dependencies {
api("com.github.mvysny.karibu-tools:karibu-tools:x.y")
}
Note: for Vaadin 23+, depend on
karibu-tools-23
instead, to bring some additional utilities.
See the tag above for the latest version.
A set of general Vaadin utilities applicable to all components.
VaadinVersion.get
property to get the Vaadin version such as 14.7.0VaadinVersion.flow
to obtain the Vaadin Flow flow-server.jar
version: for example 2.6.7 for Vaadin 14.6.8.component.fireEvent()
to fire any event on the component (a shortcut to ComponentUtil.fireEvent()
).ClickNotifier.serverClick()
to notify all click listeners (to fire a ClickEvent
).Component.findAncestor()
or Component.findAncestorOrSelf()
to discover component'sComponent.removeFromParent()
to remove the component from its parent.Component.isNestedIn(potentialAncestor: Component)
to discover whether a componentComponent.isAttached()
to see whether this component is currently attached to an UI.HasOrderedComponents<*>.insertBefore()
to insert a component before given component.HasComponents.hasChildren
to see whether a component has any children.Component.walk()
will return an Iterable<Component>
which walks the component child tree,component.textAlign
to read/write the text-align
CSS propertycomponent.tooltip
to read/write the hovering tooltip (the title
CSS property)Component.addContextMenuListener()
to add the right-click context listener to a component.UI.currentViewLocation
to return the location of the currently shown view.div.addClassNames2(" foo bar baz")
to add multiple class names. Vote for flow #11709.
div.removeClassNames2()
and div.setClassNames2()
component.placeholder
unifies the various component placeholders, usually shown when there's no value selected.component.caption
unifies component captions. Caption is displayed directly on the component (e.g. the Button text),component.label
unifies component labels. Takes advantage of HasLabel
in newer Vaadin.LabelWrapper
if you need to add a label on top of a component which doesn't support labels,FormLayout
.component.ariaLabel
gets/sets the aria-label
attribute. See HasAriaLabel
in Vaadin 23+ for more details. Since 0.17.ClassList.toggle
to set or remove given CSS class.Element.setOrRemoveAttribute
to set an attribute to given value, or remove theElement.insertBefore()
to insert a child element before another child. A counterpart for JavaScript DOMNode.insertBefore()
.Element.textRecursively2
returns all the text recursively present in the element. Vote forElement.getVirtualChildren()
Returns all virtual child elements added via Element.appendVirtualChild
.StateNode.element
returns Element
for that StateNode
.Element.getChildrenInSlot("prefix")
will return all child elements nested in the prefix
slot.Element.clearSlot("prefix")
will remove all child elements nested in the prefix
slot.Navigating:
navigateTo<AdminRoute>()
or navigateTo(AdminRoute::class)
or navigateTo(DocumentRoute::class, 25L)
.navigateTo(String)
to navigate anywhere within the app. Supports query parameters as well:
""
(empty string) - the root view.foo/bar
- navigates to a viewfoo/25
- navigates to a view with parametersfoo/25?token=bar
- any view with parameters and query parameters?token=foo
- the root view with query parametersnavigateTo(getRouteUrl(AdminRoute::class, "lang=en"))
to navigate to admin?lang=en
.AfterNavigationEvent
, query event.routeClass
Location
, call location.getRouteClass()
QueryParameters:
call queryParameters["foo"]
to obtain the value of the ?foo=bar
query parameter.
call queryParameters.getValues("foo")
to get all values of the foo
query parameter.
call the QueryParameters("foo=bar")
factory method to parse the query part of the URL
to the Vaadin QueryParameters
class.
RouterLink.target
allows you to set AnchorTargetValue
, e.g. AnchorTargetValue.BLANK
. Since 0.16
RouterLink.setOpenInNewTab()
opens the router link in new browser tab/window (sets target to AnchorTargetValue.BLANK
). Since 0.16
Anchor.target_
clears up the Anchor mess by adding yet another property :-D Since 0.16
Anchor.setOpenInNewTab()
opens the anchor in new browser tab/window (sets target to AnchorTargetValue.BLANK
). Since 0.16
In order to properly display LocalDate
and LocalDateTime
on client's machine, you need
to fetch the browser's TimeZone first. You can achieve that simply by calling BrowserTimeZone.fetch()
,
for example when the Vaadin UI is being initialized.
fetch()
will request the information from
the browser and will store it into the session. Afterwards, simply
call BrowserTimeZone.get
to get the browser's time zone instantly.
BrowserTimeZone.currentDateTime
to get the current date time at browser's current time zone.The following functions are applicable to any field that edits text, e.g.
TextField
, TextArea
, EmailField
:
field.selectAll()
to select all text within the field.field.selectNone()
to select no textfield.setCursorLocation()
to place the cursor at given characterfield.select(range)
to select a range within the text.dataProvider.fetchAll()
to fetch all items provided by this data provider as an eager list. Careful with larger data!Person::name.asc
/Person::name.desc
to create a QuerySortOrder
which is useful with DataProvider's Query.sortOrders
Grid.sort()
.Grid.refresh()
to call DataProvider.refreshAll()
Grid.isMultiSelect
to see whether a grid is configured as multi-select.Grid.isSingleSelect
to see whether a grid is configured as single-select.Grid.isSelectionEmpty
returns true if there's nothing selected in the grid.Grid.selectionMode
allows you to read/write the current selection mode.Grid.isSelectionAllowed
returns false if Grid.SelectionMode.NONE
is currently set.Grid.addColumnFor()
which allow you to create a columnKProperty
grid.addColumnFor(Person::name)
will create aGrid.getColumnBy(Person::name)
retrieves a column created via grid.addColumnFor(Person::name)
.HeaderRow.getCell(Person::name)
retrieves header cell for given column.FooterRow.getCell(Person::name)
retrieves footer cell for given column.HeaderCell.component
/FooterCell.component
sets or returns a component setgrid.sort()
sorts the grid:
grid.sort(nameColumn.asc)
sorts ascending by given column;grid.sort(Person::name.asc)
sorts ascending by column created via grid.addColumnFor(Person::name)
treeGrid.getRootItems()
will fetch the root itemstreeGrid.expandAll()
will expand all nodes; may invoke massive data loading.column.header2
returns the header set via the setHeader()
function.basicRenderer.valueProvider
returns the ValueProvider
set to the renderer.ItemClickEvent.isDoubleClick
Make sure you use these imports:
import com.vaadin.flow.component.Key.*
Then:
button.addClickShortcut(Alt + Ctrl + KEY_C)
clicks the button when Alt+Ctrl+C is pressed.button.addFocusShortcut(Alt + Ctrl + KEY_C)
focuses the button when Alt+Ctrl+C is pressed.route.addShortcut(Alt + Ctrl + KEY_C) { println("Foo") }
will cause Vaadin to runtextField.onEnter { println("Enter") }
is called when ENTER is pressed while the TextField is focused. (since 0.16)Make sure to read the Safe JavaScript Keyboard shortcuts article before designing shortcuts for your app.
MenuBar.close()
to close the submenu popup. Vote for #5742.MenuBar.addIconItem()
and SubMenu.addIconItem()
to add items with icons.icon.iconName
provides a type-safe access to setting icons.icon.setIcon(VaadinIcon)
adds the missing API of setting icons.To use custom icons with Vaadin 14+, see Custom Icons With Vaadin 14.
getAllDialogs()
will return all dialogs attached to the UI. There may be closed dialogsdialog.center()
centers the dialog within the screen. Vote for #220
dialog.requestClose()
honors listeners registered via addDialogCloseActionListener()
.button.setPrimary()
adds the ButtonVariant.LUMO_PRIMARY
theme.notification.getText()
returns the text set to the notification. Vote for #2446.notification.addCloseButton()
adds a close button, which makes the notification closeable by the user0
starts making sense). Vote for #438.PageConfigurator
is now deprecated, the suggestion is to use BootstrapListener
but there
are no utility methods to add meta tags etc! Therefore we introduce the following utility methods (see examples below):
Element.addMetaTag()
(since 0.5) adds a <meta name="foo" content="baz">
element to the html head.class MyServiceInitListener : VaadinServiceInitListener {
override fun serviceInit(event: ServiceInitEvent) {
event.addBootstrapListener {
it.document.head().addMetaTag("apple-mobile-web-app-capable", "yes")
it.document.head().addMetaTag("apple-mobile-web-app-status-bar-style", "black")
}
}
}
Upload.isEnabled
(since 0.5) allows you to enable or disable the upload component.Upload.clear()
(since 0.6) clears the list of uploaded files.Upload.clearFileList()
in newer Vaadin.AbstractLogin.setErrorMessage(title: String?, message: String?)
(since 0.5)setError(true)
. Vote for issue #1525
setItemLabelGenerator()
sets the item label generator. Since 0.6. Implemented in newer Vaadin.The HtmlSpan
component (since 0.6) has an advantage over Vaadin-provided Html
-
it will accept any HTML snippet and will set it as an innerHTML
to a <span>
element.
ComboBoxVariant
, addThemeVariants()
and removeThemeVariants()
. Only applicable to Vaadin 14, sinceComboBox.isSmall
toggles the small
themeComboBox.isHelperAboveField
toggles the helper-above-field
themeComboBox.textAlign
toggles the align-left
/align-center
/align-right
theme.ComboBox.dropdownWidth
sets a custom dropdown popup overlay width to e.g. 100px
30em
. See+vote for Issue #2331.ComboBox.prefixComponent
sets a custom prefix component. Already available in Vaadin 24+, but handy for Vaadin 23 and lower.DatePicker.prefixComponent
sets a custom prefix component. Already available in Vaadin 24+, but handy for Vaadin 23 and lower.SelectVariant
, addThemeVariants()
and removeThemeVariants()
.
Select.isSmall
toggles the small
themeSelect.isHelperAboveField
toggles the helper-above-field
themeSelect.textAlign
toggles the align-left
/align-center
/align-right
theme.Select.prefixComponent
sets a custom prefix component. Already available in Vaadin 24+, but handy for Vaadin 23 and lower.ListBox.setItemLabelGenerator()
sets the label generator. Present in newer Vaadin, both in ListBox
and MultiSelectListBox
.Validator.isValid("foo")
will run the validator on given value and will return either true or false,rangeValidatorOf("must be 0 or greater", 0, null)
accepts nulls for min/max. (since 0.16)Since 0.18; depend on karibu-tools-23
to gain access to these utility functions.
Tab.index
to obtain the index of the tab.Tab.owner
returns the Tabs
owning this tabTab.ownerTabSheet
returns the TabSheet
owning this tab.Tab.contents
/TabSheet.getComponent()
returns the contents component of given tab (TabSheet only)TabSheet.tabCount
returns the number of the tabsTabSheet.removeAll()
removes all tabsTabSheet.tabs
returns a List<Tab>
of all tabsTabSheet.getTab()
returns Tab
for its content component (TabSheet only)TabSheet.findTabContaining()
returns Tab
which transitively contains given component.Java: use TabSheetsKt.getTab()
etc.
Licensed under Apache 2.0
Copyright 2021-2022 Martin Vysny
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this software except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
See Contributing.