7.1.1 Basic Implementation

A basic implementation of this widget is really quite simple, as demonstrated by Esri’s Search Widget (3D) [1] sample. After adding the Search module to the require() list, all that is necessary to implement the widget is to create a new object of the Search class, set its view property to the app’s view, then add the widget to the view’s UI in the desired position. The widget will match the user’s text against Esri’s World Geocode service by default.

Some properties of the widget that you might consider customizing include:

• allPlaceholder – text users see in the search box prompting them on what to enter
• minSuggestCharacters – number of characters that must be entered before queries are made against the widget’s source
• popupEnabled – Boolean specifying whether a popup can be opened over a search result
• popupOpenOnSelect – Boolean specifying whether a popup should open automatically over the selected result
• popupTemplate – object that defines what the user sees in the popup

7.1.2 Using a Custom Locator

Esri’s World Geocoding service is suitable for many apps, particularly those built at a global or continental scale. However, for apps built for relatively small areas of interest, it may be possible to utilize a locator built using data from an authoritative source, such as a city or county. The advantage to using a locator from such a source is that it is much more likely to be kept up to date (e.g., to contain new subdivisions).

The example above was built using a locator developed specifically for the City of St. Paul, Minnesota. The first step in creating an app like this is discovering the desired locator. Many locators can be found in ArcGIS Online by searching for locator in the Tools category.  (1277 Madison St is an address in St. Paul if you're looking to try the locator.) If this sample does not work for you, it may be that the City has taken its geocoder / locator service offline probably due to costs as geocoding is one of the more expensive services to maintain due to the number of credits used.

Once you've identified the ArcGIS Server REST endpoint of your desired locator, incorporating it into your app involves modifying the Search widget’s sources property. In my example, I included only the St. Paul locator [5], but as the property name implies, you can wire the widget up to multiple locators (e.g., you might have locators available for adjacent jurisdictions). The widget is designed such that Esri's World Geocoding service is included as a source by default.  I've disabled that behavior by setting the includeDefaultSources property to false.  We’ll see a multi-source example later in the lesson.

As explained in the SDK, the Search widget can have its sources property set to a LocatorSearchSource, LayerSearchSource, or some combination of the two. Looking at the LocatorSearchSource [6] documentation, you’ll notice that a LocatorSearchSource object has some of the same properties mentioned on the previous page (e.g., popupEnabled). While perhaps a bit confusing, this duplication allows for having different settings for these properties on a source-by-source basis. For example, you might have a reason to disable popups for one of your widget’s sources, but enable them for another.

Getting back to the St. Paul example, the sources property is set using a single LocatorSearchSource object. Unsurprisingly, the most important property to set for this object is its url, which should be set using the REST endpoint of the locator service.

From there, because the widget provides just a single text box, you’ll want to look for matches against the locator field that is labeled as the Single Line Address Field in the REST Services Directory. In the case of the St. Paul service, that field is called SingleLine.

Finally, the placeholder property is used to provide a prompt or hint to the user on what should be entered in the search box.

In addition to its locator, there are several other LocatorSearchSource properties that you might want to set. Here are a few of them:

• autoNavigate – do you want to zoom to the selected location?
• countryCode – used to restrict searches to a single country (e.g., "US")
• resultSymbol – used to customize the symbol used to show the selected location
• zoomScale – used to control the scale that the app will zoom to after finding a match

7.1.3 Searching in a FeatureLayer

As mentioned earlier, the Search widget can also be configured to find features in a FeatureLayer. The app below allows for finding cities and counties in Jen & Barry's world.

The key difference as compared to the previous example is that a LayerSearchSource (actually two) is used instead of a LocatorSearchSource. The SDK shows that a LayerSearchSource [8] has many properties in common with a LocatorSearchSource, though it obviously has others that are unique to it.

Here’s a quick rundown of what’s happening in this app:

• The two FeatureLayers are created using their portalItem ids as we’ve done earlier in the course.
• An appropriate PopupTemplate is defined for each FeatureLayer.
• The searchFields property is set to the field that should be searched for the user’s text.
• The exactMatch property is set to false, allowing for partial matches.
• The outFields property is set to the array of fields used by the app. In this case, only the NAME field is needed in both layers.
• When more than one source is specified for the widget, a drop-down arrow appears on the left side of the search box. The drop-down list contains a choice for each of the sources. Setting a LayerSearchSource’s name property specifies how the source will appear in the drop-down list. (In this case, "Cities" and "Counties" is assigned to the name property.)
• The allPlaceholder property (which is assigned to the Search object) controls the hint that appears in the search box when it has multiple sources.
• The placeholder property (set at the source level) controls the hint that appears if that individual source is selected from the drop-down list discussed above.
• The zoomScale property is set for the cities layer source. Unlike lines and polygons, points have no logical extent envelope to zoom to. Leaving this property unset on a point layer is likely to cause the app to zoom in closer than you would like. Leaving the property unset on the county layer makes sense since zooming to the polygon extent works nicely.