wrld.js

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 a 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?
}
v0.1.1452