searchField

This component requires the free Search add-on.

searchField provides a text input and controls for executing and configuring full-text searches.

XML Element

searchField

Java Class

SearchField

Basics

Declare the search namespace in the view’s XML descriptor:

<view xmlns="http://jmix.io/schema/flowui/view"
      xmlns:search="http://jmix.io/schema/search/ui"
      title="msg://searchView.title">

Studio adds the namespace automatically when you add the component using the Add Component action in the top actions panel. See Component Palette.

Then add searchField to the view:

<search:searchField id="searchField"/>
search field

Runtime Configuration

The searchField includes a settings button (vertical ellipsis ⋮) that opens a configuration dialog, allowing users to dynamically adjust search parameters without modifying the XML.

search settings dialog

Users can configure the following options at runtime:

Configuration Corresponding Attribute Description

Search Strategy

searchStrategy

Determines how the search term is processed

Size

searchSize

Limits the number of search results

Entities

entities

Specifies which entities to search (multiple entities can be selected)

Hiding the Settings Button

You can hide the settings button using the settingsButtonVisible attribute:

<search:searchField id="searchCustomerField"
                    settingsButtonVisible="false"/>

Search Results View

By default, the searchField opens the built-in SearchResultsView. This view handles the search engine querying process and displays results either in the current navigation view or in a dialog, depending on the openMode attribute.

To modify this behavior, configure a SearchCompletedHandler. This can be done either declaratively using the @Install annotation or programmatically using setSearchCompletedHandler().

Example with @Install:

@Autowired
private DialogWindows dialogWindows;

@ViewComponent
private SearchField searchField;

@Install(to = "searchField", subject = "searchCompletedHandler")
private void searchFieldSearchCompletedHandler(
        final SearchField.SearchCompletedEvent event) {
    DialogWindow<SearchResultsView> searchResultsDialog =
            dialogWindows.view(UiComponentUtils.getView(this),
                            SearchResultsView.class)
                    .build();
    SearchResultsView view = searchResultsDialog.getView();
    view.initView(new SearchFieldContext(searchField));
    searchResultsDialog.open();
}

Attributes

The following attributes are specific to searchField:

Name Description Default

entities

Specifies which entities to search. Multiple entities can be listed as a comma-separated sequence.

<search:searchField id="searchField"
                    entities="Customer, Order_"/>

—

openMode

Specifies how the search results view is opened when a search is executed. NAVIGATION replaces the main content area; DIALOG opens a modal window.

NAVIGATION

searchButtonVisible

Shows or hides the search button.

true

searchSize

Limits the number of search results displayed on a single page of search results.

Inherited from the application property jmix.search.search-result-page-size.

searchStrategy

Determines the search strategy applied. See Search Strategies.

jmix.search.default-search-strategy

settingsButtonVisible

Shows or hides the settings button (⋮). See Runtime Configuration.

true

The following shared attributes are supported by searchField:

id - alignSelf - ariaLabel - ariaLabelledBy - autofocus - classNames - colspan - css - enabled - focusShortcut - height - helperText - justifySelf - label - maxHeight - maxWidth - minHeight - minWidth - placeholder - tabIndex - themeNames - title - value - valueChangeMode - valueChangeTimeout - visible - width

Handlers

The following handler is specific to searchField:

To generate a handler stub in Jmix Studio, use the Handlers tab of the Jmix UI inspector panel or the Generate Handler action available in the top panel of the view class and through the Code → Generate menu (Alt+Insert / Cmd+N).
Name Description

searchCompletedHandler

Handles the completed search and receives a SearchCompletedEvent containing the search result. See Search Results View.

The following shared handlers are supported by searchField:

AttachEvent - BlurEvent - ComponentValueChangeEvent - DetachEvent - FocusEvent - InputEvent - KeyDownEvent - KeyPressEvent - KeyUpEvent