diff --git a/API.md b/API.md index 7e09d6f..31acdc4 100644 --- a/API.md +++ b/API.md @@ -52,71 +52,73 @@ - [setOrigin][48] - [Parameters][49] - [getOrigin][50] - - [setAutocomplete][51] + - [setAccessToken][51] - [Parameters][52] - - [getAutocomplete][53] - - [setFuzzyMatch][54] - - [Parameters][55] - - [getFuzzyMatch][56] - - [setRouting][57] - - [Parameters][58] - - [getRouting][59] - - [setWorldview][60] - - [Parameters][61] - - [getWorldview][62] - - [on][63] - - [Parameters][64] - - [off][65] + - [setAutocomplete][53] + - [Parameters][54] + - [getAutocomplete][55] + - [setFuzzyMatch][56] + - [Parameters][57] + - [getFuzzyMatch][58] + - [setRouting][59] + - [Parameters][60] + - [getRouting][61] + - [setWorldview][62] + - [Parameters][63] + - [getWorldview][64] + - [on][65] - [Parameters][66] + - [off][67] + - [Parameters][68] ## MapboxGeocoder -A geocoder component using the [Mapbox Geocoding API][67] +A geocoder component using the [Mapbox Geocoding API][69] ### Parameters -- `options` **[Object][68]** - - `options.accessToken` **[String][69]** Required. - - `options.origin` **[String][69]** Use to set a custom API origin. (optional, default `https://api.mapbox.com`) - - `options.mapboxgl` **[Object][68]?** A [mapbox-gl][70] instance to use when creating [Markers][71]. Required if `options.marker` is `true`. - - `options.zoom` **[Number][72]** On geocoded result what zoom level should the map animate to when a `bbox` isn't found in the response. If a `bbox` is found the map will fit to the `bbox`. (optional, default `16`) - - `options.flyTo` **([Boolean][73] \| [Object][68])** If `false`, animating the map to a selected result is disabled. If `true`, animating the map will use the default animation parameters. If an object, it will be passed as `options` to the map [`flyTo`][74] or [`fitBounds`][75] method providing control over the animation of the transition. (optional, default `true`) - - `options.placeholder` **[String][69]** Override the default placeholder attribute value. (optional, default `Search`) - - `options.proximity` **[Object][68]?** a proximity argument: this is +- `options` **[Object][70]** + - `options.accessToken` **[String][71]** Required. + - `options.origin` **[String][71]** Use to set a custom API origin. (optional, default `https://api.mapbox.com`) + - `options.mapboxgl` **[Object][70]?** A [mapbox-gl][72] instance to use when creating [Markers][73]. Required if `options.marker` is `true`. + - `options.zoom` **[Number][74]** On geocoded result what zoom level should the map animate to when a `bbox` isn't found in the response. If a `bbox` is found the map will fit to the `bbox`. (optional, default `16`) + - `options.flyTo` **([Boolean][75] \| [Object][70])** If `false`, animating the map to a selected result is disabled. If `true`, animating the map will use the default animation parameters. If an object, it will be passed as `options` to the map [`flyTo`][76] or [`fitBounds`][77] method providing control over the animation of the transition. (optional, default `true`) + - `options.placeholder` **[String][71]** Override the default placeholder attribute value. (optional, default `Search`) + - `options.proximity` **[Object][70]?** 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][73]** If `true`, the geocoder proximity will automatically update based on the map view. (optional, default `true`) - - `options.collapsed` **[Boolean][73]** If `true`, the geocoder control will collapse until hovered or in focus. (optional, default `false`) - - `options.clearAndBlurOnEsc` **[Boolean][73]** If `true`, the geocoder control will clear it's contents and blur when user presses the escape key. (optional, default `false`) - - `options.clearOnBlur` **[Boolean][73]** If `true`, the geocoder control will clear its value when the input blurs. (optional, default `false`) - - `options.bbox` **[Array][76]?** a bounding box argument: this is + - `options.trackProximity` **[Boolean][75]** If `true`, the geocoder proximity will automatically update based on the map view. (optional, default `true`) + - `options.collapsed` **[Boolean][75]** If `true`, the geocoder control will collapse until hovered or in focus. (optional, default `false`) + - `options.clearAndBlurOnEsc` **[Boolean][75]** If `true`, the geocoder control will clear it's contents and blur when user presses the escape key. (optional, default `false`) + - `options.clearOnBlur` **[Boolean][75]** If `true`, the geocoder control will clear its value when the input blurs. (optional, default `false`) + - `options.bbox` **[Array][78]?** a bounding box argument: this is a bounding box given as an array in the format `[minX, minY, maxX, maxY]`. Search results will be limited to the bounding box. - - `options.countries` **[string][69]?** a comma separated list of country codes to + - `options.countries` **[string][71]?** a comma separated list of country codes to limit results to specified country or countries. - - `options.types` **[string][69]?** a comma seperated list of types that filter - results to match those specified. See [https://docs.mapbox.com/api/search/#data-types][77] + - `options.types` **[string][71]?** a comma seperated list of types that filter + results to match those specified. See [https://docs.mapbox.com/api/search/#data-types][79] for available types. If reverseGeocode is enabled and no type is specified, the type defaults to POIs. Otherwise, if you configure more than one type, the first type will be used. - - `options.minLength` **[Number][72]** Minimum number of characters to enter before results are shown. (optional, default `2`) - - `options.limit` **[Number][72]** Maximum number of results to show. (optional, default `5`) - - `options.language` **[string][69]?** Specify the language to use for response text and query result weighting. Options are IETF language tags comprised of a mandatory ISO 639-1 language code and optionally one or more IETF subtags for country or script. More than one value can also be specified, separated by commas. Defaults to the browser's language settings. - - `options.filter` **[Function][78]?** A function which accepts a Feature in the [Carmen GeoJSON][79] format to filter out results from the Geocoding API response before they are included in the suggestions list. Return `true` to keep the item, `false` otherwise. - - `options.localGeocoder` **[Function][78]?** A function accepting the query string which performs local geocoding to supplement results from the Mapbox Geocoding API. Expected to return an Array of GeoJSON Features in the [Carmen GeoJSON][79] format. - - `options.externalGeocoder` **[Function][78]?** A function accepting the query string and current features list which performs geocoding to supplement results from the Mapbox Geocoding API. Expected to return a Promise which resolves to an Array of GeoJSON Features in the [Carmen GeoJSON][79] format. + - `options.minLength` **[Number][74]** Minimum number of characters to enter before results are shown. (optional, default `2`) + - `options.limit` **[Number][74]** Maximum number of results to show. (optional, default `5`) + - `options.language` **[string][71]?** Specify the language to use for response text and query result weighting. Options are IETF language tags comprised of a mandatory ISO 639-1 language code and optionally one or more IETF subtags for country or script. More than one value can also be specified, separated by commas. Defaults to the browser's language settings. + - `options.filter` **[Function][80]?** A function which accepts a Feature in the [Carmen GeoJSON][81] format to filter out results from the Geocoding API response before they are included in the suggestions list. Return `true` to keep the item, `false` otherwise. + - `options.localGeocoder` **[Function][80]?** A function accepting the query string which performs local geocoding to supplement results from the Mapbox Geocoding API. Expected to return an Array of GeoJSON Features in the [Carmen GeoJSON][81] format. + - `options.externalGeocoder` **[Function][80]?** A function accepting the query string and current features list which performs geocoding to supplement results from the Mapbox Geocoding API. Expected to return a Promise which resolves to an Array of GeoJSON Features in the [Carmen GeoJSON][81] format. - `options.reverseMode` **(distance | score)** Set the factors that are used to sort nearby results. (optional, default `distance`) - - `options.reverseGeocode` **[boolean][73]** If `true`, enable reverse geocoding mode. In reverse geocoding, search input is expected to be coordinates in the form `lat, lon`, with suggestions being the reverse geocodes. (optional, default `false`) - - `options.enableEventLogging` **[Boolean][73]** Allow Mapbox to collect anonymous usage statistics from the plugin. (optional, default `true`) - - `options.marker` **([Boolean][73] \| [Object][68])** If `true`, a [Marker][71] 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.mapboxgl` also be set. (optional, default `true`) - - `options.render` **[Function][78]?** A function that specifies how the results should be rendered in the dropdown menu. This function should accepts a single [Carmen GeoJSON][79] object as input and return a string. Any HTML in the returned string will be rendered. - - `options.getItemValue` **[Function][78]?** A function that specifies how the selected result should be rendered in the search bar. This function should accept a single [Carmen GeoJSON][79] object as input and return a string. HTML tags in the output string will not be rendered. Defaults to `(item) => item.place_name`. - - `options.mode` **[String][69]** A string specifying the geocoding [endpoint][80] to query. Options are `mapbox.places` and `mapbox.places-permanent`. The `mapbox.places-permanent` mode requires an enterprise license for permanent geocodes. (optional, default `mapbox.places`) - - `options.localGeocoderOnly` **[Boolean][73]** If `true`, indicates that the `localGeocoder` results should be the only ones returned to the user. If `false`, indicates that the `localGeocoder` results should be combined with those from the Mapbox API with the `localGeocoder` results ranked higher. (optional, default `false`) - - `options.autocomplete` **[Boolean][73]** Specify whether to return autocomplete results or not. When autocomplete is enabled, results will be included that start with the requested string, rather than just responses that match it exactly. (optional, default `true`) - - `options.fuzzyMatch` **[Boolean][73]** Specify whether the Geocoding API should attempt approximate, as well as exact, matching when performing searches, or whether it should opt out of this behavior and only attempt exact matching. (optional, default `true`) - - `options.routing` **[Boolean][73]** Specify whether to request additional metadata about the recommended navigation destination corresponding to the feature or not. Only applicable for address features. (optional, default `false`) - - `options.worldview` **[String][69]** Filter results to geographic features whose characteristics are defined differently by audiences belonging to various regional, cultural, or political groups. (optional, default `"us"`) + - `options.reverseGeocode` **[boolean][75]** If `true`, enable reverse geocoding mode. In reverse geocoding, search input is expected to be coordinates in the form `lat, lon`, with suggestions being the reverse geocodes. (optional, default `false`) + - `options.enableEventLogging` **[Boolean][75]** Allow Mapbox to collect anonymous usage statistics from the plugin. (optional, default `true`) + - `options.marker` **([Boolean][75] \| [Object][70])** If `true`, a [Marker][73] 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.mapboxgl` also be set. (optional, default `true`) + - `options.render` **[Function][80]?** A function that specifies how the results should be rendered in the dropdown menu. This function should accepts a single [Carmen GeoJSON][81] object as input and return a string. Any HTML in the returned string will be rendered. + - `options.getItemValue` **[Function][80]?** A function that specifies how the selected result should be rendered in the search bar. This function should accept a single [Carmen GeoJSON][81] object as input and return a string. HTML tags in the output string will not be rendered. Defaults to `(item) => item.place_name`. + - `options.mode` **[String][71]** A string specifying the geocoding [endpoint][82] to query. Options are `mapbox.places` and `mapbox.places-permanent`. The `mapbox.places-permanent` mode requires an enterprise license for permanent geocodes. (optional, default `mapbox.places`) + - `options.localGeocoderOnly` **[Boolean][75]** If `true`, indicates that the `localGeocoder` results should be the only ones returned to the user. If `false`, indicates that the `localGeocoder` results should be combined with those from the Mapbox API with the `localGeocoder` results ranked higher. (optional, default `false`) + - `options.autocomplete` **[Boolean][75]** Specify whether to return autocomplete results or not. When autocomplete is enabled, results will be included that start with the requested string, rather than just responses that match it exactly. (optional, default `true`) + - `options.fuzzyMatch` **[Boolean][75]** Specify whether the Geocoding API should attempt approximate, as well as exact, matching when performing searches, or whether it should opt out of this behavior and only attempt exact matching. (optional, default `true`) + - `options.routing` **[Boolean][75]** Specify whether to request additional metadata about the recommended navigation destination corresponding to the feature or not. Only applicable for address features. (optional, default `false`) + - `options.worldview` **[String][71]** Filter results to geographic features whose characteristics are defined differently by audiences belonging to various regional, cultural, or political groups. (optional, default `"us"`) ### Examples @@ -125,15 +127,15 @@ var geocoder = new MapboxGeocoder({ accessToken: mapboxgl.accessToken }); map.addControl(geocoder); ``` -Returns **[MapboxGeocoder][81]** `this` +Returns **[MapboxGeocoder][83]** `this` ### addTo Add the geocoder to a container. The container can be either a `mapboxgl.Map`, an `HTMLElement` or a CSS selector string. -If the container is a [`mapboxgl.Map`][82], this function will behave identically to [`Map.addControl(geocoder)`][83]. -If the container is an instance of [`HTMLElement`][84], then the geocoder will be appended as a child of that [`HTMLElement`][84]. -If the container is a [CSS selector string][85], the geocoder will be appended to the element returned from the query. +If the container is a [`mapboxgl.Map`][84], this function will behave identically to [`Map.addControl(geocoder)`][85]. +If the container is an instance of [`HTMLElement`][86], then the geocoder will be appended as a child of that [`HTMLElement`][86]. +If the container is a [CSS selector string][87], the geocoder will be appended to the element returned from the query. This function will throw an error if the container is none of the above. It will also throw an error if the referenced HTML element cannot be found in the `document.body`. @@ -147,7 +149,7 @@ geocoder.addTo('#geocoder-container'); #### Parameters -- `container` **([String][69] \| [HTMLElement][86] | mapboxgl.Map)** A reference to the container to which to add the geocoder +- `container` **([String][71] \| [HTMLElement][88] | mapboxgl.Map)** A reference to the container to which to add the geocoder ### clear @@ -155,7 +157,7 @@ Clear and then focus the input. #### Parameters -- `ev` **[Event][87]?** the event that triggered the clear, if available +- `ev` **[Event][89]?** the event that triggered the clear, if available ### query @@ -163,9 +165,9 @@ Set & query the input #### Parameters -- `searchInput` **[string][69]** location name or other search input +- `searchInput` **[string][71]** location name or other search input -Returns **[MapboxGeocoder][81]** this +Returns **[MapboxGeocoder][83]** this ### setInput @@ -173,9 +175,9 @@ Set input #### Parameters -- `searchInput` **[string][69]** location name or other search input +- `searchInput` **[string][71]** location name or other search input -Returns **[MapboxGeocoder][81]** this +Returns **[MapboxGeocoder][83]** this ### setProximity @@ -183,15 +185,15 @@ Set proximity #### Parameters -- `proximity` **[Object][68]** The new `options.proximity` value. This is a geographical point given as an object with `latitude` and `longitude` properties. +- `proximity` **[Object][70]** The new `options.proximity` value. This is a geographical point given as an object with `latitude` and `longitude` properties. -Returns **[MapboxGeocoder][81]** this +Returns **[MapboxGeocoder][83]** this ### getProximity Get proximity -Returns **[Object][68]** The geocoder proximity +Returns **[Object][70]** The geocoder proximity ### setRenderFunction @@ -199,15 +201,15 @@ Set the render function used in the results dropdown #### Parameters -- `fn` **[Function][78]** The function to use as a render function. This function accepts a single [Carmen GeoJSON][79] object as input and returns a string. +- `fn` **[Function][80]** The function to use as a render function. This function accepts a single [Carmen GeoJSON][81] object as input and returns a string. -Returns **[MapboxGeocoder][81]** this +Returns **[MapboxGeocoder][83]** this ### getRenderFunction Get the function used to render the results dropdown -Returns **[Function][78]** the render function +Returns **[Function][80]** the render function ### setLanguage @@ -217,21 +219,21 @@ Look first at the explicitly set options otherwise use the browser's language se #### Parameters -- `language` **[String][69]** Specify the language to use for response text and query result weighting. Options are IETF language tags comprised of a mandatory ISO 639-1 language code and optionally one or more IETF subtags for country or script. More than one value can also be specified, separated by commas. +- `language` **[String][71]** Specify the language to use for response text and query result weighting. Options are IETF language tags comprised of a mandatory ISO 639-1 language code and optionally one or more IETF subtags for country or script. More than one value can also be specified, separated by commas. -Returns **[MapboxGeocoder][81]** this +Returns **[MapboxGeocoder][83]** this ### getLanguage Get the language to use in UI elements and when making search requests -Returns **[String][69]** The language(s) used by the plugin, if any +Returns **[String][71]** The language(s) used by the plugin, if any ### getZoom Get the zoom level the map will move to when there is no bounding box on the selected result -Returns **[Number][72]** the map zoom +Returns **[Number][74]** the map zoom ### setZoom @@ -239,15 +241,15 @@ Set the zoom level #### Parameters -- `zoom` **[Number][72]** The zoom level that the map should animate to when a `bbox` isn't found in the response. If a `bbox` is found the map will fit to the `bbox`. +- `zoom` **[Number][74]** The zoom level that the map should animate to when a `bbox` isn't found in the response. If a `bbox` is found the map will fit to the `bbox`. -Returns **[MapboxGeocoder][81]** this +Returns **[MapboxGeocoder][83]** this ### getFlyTo Get the parameters used to fly to the selected response, if any -Returns **([Boolean][73] \| [Object][68])** The `flyTo` option +Returns **([Boolean][75] \| [Object][70])** The `flyTo` option ### setFlyTo @@ -255,13 +257,13 @@ Set the flyTo options #### Parameters -- `flyTo` **([Boolean][73] \| [Object][68])** If false, animating the map to a selected result is disabled. If true, animating the map will use the default animation parameters. If an object, it will be passed as `options` to the map [`flyTo`][74] or [`fitBounds`][75] method providing control over the animation of the transition. +- `flyTo` **([Boolean][75] \| [Object][70])** If false, animating the map to a selected result is disabled. If true, animating the map will use the default animation parameters. If an object, it will be passed as `options` to the map [`flyTo`][76] or [`fitBounds`][77] method providing control over the animation of the transition. ### getPlaceholder Get the value of the placeholder string -Returns **[String][69]** The input element's placeholder value +Returns **[String][71]** The input element's placeholder value ### setPlaceholder @@ -269,15 +271,15 @@ Set the value of the input element's placeholder #### Parameters -- `placeholder` **[String][69]** the text to use as the input element's placeholder +- `placeholder` **[String][71]** the text to use as the input element's placeholder -Returns **[MapboxGeocoder][81]** this +Returns **[MapboxGeocoder][83]** this ### getBbox Get the bounding box used by the plugin -Returns **[Array][76]<[Number][72]>** the bounding box, if any +Returns **[Array][78]<[Number][74]>** the bounding box, if any ### setBbox @@ -285,15 +287,15 @@ Set the bounding box to limit search results to #### Parameters -- `bbox` **[Array][76]<[Number][72]>** a bounding box given as an array in the format [minX, minY, maxX, maxY]. +- `bbox` **[Array][78]<[Number][74]>** a bounding box given as an array in the format [minX, minY, maxX, maxY]. -Returns **[MapboxGeocoder][81]** this +Returns **[MapboxGeocoder][83]** this ### getCountries Get a list of the countries to limit search results to -Returns **[String][69]** a comma separated list of countries to limit to, if any +Returns **[String][71]** a comma separated list of countries to limit to, if any ### setCountries @@ -301,15 +303,15 @@ Set the countries to limit search results to #### Parameters -- `countries` **[String][69]** a comma separated list of countries to limit to +- `countries` **[String][71]** a comma separated list of countries to limit to -Returns **[MapboxGeocoder][81]** this +Returns **[MapboxGeocoder][83]** this ### getTypes Get a list of the types to limit search results to -Returns **[String][69]** a comma separated list of types to limit to +Returns **[String][71]** a comma separated list of types to limit to ### setTypes @@ -318,15 +320,15 @@ Set the types to limit search results to #### Parameters - `types` -- `countries` **[String][69]** a comma separated list of types to limit to +- `countries` **[String][71]** a comma separated list of types to limit to -Returns **[MapboxGeocoder][81]** this +Returns **[MapboxGeocoder][83]** this ### getMinLength Get the minimum number of characters typed to trigger results used in the plugin -Returns **[Number][72]** The minimum length in characters before a search is triggered +Returns **[Number][74]** The minimum length in characters before a search is triggered ### setMinLength @@ -334,15 +336,15 @@ Set the minimum number of characters typed to trigger results used by the plugin #### Parameters -- `minLength` **[Number][72]** the minimum length in characters +- `minLength` **[Number][74]** the minimum length in characters -Returns **[MapboxGeocoder][81]** this +Returns **[MapboxGeocoder][83]** this ### getLimit Get the limit value for the number of results to display used by the plugin -Returns **[Number][72]** The limit value for the number of results to display used by the plugin +Returns **[Number][74]** The limit value for the number of results to display used by the plugin ### setLimit @@ -350,15 +352,15 @@ Set the limit value for the number of results to display used by the plugin #### Parameters -- `limit` **[Number][72]** the number of search results to return +- `limit` **[Number][74]** the number of search results to return -Returns **[MapboxGeocoder][81]** +Returns **[MapboxGeocoder][83]** ### getFilter Get the filter function used by the plugin -Returns **[Function][78]** the filter function +Returns **[Function][80]** the filter function ### setFilter @@ -366,9 +368,9 @@ Set the filter function used by the plugin. #### Parameters -- `filter` **[Function][78]** A function which accepts a Feature in the [Carmen GeoJSON][79] format to filter out results from the Geocoding API response before they are included in the suggestions list. Return `true` to keep the item, `false` otherwise. +- `filter` **[Function][80]** A function which accepts a Feature in the [Carmen GeoJSON][81] format to filter out results from the Geocoding API response before they are included in the suggestions list. Return `true` to keep the item, `false` otherwise. -Returns **[MapboxGeocoder][81]** this +Returns **[MapboxGeocoder][83]** this ### setOrigin @@ -376,15 +378,25 @@ Set the geocoding endpoint used by the plugin. #### Parameters -- `origin` **[Function][78]** A function which accepts an HTTPS URL to specify the endpoint to query results from. +- `origin` **[Function][80]** A function which accepts an HTTPS URL to specify the endpoint to query results from. -Returns **[MapboxGeocoder][81]** this +Returns **[MapboxGeocoder][83]** this ### getOrigin Get the geocoding endpoint the plugin is currently set to -Returns **[Function][78]** the endpoint URL +Returns **[Function][80]** the endpoint URL + +### setAccessToken + +Set the accessToken option used for the geocoding request endpoint. + +#### Parameters + +- `accessToken` **[String][71]** value + +Returns **[MapboxGeocoder][83]** this ### setAutocomplete @@ -392,13 +404,13 @@ Set the autocomplete option used for geocoding requests #### Parameters -- `value` **[Boolean][73]** The boolean value to set autocomplete to +- `value` **[Boolean][75]** The boolean value to set autocomplete to ### getAutocomplete Get the current autocomplete parameter value used for requests -Returns **[Boolean][73]** The autocomplete parameter value +Returns **[Boolean][75]** The autocomplete parameter value ### setFuzzyMatch @@ -406,13 +418,13 @@ Set the fuzzyMatch option used for approximate matching in geocoding requests #### Parameters -- `value` **[Boolean][73]** The boolean value to set fuzzyMatch to +- `value` **[Boolean][75]** The boolean value to set fuzzyMatch to ### getFuzzyMatch Get the current fuzzyMatch parameter value used for requests -Returns **[Boolean][73]** The fuzzyMatch parameter value +Returns **[Boolean][75]** The fuzzyMatch parameter value ### setRouting @@ -420,13 +432,13 @@ Set the routing parameter used to ask for routable point metadata in geocoding r #### Parameters -- `value` **[Boolean][73]** The boolean value to set routing to +- `value` **[Boolean][75]** The boolean value to set routing to ### getRouting Get the current routing parameter value used for requests -Returns **[Boolean][73]** The routing parameter value +Returns **[Boolean][75]** The routing parameter value ### setWorldview @@ -434,13 +446,13 @@ Set the worldview parameter #### Parameters -- `code` **[String][69]** The country code representing the worldview (e.g. "us" | "cn" | "jp", "in") +- `code` **[String][71]** The country code representing the worldview (e.g. "us" | "cn" | "jp", "in") ### getWorldview Get the current worldview parameter value used for requests -Returns **[String][69]** The worldview parameter value +Returns **[String][71]** The worldview parameter value ### on @@ -448,14 +460,14 @@ Subscribe to events that happen within the plugin. #### Parameters -- `type` **[String][69]** name of event. Available events and the data passed into their respective event objects are:- **clear** `Emitted when the input is cleared` +- `type` **[String][71]** 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][78]** function that's called when the event is emitted. +- `fn` **[Function][80]** function that's called when the event is emitted. -Returns **[MapboxGeocoder][81]** this; +Returns **[MapboxGeocoder][83]** this; ### off @@ -463,10 +475,10 @@ Remove an event #### Parameters -- `type` **[String][69]** Event name. -- `fn` **[Function][78]** Function that should unsubscribe to the event emitted. +- `type` **[String][71]** Event name. +- `fn` **[Function][80]** Function that should unsubscribe to the event emitted. -Returns **[MapboxGeocoder][81]** this +Returns **[MapboxGeocoder][83]** this [1]: #mapboxgeocoder @@ -568,76 +580,80 @@ Returns **[MapboxGeocoder][81]** this [50]: #getorigin -[51]: #setautocomplete +[51]: #setaccesstoken [52]: #parameters-18 -[53]: #getautocomplete +[53]: #setautocomplete -[54]: #setfuzzymatch +[54]: #parameters-19 -[55]: #parameters-19 +[55]: #getautocomplete -[56]: #getfuzzymatch +[56]: #setfuzzymatch -[57]: #setrouting +[57]: #parameters-20 -[58]: #parameters-20 +[58]: #getfuzzymatch -[59]: #getrouting +[59]: #setrouting -[60]: #setworldview +[60]: #parameters-21 -[61]: #parameters-21 +[61]: #getrouting -[62]: #getworldview +[62]: #setworldview -[63]: #on +[63]: #parameters-22 -[64]: #parameters-22 +[64]: #getworldview -[65]: #off +[65]: #on [66]: #parameters-23 -[67]: https://docs.mapbox.com/api/search/#geocoding +[67]: #off + +[68]: #parameters-24 + +[69]: https://docs.mapbox.com/api/search/#geocoding -[68]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object +[70]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object -[69]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String +[71]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String -[70]: https://github.com/mapbox/mapbox-gl-js +[72]: https://github.com/mapbox/mapbox-gl-js -[71]: https://docs.mapbox.com/mapbox-gl-js/api/#marker +[73]: https://docs.mapbox.com/mapbox-gl-js/api/#marker -[72]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number +[74]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number -[73]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean +[75]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean -[74]: https://docs.mapbox.com/mapbox-gl-js/api/#map#flyto +[76]: https://docs.mapbox.com/mapbox-gl-js/api/#map#flyto -[75]: https://docs.mapbox.com/mapbox-gl-js/api/#map#fitbounds +[77]: https://docs.mapbox.com/mapbox-gl-js/api/#map#fitbounds -[76]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array +[78]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array -[77]: https://docs.mapbox.com/api/search/#data-types +[79]: https://docs.mapbox.com/api/search/#data-types -[78]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function +[80]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function -[79]: https://github.com/mapbox/carmen/blob/master/carmen-geojson.md +[81]: https://github.com/mapbox/carmen/blob/master/carmen-geojson.md -[80]: https://docs.mapbox.com/api/search/#endpoints +[82]: https://docs.mapbox.com/api/search/#endpoints -[81]: #mapboxgeocoder +[83]: #mapboxgeocoder -[82]: https://docs.mapbox.com/mapbox-gl-js/api/map/ +[84]: https://docs.mapbox.com/mapbox-gl-js/api/map/ -[83]: https://docs.mapbox.com/mapbox-gl-js/api/map/#map#addcontrol +[85]: https://docs.mapbox.com/mapbox-gl-js/api/map/#map#addcontrol -[84]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement +[86]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement -[85]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors +[87]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors -[86]: https://developer.mozilla.org/docs/Web/HTML/Element +[88]: https://developer.mozilla.org/docs/Web/HTML/Element -[87]: https://developer.mozilla.org/docs/Web/API/Event +[89]: https://developer.mozilla.org/docs/Web/API/Event diff --git a/CHANGELOG.md b/CHANGELOG.md index 08faae2..5933857 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,8 @@ -## master +## HEAD + +### Features / Improvements 🚀 + +- Adds `setAccessToken` method to update the accessToken after the Geocoder has been initialized [#449](https://github.com/mapbox/mapbox-gl-geocoder/pull/449) ### Dependency update diff --git a/lib/index.js b/lib/index.js index fb5dda0..aa0d568 100644 --- a/lib/index.js +++ b/lib/index.js @@ -1008,6 +1008,22 @@ MapboxGeocoder.prototype = { return this.options.origin; }, + /** + * Set the accessToken option used for the geocoding request endpoint. + * @param {String} accessToken value + * @returns {MapboxGeocoder} this + */ + setAccessToken: function(accessToken){ + this.options.accessToken = accessToken; + this.geocoderService = mbxGeocoder( + MapboxClient({ + accessToken: this.options.accessToken, + origin: this.options.origin + }) + ); + return this; + }, + /** * Set the autocomplete option used for geocoding requests * @param {Boolean} value The boolean value to set autocomplete to diff --git a/test/test.geocoder.js b/test/test.geocoder.js index f27fbb3..e2ff973 100644 --- a/test/test.geocoder.js +++ b/test/test.geocoder.js @@ -17,7 +17,7 @@ test('geocoder', function(tt) { function setup(opts) { opts = opts || {}; - opts.accessToken = mapboxgl.accessToken; + opts.accessToken = opts.accessToken || mapboxgl.accessToken; opts.mapboxgl = opts.mapboxgl || mapboxgl; // set default to prevent warnings littering the test logs opts.enableEventLogging = false; container = document.createElement('div'); @@ -986,6 +986,21 @@ test('geocoder', function(tt) { t.end(); }); + tt.test('geocoder#setAccessToken', function(t){ + const accessToken = process.env.MapboxAccessToken; + t.plan(1); + setup({ accessToken: `${accessToken}#foo` }); + geocoder.setAccessToken(accessToken); + geocoder.query('pizza'); + geocoder.on('results', function(e) { + t.equals( + e.request.client.accessToken, + accessToken, + "new access token applied to requests" + ); + }); + }); + tt.test('geocoder#setAutocomplete', function(t){ t.plan(2);