Single Search Add-on
Contents
The Single Search add-on control provides a single text box for all location searches. By default, the control displays the results stacked under the search box.
CDN Example
View a working demo and follow the steps below to create your own
<script src="https://maps-sdk.trimblemaps.com/addon/trimblemaps-singlesearch-1.1.0.js"></script>
<!-- Single Search addon reference js -->
<link href="https://maps-sdk.trimblemaps.com/addon/trimblemaps-singlesearch-1.1.0.css" rel="stylesheet">
<!-- Single Search addon reference css -->
TrimbleMaps.APIKey = "YOUR_ACCESS_TOKEN";
const map = (window.map = new TrimbleMaps.Map({
container: "map",
zoom: 12.5,
center: new TrimbleMaps.LngLat(-77.01866, 38.888)
}));
const ctrl = new TrimbleMapsControl.SingleSearch({
placeholderText: "Search here",
doneTypingInterval: 700,
hideResults: true,
locationRelevance: "mapCenter",
searchOption: {
region: TrimbleMaps.Common.Region.WW,
maxResults: 30
},
markerStyle: {},
markerConfig: {},
popupConfig: {}
// Include other optional customization options
});
// Map#addControl takes an optional second argument to set the position of the control.
// If no position is specified the control defaults to `top-right`.
map.addControl(ctrl, "top-left");
Module Bundler Example
Install the npm package.
npm install --save @trimblemaps/trimblemaps-singlesearch
Make sure the CSS file is included in the page either by adding it to the <head> of your HTML file or importing it with your bundler.
Next, import and use the JS module in your code.
Note: Since the multiple add-ons are published in separate packages, the modules in each package are exported individually. You will import each module directly rather than using a single namespace variable of TrimbleMapsControl shown above in the CDN example.
import TrimbleMaps from "@trimblemaps/trimblemaps-js";
import SingleSearch from '@trimblemaps/trimblemaps-singlesearch';
TrimbleMaps.APIKey = "YOUR_KEY_HERE";
const map = new TrimbleMaps.Map({
container: "map",
zoom: 12.5,
center: new TrimbleMaps.LngLat(-77.01866, 38.888)
});
const ctrl = new SingleSearch({
placeholderText: "Search here",
doneTypingInterval: 700,
hideResults: true,
locationRelevance: "mapCenter",
searchOption: {
region: TrimbleMaps.Common.Region.WW,
maxResults: 30
},
markerStyle: {},
markerConfig: {},
popupConfig: {}
// Include other optional customization options
});
map.addControl(ctrl, "top-left");
Customization Options
| Parameter Name | Type/Values | Description |
|---|---|---|
doneTypingInterval |
Number | Default: 700 The debounce value in milliseconds. The search web service request fire rate limit to this value. |
placeholderText |
String | Default: Address Placeholder text for the search box. |
minSearchTextLength |
Number | Default: 3 If search text is longer than this value, then search can be started. |
locationRelevance |
String | Default: null Available values are “mapCenter”, “device”, or null. If it is set, map view center or device location will be used to assist search. |
hideResults |
Boolean | Default: false Hide results list or not when a result item is clicked on or enter key is pressed on a focused item. |
searchOption |
Object | Optional. See the section below. |
markerStyle |
Object | Optional. See the section below. |
markerConfig |
Object | Optional. 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.
| Parameter | Type/Values | Description |
|---|---|---|
query |
String | Default: null If it is not null, the search input box value will be ignored by the control. It is optional. |
maxResults |
Number | Default: 20 Maximum returned results. |
currentLonLat |
LngLat.L.latLng | Default: 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. |
excludedSearchTypes |
String | Default: null Comma-separated list of types to exclude from the search. |
poiCategories |
String | Default: null Comma-separated list of POI category names by which you want to filter all POI results.Note: To get supported categories, call SearchService.singleSearchGet(“poiCategories”) method. |
countries |
String | Default: null Comma-separated list of country abbreviations by which you want to filter all results. |
countryType | ["ISO", "FIPS", "GENC2", "GENC3"] | Default: null |
states |
String | Default: null Comma-separated list of state abbreviations by which you want to filter all results. |
region | [TrimbleMaps.Common.Region.NA, TrimbleMaps.Common.Region.EU, TrimbleMaps.Common.Region.WW] | Required. |
success |
Function | Optional. If it is provided, it will replace the control built-in handler method. |
failure |
Function | Optional. 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.
| Parameter | Type/Values | Description |
|---|---|---|
externalGraphic |
String | Default: 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. |
graphicHeight |
Number | Default: 26 Marker height in pixels. |
graphicWidth |
Number | Default: 26 Marker height in pixels. |
graphicXOffset |
Number | Default: -13 Marker x-direction offset. |
graphicYOffset |
Number | Default: -13 Marker y-direction offset. |
Marker Configuration
The markerConfig parameter contains options related to the creation of the marker on the map.
| Parameter | Type/Values | Description |
|---|---|---|
exclusive |
Boolean | Default: true If true, erases all other makers first. |
centerOnMap |
Boolean | Default: true Center the marker on the map. |
zoomLevel |
Number | Default: 12 Centers the marker at the zoom level. |
Popup Configuration
The popupConfig parameter contains options related to the creation of the marker popup on the map.
| Parameter | Type/Values | Description |
|---|---|---|
show |
Boolean | Default: true If true, shows popup with the marker. |
className |
String | Default: single-search CSS class name. If you change this value, you need to add your CSS class to your style file. |
offset |
Number | Popup location offset. |
closeBox |
Boolean | Default: false If true, shows the close button on the popup. |
Events
The primary method of reacting to user interaction with the add-on is through events. The full list of events is available in the API documentation.
A common scenario is to perform some action when a location is selected from the list of results by the user. This can be accomplished with the locationselected event.
TrimbleMaps.APIKey = "YOUR_ACCESS_TOKEN";
const map = new TrimbleMaps.Map({ /* map options */ });
const ctrl = new TrimbleMapsControl.SingleSearch({ /* control options */ });
map.addControl(ctrl, "top-left");
ctrl.on('locationselected', (evt) => {
// The `location` property of the event contains the location data of the
// search result selected by the user.
console.log(evt.location);
});