search-ui

This bundle offers a user interface for searching in multiple data sources. If a search result is selected, the actions that are configured in this bundle are performed.

Search results are provided by the SearchService service implementation of the search-api bundle.

The API of this bundle is described in detail in the API documentation.

Usage

No configuration is required. Default values are applied.

The widget is registered at the component system with the widget role search-ui.

Configuration reference

The following code sample shows all configurable properties and their default values:

"search-ui": {
    "Config": {
        "actions": [
            "zoomto",
            "highlight",
            "openpopup"
        ],
        "maxResultsPerGroup": 5,
        "showTotalResultsCount": false,
        "placeholderText": "${search.placeholder}",
        "searchDelay": 100,
        "minSearchCharacters": 1,
        "zoomto-point-scale": 1000,
        "<action-property>": "value"
    }
}

Configure actions

For more information about configuration options of the default actions, see the map-actions bundle documentation.

Use cases

How to configure actions

For configuration options of the highlight and zoomto actions consider the map-actions documentation. To use the openpopup action define a popupTemplate. See map-actions how to add custom actions, too.

How to add custom actions

For more information about adding custom actions, see the map-actions bundle.

How to define the order of search results

This bundle shows search results in an order that matches the search priority of the given data sources:

• If data sources have no or equal priority, search results are displayed in the order they become available.
• If the search priorities of given data sources are configured individually, search results of higher prioritized data sources are displayed before results of lower prioritized data sources.
• Since results of lower prioritized data sources are not displayed before the results of higher prioritized data sources, we recommend to only configure fast data sources with a higher priority.

The following code sample shows an app configuration with different stores:

• The Countries store has the highest search priority (searchPriority is 1).
• The Cities store has a lower search priority (searchPriority is 2).
• The Addresses and Streets stores have the same but lowest priority (searchPriority is 3).

"agssearch": {
    "AGSStore":[
        {
            "id": "Countries",
            "url": "https://myserver/arcgis/rest/services/Countries/MapServer/0",
            "searchPriority": 1
        },
        {
            "id": "Cities",
            "url": "https://myserver/arcgis/rest/services/Cities/MapServer/0",
            "searchPriority": 2
        },
        {
            "id": "Addresses",
            "url": "https://myserver/arcgis/rest/services/Addresses/MapServer/0",
            "searchPriority": 3
        },
        {
            "id": "Streets",
            "url": "https://myserver/arcgis/rest/services/Streets/MapServer/0",
            "searchPriority": 3
        }
    ]
}

The search results are displayed in the following order:

1. Countries
2. Cities (after the search for Countries has finished)
3. Addresses or Streets (after the search for Cities has also finished) depending on which store is faster.

If searchPriority is not explicitly defined for a store, the priority value 50 is applied.

Reset the search-ui programmatically

To reset the current search programmatically, for example because a new workflow is started, perform the following steps:

First inject the search-ui.SearchUiService to your bundle:

"components": [
    {
        "name": "MyComponent",
        "references": [{
            "name": "searchUiService",
            "providing": "search-ui.SearchUiService"
        }]
    }
]

To reset the search, use the reset() method as follows:

import { InjectedReference } from "apprt-core/InjectedReference";
import { SearchUiService } from "search-ui/api";

private searchUiService: InjectedReference<SearchUiService>;
...
searchUiService!.reset();

Set a text in the search-ui programmatically

The previously described reset() method also accepts a searchText value, which sets a text in the input field, but will not trigger a search:

searchUiService.reset({ searchText: "My search term" });

Define a custom action for <ENTER> key press

To define a custom behaviour when pressing the <ENTER> key while typing a search term, you can use the SearchUiEnterKeyAction interface.

The code inside it's trigger() method is executed, when you press the <ENTER> key while the focus is inside the search-ui's text-input. Furthermore, you can be notified, when the search-ui's input is cleared. To do so, you can implement some code inside the reset() method. This is optional.

To implement a custom action, first inject the search-ui.SearchUiService to your bundle:

"components": [{
    "name": "CustomEnterKeyAction",
    "provides": ["search-ui.EnterKeyAction"],
}]

NOTE: Only a single EnterKeyAction is allowed to be registered at the same time.

Then implement the logic for your custom action like in the following example:

import { InjectedReference } from "apprt-core/InjectedReference";
import { SearchUiEnterKeyAction } from "search-ui/api";

export class CustomEnterKeyAction implements SearchUiEnterKeyAction {
    description = "An optional description for the action. It will appear as tooltip for the magnifying glass icon button of the search-ui and as its aria-label.";
    trigger(inputText: string): void {
        console.info(`Action 'trigger' triggered with '${inputText}'`);
    }
    reset(): void {
        console.info("Action 'reset' was triggered");
    }
}