Merge pull request #219 from mapbox/map-marker

Map marker on selected result

API.md

@@ -84,6 +84,8 @@ A geocoder component using Mapbox Geocoding API
     -   `options.localGeocoder` **[Function][55]?** 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][56] format.
     -   `options.reverseMode` **(`"distance"` \| `"score"`)** Set the factors that are used to sort nearby results. (optional, default `'distance'`)
     -   `options.reverseGeocode` **[boolean][52]?** Enable reverse geocoding. Defaults to false. Expects coordinates to be lat, lon.
+    -   `options.marker` **([Boolean][52] \| [Object][48])** If `true`, a [Marker][57] 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. (optional, default `true`)
+    -   `options.mapboxgl` **[Object][48]?** A [mapbox-gl][58] instance to use when creating [Markers][57]. Required if `options.marker` is true.
     -   `options.render` **[Function][55]?** A function that specifies how the results should be rendered in the dropdown menu
     -   `options.getItemValue` **[Function][55]?** A function that specifies how the selected result should be rendered in the search bar
 
@@ -94,7 +96,7 @@ var geocoder = new MapboxGeocoder({ accessToken: mapboxgl.accessToken });
 map.addControl(geocoder);
 ```
 
-Returns **[MapboxGeocoder][57]** `this`
+Returns **[MapboxGeocoder][59]** `this`
 
 ### query
 
@@ -104,7 +106,7 @@ Set & query the input
 
 -   `searchInput` **[string][49]** location name or other search input
 
-Returns **[MapboxGeocoder][57]** this
+Returns **[MapboxGeocoder][59]** this
 
 ### setInput
 
@@ -114,7 +116,7 @@ Set input
 
 -   `searchInput` **[string][49]** location name or other search input
 
-Returns **[MapboxGeocoder][57]** this
+Returns **[MapboxGeocoder][59]** this
 
 ### setProximity
 
@@ -124,7 +126,7 @@ Set proximity
 
 -   `proximity` **[Object][48]** The new options.proximity value. This is a geographical point given as an object with latitude and longitude properties.
 
-Returns **[MapboxGeocoder][57]** this
+Returns **[MapboxGeocoder][59]** this
 
 ### getProximity
 
@@ -140,7 +142,7 @@ Set the render function used in the results dropdown
 
 -   `fn` **[Function][55]** The function to use as a render function
 
-Returns **[MapboxGeocoder][57]** this
+Returns **[MapboxGeocoder][59]** this
 
 ### getRenderFunction
 
@@ -158,7 +160,7 @@ Look first at the explicitly set options otherwise use the browser's language se
 
 -   `language` **[String][49]** 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][57]** this
+Returns **[MapboxGeocoder][59]** this
 
 ### getLanguage
 
@@ -180,13 +182,13 @@ Set the zoom level
 
 -   `zoom` **[Number][51]** 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][57]** this
+Returns **[MapboxGeocoder][59]** this
 
 ### getFlyTo
 
 Get the parameters used to fly to the selected response, if any
 
-Returns **[MapboxGeocoder][57]** this
+Returns **[MapboxGeocoder][59]** this
 
 ### setFlyTo
 
@@ -210,7 +212,7 @@ Set the value of the input element's placeholder
 
 -   `placeholder` **[String][49]** the text to use as the input element's placeholder
 
-Returns **[MapboxGeocoder][57]** this
+Returns **[MapboxGeocoder][59]** this
 
 ### getBbox
 
@@ -226,7 +228,7 @@ Set the bounding box to limit search results to
 
 -   `bbox` **[Array][53]<[Number][51]>** a bounding box given as an array in the format [minX, minY, maxX, maxY].
 
-Returns **[MapboxGeocoder][57]** this
+Returns **[MapboxGeocoder][59]** this
 
 ### getCountries
 
@@ -242,7 +244,7 @@ Set the countries to limit search results to
 
 -   `countries` **[String][49]** a comma separated list of countries to limit to
 
-Returns **[MapboxGeocoder][57]** this
+Returns **[MapboxGeocoder][59]** this
 
 ### getTypes
 
@@ -259,7 +261,7 @@ Set the types to limit search results to
 -   `types`  
 -   `countries` **[String][49]** a comma separated list of types to limit to
 
-Returns **[MapboxGeocoder][57]** this
+Returns **[MapboxGeocoder][59]** this
 
 ### getMinLength
 
@@ -275,7 +277,7 @@ Set the minimum number of characters typed to trigger results used by the plugin
 
 -   `minLength` **[Number][51]** the minimum length in characters
 
-Returns **[MapboxGeocoder][57]** this
+Returns **[MapboxGeocoder][59]** this
 
 ### getLimit
 
@@ -291,7 +293,7 @@ Set the limit value for the number of results to display used by the plugin
 
 -   `limit` **[Number][51]** the number of search results to return
 
-Returns **[MapboxGeocoder][57]** 
+Returns **[MapboxGeocoder][59]** 
 
 ### getFilter
 
@@ -307,7 +309,7 @@ Set the filter function used by the plugin.
 
 -   `filter` **[Function][55]** A function which accepts a Feature in the [Carmen GeoJSON][56] 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][57]** this
+Returns **[MapboxGeocoder][59]** this
 
 ### on
 
@@ -322,7 +324,7 @@ Subscribe to events that happen within the plugin.
     -   **error** `{ error } Error as string`
 -   `fn` **[Function][55]** function that's called when the event is emitted.
 
-Returns **[MapboxGeocoder][57]** this;
+Returns **[MapboxGeocoder][59]** this;
 
 ### off
 
@@ -333,7 +335,7 @@ Remove an event
 -   `type` **[String][49]** Event name.
 -   `fn` **[Function][55]** Function that should unsubscribe to the event emitted.
 
-Returns **[MapboxGeocoder][57]** this
+Returns **[MapboxGeocoder][59]** this
 
 [1]: #mapboxgeocoder
 
@@ -447,4 +449,8 @@ Returns **[MapboxGeocoder][57]** this
 
 [56]: https://github.com/mapbox/carmen/blob/master/carmen-geojson.md
 
-[57]: #mapboxgeocoder
+[57]: https://docs.mapbox.com/mapbox-gl-js/api/#marker
+
+[58]: https://github.com/mapbox/mapbox-gl-js
+
+[59]: #mapboxgeocoder

CHANGELOG.md

@@ -1,9 +1,11 @@
 ## Master
+- Support for the Mapbox GL JS 0.47.0 API. This is compatible with 0.47.0 and later, and may not be compatible with earlier versions.
 - Pass `flyTo` options to the map on result selection on both map#flyTo and map#fitBounds operations [#214](https://github.com/mapbox/mapbox-gl-geocoder/pull/214)  and [#227](https://github.com/mapbox/mapbox-gl-geocoder/pull/227)
 - Obtain language from user's browser settings [#195](https://github.com/mapbox/mapbox-gl-geocoder/issues/195)
 - Localize placeholder based on language set in constructor options [#150](https://github.com/mapbox/mapbox-gl-geocoder/issues/150)
 - `trackProximity` turned on by default [#195](https://github.com/mapbox/mapbox-gl-geocoder/issues/195)
 - Bump suggestions to v1.3.4
+- Adds the `marker` constructor option that allows adding the selected result to the map as a [marker](https://docs.mapbox.com/mapbox-gl-js/api/#marker). Adding the marker to the map is now the default behavior. [#219](https://github.com/mapbox/mapbox-gl-geocoder/pull/219). 
 - Upgrade dev dependencies
 - Remove hardcoded IDs in bounding box exception list
 - Fix duplicate event bug

debug/index.js

@@ -38,8 +38,8 @@ var coordinatesGeocoder = function(query) {
     return null;
   }
   function coordinateFeature(lng, lat) {
-    var lng = Number(lng);
-    var lat = Number(lat);
+    lng = Number(lng);
+    lat = Number(lat);
     return {
       center: [lng, lat],
       geometry: {
@@ -76,7 +76,8 @@ var geocoder = new MapboxGeocoder({
   trackProximity: true,
   localGeocoder: function(query) {
     return coordinatesGeocoder(query);
-  }
+  },
+  mapboxgl: mapboxgl
 });
 
 window.geocoder = geocoder;

lib/index.js

@@ -43,6 +43,8 @@ var geocoderService;
  * @param {Function} [options.localGeocoder] 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](https://github.com/mapbox/carmen/blob/master/carmen-geojson.md) format.
  * @param {'distance'|'score'} [options.reverseMode='distance'] - Set the factors that are used to sort nearby results.
  * @param {boolean} [options.reverseGeocode] Enable reverse geocoding. Defaults to false. Expects coordinates to be lat, lon.
+ * @param {Boolean|Object} [options.marker=true]  If `true`, a [Marker](https://docs.mapbox.com/mapbox-gl-js/api/#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.
+ * @param {Object} [options.mapboxgl] A [mapbox-gl](https://github.com/mapbox/mapbox-gl-js) instance to use when creating [Markers](https://docs.mapbox.com/mapbox-gl-js/api/#marker). Required if `options.marker` is true. 
  * @param {Function} [options.render] A function that specifies how the results should be rendered in the dropdown menu
  * @param {Function} [options.getItemValue] A function that specifies how the selected result should be rendered in the search bar
  * @example
@@ -69,6 +71,8 @@ MapboxGeocoder.prototype = {
     reverseGeocode: false,
     limit: 5,
     origin: 'https://api.mapbox.com',
+    marker: true,
+    mapboxgl: null,
     collapsed: false,
     getItemValue: function(item) {
       return item.place_name
@@ -159,6 +163,15 @@ MapboxGeocoder.prototype = {
       this._map.on('moveend', this._updateProximity);
     }
 
+    this.mapMarker = null;
+    this._handleMarker = this._handleMarker.bind(this);
+
+    this._mapboxgl = this.options.mapboxgl;
+    if (!this._mapboxgl && this.options.marker) {
+      console.error("No mapboxgl detected in options. Map markers are disabled. Please set options.mapboxgl.");
+      this.options.marker = false;
+    }
+
     return el;
   },
 
@@ -180,6 +193,8 @@ MapboxGeocoder.prototype = {
       this._map.off('moveend', this._updateProximity);
     }
 
+    this._removeMarker();
+
     this._map = null;
 
     return this;
@@ -245,6 +260,10 @@ MapboxGeocoder.prototype = {
           this._map.flyTo(flyOptions);
         }
       }
+      if (this.options.marker && this._mapboxgl){
+        this._handleMarker(selected);
+      }
+
       this._eventEmitter.emit('result', { result: selected });
       this.eventManager.select(selected, this);
       this.lastSelected = selected.id;
@@ -378,9 +397,9 @@ MapboxGeocoder.prototype = {
     this._onChange();
     this._inputEl.focus();
     this._clearEl.style.display = 'none';
+    this._removeMarker();
     this.lastSelected = null;
     this._eventEmitter.emit('clear');
-    // reset the turnstile event
     this.fresh = true;
   },
 
@@ -682,6 +701,37 @@ MapboxGeocoder.prototype = {
     return this;
   },
 
+  /**
+   * Handle the placement of a result marking the selected result
+   * @private
+   * @param {Object} selected the selected geojson feature
+   * @returns {MapboxGeocoder} this
+   */
+  _handleMarker: function(selected){
+    // clean up any old marker that might be present
+    this._removeMarker();
+    var defaultMarkerOptions = {
+      color: '#4668F2'
+    }
+    var markerOptions = extend({}, defaultMarkerOptions, this.options.marker)
+    this.mapMarker = new this._mapboxgl.Marker(markerOptions);
+    this.mapMarker
+      .setLngLat(selected.center)
+      .addTo(this._map);
+    return this;
+  },
+
+  /**
+   * Handle the removal of a result marker
+   * @private
+   */
+  _removeMarker: function(){
+    if (this.mapMarker){
+      this.mapMarker.remove();
+      this.mapMarker = null;
+    }
+  },
+
   /**
    * Subscribe to events that happen within the plugin.
    * @param {String} type name of event. Available events and the data passed into their respective event objects are: