eegeo.js

EegeoSearchbar

The EegeoSearchbar 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
  • eegeo.css
  • searchbar.js

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

Constructor

var searchbarConfig = {
    apiKey: "your_api_key_here"
};
var searchbar = new EegeoSearchbar("widget-container", map, searchbarConfig);
Argument Type Description
id string The id of the DOM element to contain the searchbar
map L.eeGeo.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 [SearchMenuItem] [] “Find” options to display in the search menu when outdoors
indoorSearchMenuItems [SearchMenuItem] [] “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 EegeoSearchbar constructor as the "placesSearchService" option.

Any object which has the following methods can be used.

Methods

fetchAllNearbyPlaces(callback)

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

Argument Type Description
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(term, callback)

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

Argument Type Description
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(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
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

LocationSearchService

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

Any object which has the following methods can be used.

Methods

fetchNearbyLocationsByTerm(term, callback)

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

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.

SearchMenuItem

Below is the structure of a SearchMenuItem object which represents the label and icon to display for this option in the menu, and the tag to search for when clicked. 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,
    "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.

{
    "data": {
        "icon_key": string,
        "id": number,
        "title": string,
        "subtitle": string,
        "tags": [string],
        "lat": number,
        "lon": number,
        "height_offset": number?,
        "indoor": boolean?,
        "indoor_id": string?,
        "floor_id": number?,
        "user_data": object?,
    },
    "source": string,
    "sourceId": any
}

LocationSearchResult

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

{
    "iconKey": string,
    "label": string,
    "value": {
        "location": {
            "latLng": L.LatLng,

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

    "subtitle": string?
}

AutocompleteOption

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

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

        "floorIndex": number?,
        "isIndoors": boolean?,
        "indoorId": string?
    }
}
v0.1.1111