SingleSearch Control

The ALKMaps.Control.SingleSearch control provides a single box for all search types. User does not need to manually specify how the query should be broken down. The ALK geocoder service supports for search near current location, map view, or other point. It returns short pick list of results, ranked appropriately. By default, the control displays the results stacked under the search box.

SingleSearch Control

If the input search box still has the focus, pressing the Enter key will make the first item in the results list having the focus. Then pressing the Tab key will move the focus to the next item. Pressing the Esc key will hide the results list.

Add Control

var map = new ALKMaps.Map("map");
var singleSearchControl = new ALKMaps.Control.SingleSearch({
  // options
});
map.addControl(singleSearchControl);
singleSearchControl.activate();

The control can be created by calling the ALKMaps.Control.SingleSearch constructor. The constructor takes many parameters. Descriptions for the parameters can be found in the table below.

ParameterType/ValuesDescription
doneTypingIntervalNumberDefault: 700
The debounce value in milliseconds. The search web service request fire rate limit to this value.
placeholderTextStringDefault: Address …
Place holder text for the search box.
minSearchTextLengthNumberDefault: 3
If search text is longer than this value, then search can be started.
locationRelevanceStringDefault: null
Available values are “mapCenter”, “device”, or null. If it is set, map view center or device location will be used to assist search.
Note: Device location is obtained from navigator.geolocation. For it to work, HTTPS has to be enabled.
hideResultsBooleanDefault: false
Hide results list or not when a result item is clicked on or enter key is pressed on a focused item.
displaySystemStringDefault: metric
Show distance in KM or Miles in results list. Accepts “metric” or “english’.
searchOptionObjectOptional.
See the section below.
markerStyleObjectOptional.
See the section below.
markerConfigObjectOptional.
See the section below.
popupConfig{object}Optional.
See the section below.

Search Option

The searchOption parameter contains options that are used by the geocoder web service to perform the search.

ParameterType/ValuesDescription
queryStringDefault: null
If it is not null, the search input box value will be ignored by the control. It is optional.
maxResultsNumberDefault: 20
Maximum returned results.
currentLonLatL.latLngDefault: null
Search near the location provided. Latitude and longitude values are in degrees. It is optional. The control can set current location based on navigator.geolocation location or map view center. They are optional too.
Note: For navigator.geolocation to work, HTTPS has to be enabled.
excludedSearchTypesStringDefault: null
Comma-separated list of types to exclude from the search.
Note: To get supported types, call ALKMaps.Geocoder.singleSearchGet(“types”) method.
poiCategoriesStringDefault: null
Comma-separated list of POI category names by which you want to filter all POI results.
Note: To get supported categories, call ALKMaps.Geocoder.singleSearchGet(“poiCategories”) method.
countriesStringDefault: null
Comma-separated list of country abbreviations by which you want to filter all results.
Note: To get all countries, call ALKMaps.Geocoder.singleSearchGet(“countries”) method.
countryType["ISO", "FIPS", "GENC2", "GENC3"]Default: null
Note: To get supported types, call ALKMaps.Geocoder.singleSearchGetCountryTypes() method.
statesStringDefault: null
Comma-separated list of state abbreviations by which you want to filter all results.
Note: To get all states, you can call ALKMaps.Geocoder.singleSearchGet(“states”) method.
region["NA", "EU", "WW"]Required.
Note: To get supported regions, call ALKMaps.Geocoder.singleSearchGetRegions() method.
asyncBooleanDefault: true
Open an asynchronous request or not.
successFunctionOptional.
If it is provided, it will replace the control built-in handler method.
failureFunctionOptional.
If it is provided, it will replace the control built-in handler method.

Marker Style

After search results are returned, the control will display them as a stacked list under the search input box by default. When a list item is clicked or the Enter key is pressed on an item having the focus in the list, a marker for the location will be shown on the map. The markerStyle parameter determines the marker’s look and feel. Setup this property while creating an instance of this control. Changing this property after initialization may cause undesired effects.

ParameterType/ValuesDescription
externalGraphicStringDefault: null
If the URL is supplied, it will replace the default icon. If null, the control will choose icon for the marker based on result type.
graphicHeightNumberDefault: 26
Marker height in pixel.
graphicWidthNumberDefault: 26
Marker height in pixel.
graphicXOffsetNumberDefault: -13
Marker x-direction offset.
graphicYOffsetNumberDefault: -13
Marker y-direction offset.

Marker Configuration

The markerConfig parameter contains options related to the creation of the marker on the map.

ParameterType/ValuesDescription
exclusiveBooleanDefault: true
If true, erases all other makers first.
centerOnMapBooleanDefault: true
Center the marker on the map.
zoomLevelNumberDefault: 12
Centers the marker at the zoom level.

The popupConfig parameter contains options related to the creation of the marker popup on the map.

ParameterType/ValuesDescription
showBooleanDefault: true
If true, shows popup with the marker.
idStringDefault: Null
Unique identifier. If null, the system will assign id to each popup.
displayClassStringDefault: single-search
CSS class name. If you change this value, you need add your CSS class to your style file.
sizeALKMaps.SizeDefault: 200 x 50 pixel
Popup size. Set it to null, the control will auto-size the popup.
offsetALKMaps.PixelDefault: (0, -13)
Popup location offset.
closeBoxBooleanDefault: false
If true, show close button on the popup.
closeBoxCallbackFunctionDefault: null
Function to be called on closeBox click.
exclusiveBooleanDefault: true
If true, closes all other popups first.

Custom Events

The control exposes a few custom events.

EventDescription
locationfailedTriggered when browser’s geolocation failure. It can be caused by HTTPS is not enabled. The event object will include an error property that references the error.
searchcompletedTriggered when the control receives results from the single search web service before the control starts to show results. The event object will include a locations property that references the results. When a listener returns “false”, the step of showing results list will be skipped.
resultslistdrawnTriggered after results list is shown. The event object will include a locations property that reference the search results.
locationclickTriggered when user clicks on a location item on the displayed results list. The event object will include a location property that references the location. When a listener returns “false”, the step of showing the location marker on the map will be aborted.
locationenterTriggered when user presses enter key if the location item has the focus. The event object will include a location property that references the location. When a listener returns “false”, the step of showing the location marker on the map will be aborted.
resultslistescapeTriggered when the Esc key is pressed if any location item has the focus. The event object will include a resultsListElement property that references the UL DOM element. When a listener returns “false”, the step of hiding results list process will be aborted.
beforeprocessresponseitemTrigged before a location marker with an optional popup is added to the map. The event object will include a location property that references the location. When a listener returns “false”, the step of showing the location marker on the map will be aborted. By handling this event, user does not need to handle locationclick and locationenter separately.
locationblurTriggered when a location item in the displayed list loses focus. The event object will include a location property that references the location. When a listener returns “false”, the activate keyboard control process will be aborted.
locationfocusTriggered when a location item in the displayed list gets focus. The event object will include a location property that references the location. When a listener returns “false”, the deactivate keyboard control process will be aborted.
beforegeticonTriggered when showing location results list or showing location marker on the map. The event object will include a location property that references the location. If a listener returns an icon path, this icon will be used instead of the application default icon. Be aware that if markerStyle.externalGraphic is supplied, it will be used to draw the location marker.

Creating Event Listener

singleSearchControl.events.register("searchcompleted", this, function(data) {
  console.log("searchcompleted", data);
  return true; // optional
});
Last updated November 5, 2019.