SearchBox Plugin

This plugin provides a search box functionality to your map (@tomtom-international/web-sdk-maps).

As the user starts typing, search results appear in the list below the input field. Results list combines autocomplete and fuzzy search results.

The user 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.

For more details on how to use the configuration options, please refer to the documentation: https://developer.tomtom.com/maps-sdk-web-js/documentation#ttPlugins.SearchBox

Please note that from version 3.0.0 this plugin only works with @tomtom-international/web-sdk-maps@6.*.*, if you are using @tomtom-international/web-sdk-maps@5.*.* please use version 2.*.*

Instalation

Just do:

npm i @tomtom-international/web-sdk-plugin-searchbox

You must also include the search box stylesheet in your project. It's located here:

node_modules/@tomtom-international/web-sdk-plugin-searchbox/dist/SearchBox.css

Usage

There are two ways to include search box into your page.

1. Embed it into the map.
2. Get the HTML container and place it wherever you need on your page.

1. Using searchbox with Maps library:

import tt from '@tomtom-international/web-sdk-maps';
import { services } from '@tomtom-international/web-sdk-services';
import SearchBox from '@tomtom-international/web-sdk-plugin-searchbox';

const ttSearchBox = new SearchBox(services, options);
map.addControl(ttSearchBox, 'top-left');

Note, that you need to pass the Tomtom services instance to the search box constructor. The second parameter are the options. They allow you to customize how search box behaves. Options (except searchOptions.key) are not mandatory, we provide default ones. Example options:

{
    idleTimePress: 100,
    minNumberOfCharacters: 0,
    searchOptions: {
        key: '<your-tomtom-search-key>'
        language: 'en-GB'
    },
    autocompleteOptions: {
        key: '<your-tomtom-search-key>'
        language: 'en-GB'
    },
    noResultsMessage: 'No results found.'
}

• idleTimePress - Search service call delay (in ms) after the last typed character.
• minNumberOfCharacters - The minimum number of characters to trigger the search call.
• searchOptions - Options for the fuzzy search service. For full list of options please refer to https://developer.tomtom.com/maps-sdk-web-js/documentation#Services.services.fuzzySearch.
• autocompleteOptions - Options for the autocomplete service. For full list of options please refer to https://developer.tomtom.com/maps-sdk-web-js/documentation#Services.services.autocomplete. If you pass this option, results list will be extended by the results returned by autocomplete service. When choosen, autocomplete result is used as filter for the fuzzy search.
• filterSearchResults - Only those fuzzy search results that pass the test implemented in this method will be shown on the results list.
• noResultsMessage - The message shown when a given query Search service returned no results or they were filtered out.

Using searchbox as independent element

import { services } from '@tomtom-international/web-sdk-services';
import SearchBox from '@tomtom-international/web-sdk-plugin-searchbox';

const ttSearchBox = new SearchBox(services, options);
const searchBoxHTML = ttSearchBox.getSearchBoxHTML();
//Attach searchboxHTML to your page

Handling events

Search box emits 7 different events:

• tomtom.searchbox.inputrestored - Triggered 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.resultfocused - Fired when result is focused.
• tomtom.searchbox.resultscleared - Triggered when the clear button is clicked.
• tomtom.searchbox.resultselected - Triggered when the user selects an element on the results list. It is fired after either clicking on an element or highlighting it using arrow keys and clicking the Enter button.
• tomtom.searchbox.resultsfound - Triggered when the search engine finds results.
• tomtom.searchbox.loadingstarted - Triggered when a request to search services is triggered in the background.
• tomtom.searchbox.loadingfinished - Triggered when a request to search services is finished(resolved) in the background.

If you want to subscribe for the event:

ttSearchBox.on('tomtom.searchbox.resultsfound', function(data) {
    console.log(data);
});

Updating options programatically

If you have initialized the search box and you want to change options later, you can do the following:

ttSearchBox.getOptions() //if you need old options, you can also retrieve them
ttSearchBox.updateOptions(newOptions)
ttSearchBox.query()

This query method triggers the search with updated options. This is necessary if you want to update results for the user with new options.