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

SearchBox Plugin

This plugin provides a search box functionality to your map. As the user starts typing, search results appear in the suggestions list below the input field. This functionality is enabled by the typahead functionality of Fuzzy Search.

User’s keystrokes result in requests to Fuzzy Search. A number of calls made to the service can be optimized thanks to the options: idleTimePress and minNumberOfCharacters. For example, with default settings, typing in the word "amst" (4 characters) will result in two separate API requests, if there is a delay of at least 200 ms after typing the third and fourth characters.

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

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.

The first way to use search box:

import { map } 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.fuzzySearch, 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: 200,
    minNumberOfCharacters: 3,
    searchOptions: {
        key: '<your-tomtom-search-key>'
        language: 'en-GB'
    },
    units: 'metric',
    filter: function(result[, resultIndex[, results]]) {
        return true;
    },
    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.
• units - Either 'metric' or 'imperial'. Search results will show the distance from the center of the map, this sets which units should be used.
• searchOptions - All custom options for the Search service. For all parameters please refer to https://developer.tomtom.com/search-api/search-api-documentation-search/fuzzy-search.
• filter - Only 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.

The second way to use search box:

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

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

Handling events

Search box emits 3 events:

• 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.

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.