Search widget

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.

If you configure multiple search sources, at run time users can use the drop-down menu to turn individual sources on and off, or use the All check box to turn every source on or off.

With locator sources, you can enter the following types of search terms:

• Place-names

• Points of interest

• Addresses

• UTM coordinates

• Coordinates in a coordinate system that you specify with a well-known ID (WKID).

  The format for this is x, y: WKID . An example is -13046165.52, 4036389.847: 102100

If you connect a Search widget and Map widget to the same feature layer, and turn on Show pop-up upon feature selection in the Map widget's settings, pop-ups appear when you select records from search results.

Search methods

The Search widget uses different methods to retrieve search suggestions and search results.

The widget uses full-text search to retrieve search suggestions for layer sources. Full-text search is an efficient search method that uses full-text field indexes, which split up records into small units, such as individual words. For example, imagine you have a layer of United States Post Office locations with a name field containing the names of every post office location. The index splits the name Highland Station Baltimore Post Office into five individually searchable words: Highland , Station , Baltimore , Post , and Office . If you enter a search phrase made up of any combination of those words (or just the first part of any of them) such as Baltimore Office , Highland Baltimore , or Stat Balt Office , you get that office in the search suggestions.

Full-text field indexes are automatically generated for hosted feature layers when you select them as search fields for the Search, List, or Table widget if you are the owner of the hosted feature layer or an organization administrator. You can also manually add indexes to attribute fields on the layer's item details page. If you have layers with no indexes and you do not have permission to edit the layers, the Search widget finds suggestions using START WITH abc% , meaning the widget looks for records that start with the search phrase. This is a less efficient search method.

To retrieve search results, the widget uses CONTAIN %abc% , meaning the search phrase can be anywhere in the record. For example, you can search for alt to get Baltimore, Salt Lake City, and Alton in search results.

Settings

The Search widget includes the following settings:

• Source—You must connect the Search widget to data so that the user has something to search through. You can connect the Search widget to data in one of the following ways:

  • Add custom search sources—Add search sources without connecting the widget to a Map widget. Click New search source to connect layer or locator sources.
  • Interact with a Map widget—Connect the Search widget to a Map widget.

  If you connect the Search widget to a Map widget, by default the Search widget uses any layers and locators that are already configured as the map's search sources. If you want to change the search sources, turn on Customize search sources then select available sources from the list that appears, or add new sources by clicking New search source.

  When you connect the Search widget to a Map widget, the Show on map and Zoom to message actions are automatically added in the Search widget's action 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 that you want users to use to search. In 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.

  • 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.

    • Search in specific countries or regions—This additional setting appears for the ArcGIS World Geocoding Service. Enter a country code to narrow results to that country.

• Enable filtering for layer source search—If this setting is turned on, 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.)

• Search result—Choose to display a search results panel or link to a page in your app to show results in another widget.

  • Auto select the first result—Select the first result when the user performs a search.
  • 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.
  • 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.

• Arrangement style—Choose a user interface for the widget, either Square, Curve, or Linear.

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. When you connect a Search widget to a Map widget, these two actions are configured automatically.

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.

URL parameters

The subsections below describe search-related URL parameters. You can use the settings under Manage URL status to make these parameters appear in the URL when the user performs a search. Search widget parameters follow hashmarks (# ).

Show the search input

The searchText parameter shows what text the user entered to perform a search. The following is an example URL with the searchText parameter:

1
https://experience.arcgis.com/experience/<AppId>#<searchWidgetID>=search_status:%7B"searchText"%3A"<text>"%7D

Show the search source

When the user performs a search using only some of the available search sources, one of the two following parameters appear in the URL:

• If at least one search source is unchecked in the widget's drop-down menu at run time, the serviceEnabledList parameter appears and defines which search sources are checked. This parameter is hidden when all search sources are checked. The following is an example encoded URL:

  Use dark colors for code blocksCopy

  1
  https://experience.arcgis.com/experience/<AppId>#<searchWidgetID>=search_status:%7B"serviceEnabledList"%3A%5B"<SourceID1>"%2C"<SourceID2>"%5D%7D

• If the user clicks a search suggestion to apply a search, the "status":{"configId":"<SourceID>"} parameter appears and defines the unique search source being used in the current search. Both the search input and the search source appear in the URL. The following is an example encoded URL:

  Use dark colors for code blocksCopy

  1
  https://experience.arcgis.com/experience/<AppId>#<searchWidgetID>=search_status:%7B"searchText"%3A"<text>"%2C"status"%3A%7B"configId"%3A"<SourceID>"%7D%7D

If the user clicks a search suggestion from a locator source, the URL displays the magicKey associated with the suggestion. A magicKey is a unique ID that links a suggestion to a specific address or place. The following is an example of search properties and parameters written in JSON format:

1
2
3
4
5
6
7
{
	"searchText": "<text>",
	"status":{
		"configId": "<SourceID>",
		"magicKey": "<key>"
	}
}

The following is an example of the same properties and parameters above written in an encoded URL:

1
https://experience.arcgis.com/experience/<AppId>#<searchWidgetID>=search_status:%7B"searchText"%3A"<text>"%2C"status"%3A%7B"configId"%3A"<SourceID>"%2C"magicKey"%3A"<key>"%7D%7D