The Search widget allows you to configure a search tool to find features, records, or locations based on specific layers and locators and define how to display search results. If you add multiple search sources to the widget, users can choose which ones to search. Performing the search using a layer source affects data across your app, so other widgets that use the same layer are filtered to show the corresponding search result. If you want search results to be selected, you can set an action. To have the widget select features without filtering the data, create a data view for the data source that you can use as the layer source. Performing a search using a locator source generates an output data source that other widgets can use.
To search, users type a word or phrase in the search box and press Enter, click the search button, or choose from a list of suggestions that appear based on matching records. (The suggestions list displays each matching value as an item, so if a record has two fields that match the search phrase, that record appears as two suggestions.) Users can use the Up and Down arrow keys to browse through the suggestions list. Clicking a suggestion replaces the search phrase with the content from the suggested item to apply the search using the new value, which returns corresponding data in a result panel. To streamline this, there is a setting you can turn on to automatically select the first search result. You can also configure the widget to open another page in your app to show the result in another widget.
Examples
Use this widget to support app design requirements such as the following:
- You want to configure a search option in your app that provides more flexibility than the search tool included in the Map, List, and Table widgets. In particular, you want to search limited fields for specific layers in the map, provide unique hint text in the search box, and display values for certain data fields in the results panel.
- You want users to find information from multiple sources when performing a search.
- You want to display search results in other widgets on a different page in your app.
Usage notes
The Search widget supports two types of search sources—layers and locators. To use a locator source, add a locator service. You can use locators specified in your organization settings or added by you in the Select utility panel. To search layers, select from feature layers and scene layers that are added as data to your app.
You can set actions for a Search widget to interact with other widgets in your app, such as zooming a map to the selected result or showing search results (from a locator source) in a map.
Settings
The Search widget includes the following settings:
- New search source—Add sources for searching content. Choose Layer source or Locator source and specify the following settings for each:
- Data—If applicable, select the data source for the feature layer that you want users to search. In the data view settings, you can filter the data to limit the search scope or sort the data to display search results in a particular order.
- Locator URL—Connect a locator utility service. The Select utility panel shows the locators specified in your organization settings or added by you in the Utility service panel.
- Label—Type a name for the search source. This name appears in the search menu, the suggestion list, and the results panel.
- Icon—Select an icon for the source. This icon shows in the suggestion list and the search results panel. You can choose icons from the General and Arrows galleries, or add your own icon from a file. Click the Delete button to remove unused uploaded icons.
Note:
You can upload the following image formats: PNG, GIF, JPG, JPEG, and BMP. To preserve optimal performance, there is a 10MB size limit for each upload.
- Search options—You can set the following additional options:
- Select searching fields (Layer sources only)—Choose one or more fields to search in the layer.
- Exact match (Layer sources only)—Limit search results to only records that match the search phrase.
- Display fields—Choose one or more fields to display in the search result panel. You can drag selected fields to reorder them.
- Hint—Customize the hint text that appears in the search box when users choose to search only this source.
- Enable filtering for layer source search—If this setting is turned on, then when the user performs a search, the widget filters the connected layer sources by the search criteria.
- General search options—You can set the following general search options:
- Hint for multiple search sources—Customize the hint text that appears in the search box when users choose to search multiple sources.
- Search suggestion—Define the maximum number of suggestions that appear for each search source. You can also configure the following options:
- Use current location—Include a suggestion option to search based on the user’s current location.
- Recent searches—Display the search history in the suggestion box based on a specified maximum number of recent searches. (Users can clear the search history.)
Tip:
Set Maximum suggestions per source to 0 to disable search source suggestions.
- Search result—Choose to display a search results panel or link to a page in your app to show results in another widget.
- Result panel—Display the search results in a panel that appears under the search box. You can define the maximum number of results to display per search source and choose to automatically select the first result.
- Set link—Add a link to open a specific page, window, or section view in your app, or scroll to a specific block or the top of the page to show relevant search results in a corresponding widget. This setting appears when Result panel is turned off.
- Style—Choose an interface style for the result panel, either Classic or Compact. Compact has a smaller collapse button that appears at the bottom of the panel.
Interaction options
When you configure message actions for the Search widget, you can choose from the following triggers depending on the search source.
| Trigger | Layer source | Locator source |
|---|---|---|
Record selection changes |
|
|
Records created |
| |
Data filtering changes |
|
When configured with a locator source, the Search widget generates an output data source that can be used in other widgets. The interaction with additional widgets using the same output data source is achieved through adding actions. For example, the map can automatically display the search results and zoom to the features. In the Search widget settings, on the Action tab, add the Records created trigger, select the target map, and add actions for Show on map and Zoom to.
To select a feature on a map that corresponds with a selected search result, add the Record selection changes trigger for the Search widget (when configured to use the results panel). Select the target framework, add the Select data records action, and configure it with the feature layer for the map and the fields that bind the connection between the trigger and action data. Additionally, you can add the Zoom to action to zoom the map to the feature.
When configured with a layer source, if you want the map to zoom or pan to the selected search result, add the Data filtering changes trigger, select the target map, and add the Pan to and Zoom to actions.
To adjust the level of zoom for the Zoom to action, switch the Zoom scale to Custom and provide the desired scale.
Tip:
For the Search widget to select the feature on a map without filtering the data, create a data view for the data source that you can use as the layer source.