Skip to content

Latest commit

 

History

History
421 lines (249 loc) · 11.6 KB

API.md

File metadata and controls

421 lines (249 loc) · 11.6 KB

Table of Contents

GoongGeocoder

A geocoder component using the Goong Places API

Parameters

  • options Object
    • options.accessToken String Required. An API Key created at https://account.goong.io
    • options.origin String Use to set a custom API origin. (optional, default https://rsapi.goong.io)
    • options.goongjs Object? A goongjs instance to use when creating Markers. Required if options.marker is true.
    • options.zoom Number On geocoded result what zoom level should the map animate to. (optional, default 16)
    • options.flyTo (Boolean | Object) If false, animating the map to a selected result is disabled. If true, animating the map will use the default animation parameters. (optional, default true)
    • options.placeholder String Override the default placeholder attribute value. (optional, default Search)
    • options.proximity Object? a proximity argument: this is a geographical point given as an object with latitude and longitude properties. Search results closer to this point will be given higher priority.
    • options.trackProximity Boolean If true, the geocoder proximity will automatically update based on the map view. (optional, default true)
    • options.collapsed Boolean If true, the geocoder control will collapse until hovered or in focus. (optional, default false)
    • options.clearAndBlurOnEsc Boolean If true, the geocoder control will clear it's contents and blur when user presses the escape key. (optional, default false)
    • options.clearOnBlur Boolean If true, the geocoder control will clear its value when the input blurs. (optional, default false)
    • options.minLength Number Minimum number of characters to enter before results are shown. (optional, default 2)
    • options.limit Number Maximum number of results to show. (optional, default 5)
    • options.radius Number Distance by kilometers around search location (optional, default 3000)
    • options.marker (Boolean | Object) If true, a Marker will be added to the map at the location of the user-selected result using a default set of Marker options. If the value is an object, the marker will be constructed using these options. If false, no marker will be added to the map. Requires that options.goongjs also be set. (optional, default true)
    • options.render Function? A function that specifies how the results should be rendered in the dropdown menu. This function should accepts a single Predictions object as input and return a string. Any HTML in the returned string will be rendered.
    • options.getItemValue Function? A function that specifies how the selected result should be rendered in the search bar. This function should accept a single Place Detail object as input and return a string. HTML tags in the output string will not be rendered. Defaults to (item) => item.formatted_address.

Examples

var geocoder = new GoongGeocoder({ accessToken: goongjs.accessToken });
map.addControl(geocoder);

Returns GoongGeocoder this

addTo

Add the geocoder to a container. The container can be either a goongjs.Map or a reference to an HTML class or id.

If the container is a goongjs.Map, this function will behave identically to Map.addControl(geocoder). If the container is an HTML id or class, the geocoder will be appended to that element.

This function will throw an error if the container is not either a map or a class/id reference. It will also throw an error if the referenced HTML element cannot be found in the document.body.

For example, if the HTML body contains the element <div id='geocoder-container'></div>, the following script will append the geocoder to #geocoder-container:

var geocoder = new GoongGeocoder({ accessToken: goongjs.accessToken });
geocoder.addTo('#geocoder-container');

Parameters

  • container (String | goongjs.Map) A reference to the container to which to add the geocoder

clear

Clear and then focus the input.

Parameters

  • ev Event? the event that triggered the clear, if available

query

Set & query the input

Parameters

  • searchInput string location name or other search input

Returns GoongGeocoder this

setInput

Set input

Parameters

  • searchInput string location name or other search input

Returns GoongGeocoder this

getInput

Get input

Returns any current input

setProximity

Set proximity

Parameters

  • proximity Object The new options.proximity value. This is a geographical point given as an object with latitude and longitude properties.

Returns GoongGeocoder this

getProximity

Get proximity

Returns Object The geocoder proximity

setRenderFunction

Set the render function used in the results dropdown

Parameters

  • fn Function The function to use as a render function. This function accepts a single Predictions object as input and returns a string.

Returns GoongGeocoder this

getRenderFunction

Get the function used to render the results dropdown

Returns Function the render function

getZoom

Get the zoom level the map will move to

Returns Number the map zoom

setZoom

Set the zoom level

Parameters

  • zoom Number The zoom level that the map should animate to

Returns GoongGeocoder this

getFlyTo

Get the parameters used to fly to the selected response, if any

Returns (Boolean | Object) The flyTo option

setFlyTo

Set the flyTo options

Parameters

  • flyTo (Boolean | Object) If false, animating the map to a selected result is disabled. If true, animating the map will use the default animation parameters

getPlaceholder

Get the value of the placeholder string

Returns String The input element's placeholder value

setPlaceholder

Set the value of the input element's placeholder

Parameters

  • placeholder String the text to use as the input element's placeholder

Returns GoongGeocoder this

getMinLength

Get the minimum number of characters typed to trigger results used in the plugin

Returns Number The minimum length in characters before a search is triggered

setMinLength

Set the minimum number of characters typed to trigger results used by the plugin

Parameters

  • minLength Number the minimum length in characters

Returns GoongGeocoder this

getLimit

Get the limit value for the number of results to display used by the plugin

Returns Number The limit value for the number of results to display used by the plugin

setLimit

Set the limit value for the number of results to display used by the plugin

Parameters

  • limit Number the number of search results to return

Returns GoongGeocoder

getRadius

Get the radius value for the number of results to display used by the plugin

Returns Number The limit value for the number of results to display used by the plugin

setRadius

Set the limit value for the number of results to display used by the plugin

Parameters

  • radius Number the number of search results to return

Returns GoongGeocoder

setOrigin

Set the geocoding endpoint used by the plugin.

Parameters

  • origin Function A function which accepts an HTTPS URL to specify the endpoint to query results from.

Returns GoongGeocoder this

getOrigin

Get the geocoding endpoint the plugin is currently set to

Returns Function the endpoint URL

on

Subscribe to events that happen within the plugin.

Parameters

  • type String name of event. Available events and the data passed into their respective event objects are:- clear Emitted when the input is cleared
    • loading { query } Emitted when the geocoder is looking up a query
    • results { results } Fired when the geocoder returns a response
    • result { result } Fired when input is set
    • error { error } Error as string
  • fn Function function that's called when the event is emitted.

Returns GoongGeocoder this;

off

Remove an event

Parameters

  • type String Event name.
  • fn Function Function that should unsubscribe to the event emitted.

Returns GoongGeocoder this