Maps SDK for Web
tt.plugins.SearchBox
This plugin provides a search box functionality to your map.
As the user starts typing, search results appear in the list below the input field. Results list combines autocomplete and fuzzy search results.
User’s keystrokes result in requests to Fuzzy Search and Autocomplete services. A number of calls made to the service can be optimized thanks to the options: idleTimePress and minNumberOfCharacters.
CSS stylesheet
SearchBox.css - CSS declarations for SearchBox plugin. Without this stylesheet, dependant elements might appear in wrong place. It can be imported:
- in the
<head>
of your HTML document:
<link rel='stylesheet' type='text/css' href='https://api.tomtom.com/maps-sdk-for-web/cdn/plugins/SearchBox/<version>/SearchBox.css'>
- or if you're using Webpack with css-loader:
import '@tomtom-international/web-sdk-plugin-searchbox/dist/SearchBox.css';
To find current plugin's version, visit the Downloads page.
For more details on how to use the configuration options, please refer to the documentation below.
Constructor
tt.plugins.SearchBox(services, [options])
Example
{
idleTimePress: 100,
minNumberOfCharacters: 0,
searchOptions: {
key: '<your-tomtom-search-key>'
language: 'en-GB'
},
autocompleteOptions: {
key: '<your-tomtom-search-key>'
language: 'en-GB'
},
labels: {
noResultsMessage: 'No results found.'
},
distanceFromPoint: '4.3321,55.2121',
units: 'kilometers'
}
Parameters
Name | Description |
---|---|
services
Services default:None |
The services object, which you need to import beforehand. |
options
Object default:None |
The Options object. |
options.placeholder
String default:None |
Deprecated You should use options.labels.placeholder instead.
|
options.idleTimePress
Number default:200 |
The Search service call delay (in ms) after the last typed character. |
options.minNumberOfCharacters
Number default:3 |
The minimum number of characters to trigger the search call. |
options.searchOptions
Object default:None |
Options for the fuzzy search service. For full list of options please refer to fuzzySearch service documentation. |
options.autocompleteOptions
Object default:None |
Options for the autocomplete service. For full list of options please refer to autocomplete service documentation. If you pass this option, results list will be extended by the results returned by autocomplete service. They are used as filters for the fuzzy search. |
options.filterSearchResults
Function default:None |
Only those fuzzy search results that pass the test implemented in this method will be shown on the results list. |
options.noResultsMessage
String default:None |
Deprecated You should use options.labels.noResultsMessage
instead.
|
options.showSearchButton
Boolean default:true |
If set to false, search icon in the input will be hidden. |
options.cssStyleCheck
Boolean default:true |
If true, the plugin will check if required css styles are added. |
options.labels.placeholder
String default:None |
Specifies text that appears within the search box when it's empty. |
options.labels.suggestions.brand
String default:'Suggested brand' |
Specifies text that is used to mark a suggested brand. |
options.labels.suggestions.category
String default:'Suggested category' |
Specifies text that is used to mark a suggested category. |
options.labels.noResultsMessage
String default:'No results found.' |
The message shown when a given query search service returned no results or they were filtered out. |
options.distanceFromPoint
Array | Object | String default:None |
Coordinate used to calculate and display the distance for each result,
if it's not used the distance will not be displayed.
Note that when this property is used, we update the dist property (distance) in the response of Fuzzy search, which is
accessible in tomtom.searchbox.resultsfound , tomtom.searchbox.resultselected and tomtom.searchbox.resultfocused events.
It can be an Array (lng, lat), an Object {lng, lat} or a String 'lng,lat'.
The distance is returned is always in meters.
|
options.units
String default: 'kilometers' |
Units used to display the distance in the SearchBox suggestion list, it does not affect the distance in the response returned in the events payload. Can be 'kilometers' or 'miles'. Default value: 'kilometers' |
Methods
getOptions( ): Object
Returns the options object.
Returns
this.options
getSearchBoxHTML( ): HTMLElement
Returns the plugin container.
Returns
container
getValue( ): String
Returns
The input value
onAdd(map): HTMLElement
Binds map with plugin instance.
Parameters
Name | Description |
---|---|
map
Maps.Map default:None |
Returns
container
onRemove( ): Void
Removes plugin from the map.
Returns
query( ): Void
Triggers search and fills the results list
Returns
removeFilter( ): Void
Remove the existing filter
Returns
setFilter(filterOptions): Void
Set a filter as brandSet or categorySet for the search options
Example
Sample filterOptions object:
{
type: 'category',
value: {
name: 'Shop',
id: '9361'
}
}
OR
{
type: 'brand',
value: {
name: 'Decathlon'
}
}
Parameters
Name | Description |
---|---|
filterOptions
Object default:None |
object consists of [type] and [value] properties |
filterOptions.type
String default:None |
available types: 'category', 'brand' |
filterOptions.value
Object default:None |
data needed for preparing a service call and for the correct display the filter inside the input |
Returns
setValue(value): Void
updateOptions(options): Void
Events
All the class events are keys of the Events static member.
To learn more about how to listen events please refer to the Evented class.
tomtom.searchbox.inputrestored
tomtom.searchbox.loadingfinished
Properties
Name | Description |
---|---|
event
Object default:None |
|
event.data
Object default:None |
The data object containing event details. |
event.data.metadata
Object default:None |
The metadata object providing additional information associated with the event. |
event.data.metadata.triggeredBy
String default:None |
Possible values are input - when the event is triggered
by the user typing, or submit - triggered by executing
query() method or pressing 'Enter'. |
tomtom.searchbox.loadingstarted
Properties
Name | Description |
---|---|
event
Object default:None |
|
event.data
Object default:None |
The data object containing event details. |
event.data.metadata
Object default:None |
The metadata object providing additional information associated with the event. |
event.data.metadata.triggeredBy
String default:None |
Possible values are input - when the event is triggered
by the user typing, or submit - triggered by executing
query() method or pressing 'Enter'. |
tomtom.searchbox.resultfocused
Properties
tomtom.searchbox.resultscleared
tomtom.searchbox.resultselected
Properties
tomtom.searchbox.resultsfound
Properties
Name | Description |
---|---|
event
Object default:None |
|
event.data
Object default:None |
The data object containing event details. |
event.data.metadata
Object default:None |
The metadata object providing additional information associated with the event. |
event.data.metadata.triggeredBy
String default:None |
Possible values are input - when the event is triggered
by the user typing, or submit - triggered by executing
query() method or pressing 'Enter'. |
event.data.results
Object default:None |
The results object contains fuzzySearch and autocomplete (if autocompleteOptions are passed to the searchbox contructor) services responses. |
event.data.errors
Object default:None |
The errors object contains fuzzzySearch and autocomplete services error responses. |