WrldSearchbar

The WrldSearchbar is an optional widget for searching on the map. Users can search for Places (points of interest), as well as geographical locations. The searchbar can also optionally have a menu with preset options for various searches.

To configure the Places that are available to search for on a map, use the Places Designer.

Dependencies

JQuery
wrld.css
searchbar.js

For an example of how to add an WrldSearchbar to a map, see this example.

Constructor

var searchbarConfig = {
    apiKey: "your_api_key_here"
};
var searchbar = new WrldSearchbar("widget-container", map, searchbarConfig);

Argument	Type	Description
id	string	The id of the DOM element to contain the searchbar
map	`L.Wrld.map`	The map object that the searchbar controls
options	object	An object containing optional parameters, described below

Options

Options	Type	Default	Description
apiKey	string	null	A valid API key which is required by the default `placesSearchService`
mapzenApiKey	string	null	A valid Mapzen API key, required by the default `locationSearchService`
skipYelpSearch	boolean	false	Whether to ignore Yelp results when searching. By default, Yelp search results are included
outdoorSearchMenuItems	[SearchTag]	[]	“Find” options to display in the search menu when outdoors
indoorSearchMenuItems	[SearchTag]	[]	“Find” options to display in the search menu when indoors
locationJumps	[LocationJump]	[]	“Location” options to display in the search menu
placesSearchService	PlacesSearchService	*	The service to use when searching for Places, points of interest. The default searches for any Places associated with the given API key. To configure these, use the Places Designer
locationSearchService	LocationSearchService	*	The service to use when searching for geographical locations, like city names. The default uses Mapzen Search

Methods

searchbar.openMenu()

Opens the searchbar menu. The menu is only available if either the "outdoorSearchMenuItems" or "locationJumps" options were specified at construction.

searchbar.closeMenu()

Closes the searchbar menu. The menu is only available if either the "outdoorSearchMenuItems" or "locationJumps" options were specified at construction.

searchbar.clear()

Clears any search results.

Events

The following events can be listened to :

Event	Data	Description
inputchange	InputChangeEvent	Fired when the user inputs into the searchbar
search	Event	Fired when the user performs a search
searchresultsupdate	SearchResultsUpdateEvent	Fired when new search results appear
searchresultselect	SearchResultSelectEvent	Fired when a search result is clicked
searchresultsclear	Event	Fired when the search results are cleared
menuopen	Event	Fired when the menu is opened
menuclose	Event	Fired when the menu is closed
autocompleteoptionselect	AutocompleteOptionSelectEvent	Fired when the user clicks an autocomplete option

InputChangeEvent

Property	Type	Description
input	string	The text that the user has input so far.

SearchResultsUpdateEvent

Property	Type	Description
results	{ number: SearchResult }	Data for all Places matching the performed search. Each key in this object is a unique ID for the corresponding `SearchResult` value.

SearchResultSelectEvent

Property	Type	Description
results	SearchResult	Data for the Place selected by the user.

AutocompleteOptionSelectEvent

Property	Type	Description
option	AutocompleteOption	Data for the autocomplete option selected by the user.

PlacesSearchService

In order to override the default place searching, an object which implements this interface can be passed to the WrldSearchbar constructor as the "placesSearchService" option.

Any object which has the following methods can be used.

Methods

fetchAllNearbyPlaces(latLng, callback)

This method should search for nearby Places, and return them by passing them to the given callback.

Argument	Type	Description
latLng	L.LatLng	The center of the map
callback	function	A function to be called when the search is complete. The function should take an array of `SearchResult` objects as its only argument

fetchNearbyPlacesByTerm(latLng, term, callback)

This method should search for nearby Places which match the given search term. The results should be returned by passing them to the given callback.

Argument	Type	Description
latLng	L.LatLng	The center of the map
term	string	A plain text search term
callback	function	A function to be called when the search is complete. The function should take an array of `SearchResult` objects as its only argument

fetchNearbyPlacesByTag(latLng, tag, callback)

This method should search for nearby Places by tag. This is useful if a search service accepts some notion of tag or category. The results should be returned by passing them to the given callback.

Argument	Type	Description
latLng	L.LatLng	The center of the map
tag	string	A tag or category to search with, where a search service has a pre-determined set of such tags
callback	function	A function to be called when the search is complete. The function should take an array of `SearchResult` objects as its only argument

fetchAutocompleteOptions(latLng, term, callback)

This method should return Places autocomplete options for the given search term. The results should be returned by passing them to the given callback.

Argument	Type	Description
latLng	L.LatLng	The center of the map
term	string	A plain text search term
callback	function	A function to be called when the autocomplete search is complete. The function should take an array of `AutocompleteOption` objects as its only argument

fetchTagOptions(term, callback)

This method should return tag autocomplete options. This is useful if a search service accepts some notion of tag or category. The results should be returned by passing them to the given callback.

Argument	Type	Description
term	string	A plain text search term
callback	function	A function to be called when the tag autocomplete search is complete. The function should take an array of `SearchTag` objects as its only argument

LocationSearchService

In order to override the default location searching, an object which implements this interface can be passed to the WrldSearchbar constructor as the "locationSearchService" option.

Any object which has the following methods can be used.

Methods

fetchNearbyLocationsByTerm(latLng, term, callback)

This method should search for nearby locations which match the given search term. The results should be returned by passing them to the given callback.

Argument	Type	Description
latLng	L.LatLng	The center of the map
term	string	A plain text search term
callback	function	A function to be called when the search is complete. The function should take an array of `LocationSearchResult` objects as its only argument

fetchAutocompleteOptions(latLng, term, callback)

This method should return location autocomplete options for the given search term. The results should be returned by passing them to the given callback.

Argument	Type	Description
latLng	L.LatLng	The center of the map
term	string	A plain text search term
callback	function	A function to be called when the autocomplete search is complete. The function should take an array of `LocationSearchResult` objects as its only argument

Data Types

There are a few data types used by the search bar and its associated events and services. This section describes the structure of these objects, and the types of their fields.

SearchTag

Below is the structure of a SearchTag object which represents the label and icon to display, and the tag to search for. Valid iconKey values can be found here.

{
    "name": string,
    "iconKey": string,
    "searchTag": string
}

LocationJump

Below is the structure of a LocationJump object which represents the label to display in the menu, and a L.LatLng to jump to when clicked. Fields with a ? following them are optional and may be omitted.

{
    "name": string,
    "latLng": L.LatLng,

    "zoom": number?,
    "headingDegrees": number?
}

SearchResult

Below is the structure of a SearchResult object. Fields with a ? following them are optional and may be omitted.

For more details about this format, see the POI API documentation.

{
    "title": string,
    "location": {
        "latLng": L.LatLng,

        "elevation": number?,
        "isIndoor": boolean?,
        "indoorId": string?,
        "floorIndex": number?
    },
    "sourceId": any,

    "data": object?,
    "source": string?,
    "subtitle": string?,
    "iconKey": string?,
    "tags": [string]?
}

LocationSearchResult

Below is the structure of a LocationSearchResult object. Fields with a ? following them are optional and may be omitted.

{
    "title": string,
    "location": {
        "latLng": L.LatLng,

        "zoom": number?,
        "headingDegrees": number?
    }

    "subtitle": string?,
    "iconKey": string?
}

AutocompleteOption

Below is the structure of an AutocompleteOption object. Fields with a ? following them are optional and may be omitted.

{
    "title": string,
    "location": {
        "latLng": L.LatLng,

        "isIndoor": boolean?,
        "indoorId": string?,
        "floorIndex": number?
    }

    "subtitle": string?,
    "iconKey": string?
}