SearchField Component

The SearchField component presents a text input field with an accompanying button for executing searches. It also provides runtime configuration options accessible via a settings button.

XML Element

searchField

Java Class

io.jmix.searchflowui.component.SearchField

Attributes

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

Handlers

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

Basics

To add the component on the view, use Jmix Studio.

Click Add Component in the actions panel, then find the SearchField item and double-click it.

create search field component

The new searchField element will be added both in the Jmix UI structure panel and in the XML descriptor. You can configure standard attributes (id, height, width, etc.) just like any other UI component.

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

If you don’t use the view designer, declare the search namespace in your view’s XML descriptor manually:

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

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

Common attributes serve the same purpose for all components. 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 single page of search result.

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

searchStrategy

Determines the search strategy applied. See Search Strategies.

anyTermAnyField

settingsButtonVisible

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

true