Maps SDK for Web - ttPlugins.SearchBox

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 Required 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 Required 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

Object this.options

getSearchBoxHTML( ): HTMLElement

Returns the plugin container.

Returns

HTMLElement container

getValue( ): String

Returns

String The input value

onAdd(map): HTMLElement

Binds map with plugin instance.

Parameters

Name	Description
map Required Maps.Map default:None

Returns

HTMLElement container

onRemove( ): Void

Removes plugin from the map.

Returns

Void

query( ): Void

Triggers search and fills the results list

Returns

Void

removeFilter( ): Void

Remove the existing filter

Returns

Void

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 Required Object default:None	object consists of [type] and [value] properties
filterOptions.type Required String default:None	available types: 'category', 'brand'
filterOptions.value Required Object default:None	data needed for preparing a service call and for the correct display the filter inside the input

Returns

Void

setValue(value): Void

Parameters

Name	Description
value Required String default:None	The input value

Returns

Void

updateOptions(options): Void

Updates options

Parameters

Name	Description
options Required Object default:None

Returns

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

Fired when the input is restored. This happens when the user uses the arrows to navigate through the suggestions list and navigates back to the input.

tomtom.searchbox.loadingfinished

Fired when a request in the background is finished.

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

Fired when a request in the background is started.

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

Fired when result is focused.

Properties

Name	Description
event Object default:None
event.data Object default:None	The data object containing event details.
event.data.result Object default:None	The focused result.
event.data.text String default:None	The display value, same as in the searchbox input.

tomtom.searchbox.resultscleared

Fired when search results are cleared.

tomtom.searchbox.resultselected

Fired when result is selected.

Properties

Name	Description
event Object default:None
event.data Object default:None	The data object containing event details.
event.data.result Object default:None	The selected result.
event.data.text String default:None	The display value, same as in the searchbox input.

tomtom.searchbox.resultsfound

Fired when search results are found.

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.