|
| 1 | +# Quickstart |
| 2 | + |
| 3 | +## Installation |
| 4 | + |
| 5 | +You can install `@geospoc/v-mapbox-geocoder` via GitHub package registry. |
| 6 | +Note that you need to install `@mapbox/mapbox-gl-geocoder` & `v-mapbox` aswell: |
| 7 | + |
| 8 | +```bash |
| 9 | +npm login --registry=https://npm.pkg.github.com --scope=@geospoc |
| 10 | +npm i @mapbox/mapbox-gl-geocoder v-mapbox @geospoc/v-mapbox-geocoder |
| 11 | +``` |
| 12 | + |
| 13 | +## Usage |
| 14 | + |
| 15 | +Now you can add the geocoder control like other controls |
| 16 | + |
| 17 | +```html |
| 18 | +<template> |
| 19 | + <MglMap |
| 20 | + :accessToken="accessToken" |
| 21 | + :mapStyle="mapStyle" |
| 22 | + > |
| 23 | + <MglGeocoderControl |
| 24 | + :accessToken="accessToken" |
| 25 | + :input.sync="defaultInput" |
| 26 | + :mapboxgl="mapbox" |
| 27 | + container="geocoder_container_id" |
| 28 | + position="top-left" |
| 29 | + @results="handleSearch" |
| 30 | + /> |
| 31 | + </MglMap> |
| 32 | +</template> |
| 33 | + |
| 34 | +<script> |
| 35 | + import mapboxgl from 'mapbox-gl'; |
| 36 | + import { MglMap } from 'v-mapbox'; |
| 37 | + import MglGeocoderControl from '@geospoc/v-mapbox-geocoder'; |
| 38 | + // you can also import this in your main.js or nuxt.config.js |
| 39 | + // or even main/global (s)css file |
| 40 | + import '@mapbox/mapbox-gl-geocoder/dist/mapbox-gl-geocoder.css' |
| 41 | +
|
| 42 | + export default { |
| 43 | + name: 'App', |
| 44 | + components: { |
| 45 | + MglMap, |
| 46 | + MglGeocoderControl |
| 47 | + }, |
| 48 | + data() { |
| 49 | + return { |
| 50 | + accessToken: 'YOUR_ACCESS_TOKEN', |
| 51 | + mapStyle: 'YOUR_MAP_STYLE', |
| 52 | + defaultInput: 'Bodhgaya', |
| 53 | + mapbox: mapboxgl, |
| 54 | + } |
| 55 | + }, |
| 56 | + methods: { |
| 57 | + handleSearch(event) { |
| 58 | + console.log(event) |
| 59 | + } |
| 60 | + }, |
| 61 | + }; |
| 62 | +</script> |
| 63 | +``` |
| 64 | + |
| 65 | +## Props |
| 66 | + |
| 67 | +_The props that you send to the `<MglGeocoderControl />` component_ |
| 68 | + |
| 69 | +### Available properties |
| 70 | + - `accessToken` **[String][57]** Required. |
| 71 | + - `origin` **[String][57]** Use to set a custom API origin. (optional, default `https://api.mapbox.com`) |
| 72 | + - `mapboxgl` **[Object][56]?** A [mapbox-gl][58] instance to use when creating [Markers][59]. Required if `marker` is `true`. |
| 73 | + - `zoom` **[Number][60]** 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`) |
| 74 | + - `flyTo` **([Boolean][61] \| [Object][56])** 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`][62] or [`fitBounds`][63] method providing control over the animation of the transition. (optional, default `true`) |
| 75 | + - `placeholder` **[String][57]** Override the default placeholder attribute value. (optional, default `Search`) |
| 76 | + - `proximity` **[Object][56]?** a proximity argument: this is |
| 77 | + a geographical point given as an object with `latitude` and `longitude` |
| 78 | + properties. Search results closer to this point will be given |
| 79 | + higher priority. |
| 80 | + - `trackProximity` **[Boolean][61]** If `true`, the geocoder proximity will automatically update based on the map view. (optional, default `true`) |
| 81 | + - `collapsed` **[Boolean][61]** If `true`, the geocoder control will collapse until hovered or in focus. (optional, default `false`) |
| 82 | + - `clearAndBlurOnEsc` **[Boolean][61]** If `true`, the geocoder control will clear it's contents and blur when user presses the escape key. (optional, default `false`) |
| 83 | + - `clearOnBlur` **[Boolean][61]** If `true`, the geocoder control will clear its value when the input blurs. (optional, default `false`) |
| 84 | + - `bbox` **[Array][64]?** a bounding box argument: this is |
| 85 | + a bounding box given as an array in the format `[minX, minY, maxX, maxY]`. |
| 86 | + Search results will be limited to the bounding box. |
| 87 | + - `countries` **[String][57]?** a comma separated list of country codes to |
| 88 | + limit results to specified country or countries. |
| 89 | + - `types` **[String][57]?** a comma seperated list of types that filter |
| 90 | + results to match those specified. See [https://docs.mapbox.com/api/search/#data-types][65] |
| 91 | + for available types. |
| 92 | + If reverseGeocode is enabled, you should specify one type. If you configure more than one type, the first type will be used. |
| 93 | + - `minLength` **[Number][60]** Minimum number of characters to enter before results are shown. (optional, default `2`) |
| 94 | + - `limit` **[Number][60]** Maximum number of results to show. (optional, default `5`) |
| 95 | + - `language` **[String][57]?** 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. |
| 96 | + - `filter` **[Function][66]?** A function which accepts a Feature in the [Carmen GeoJSON][67] 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. |
| 97 | + - `localGeocoder` **[Function][66]?** 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][67] format. |
| 98 | + - `reverseMode` **(distance | score)** Set the factors that are used to sort nearby results. (optional, default `distance`) |
| 99 | + - `reverseGeocode` **[boolean][61]** 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`) |
| 100 | + - `enableEventLogging` **[Boolean][61]** Allow Mapbox to collect anonymous usage statistics from the plugin. (optional, default `true`) |
| 101 | + - `marker` **([Boolean][61] \| [Object][56])** If `true`, a [Marker][59] 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 `mapboxgl` also be set. (optional, default `true`) |
| 102 | + - `render` **[Function][66]?** A function that specifies how the results should be rendered in the dropdown menu. This function should accepts a single [Carmen GeoJSON][67] object as input and return a string. Any HTML in the returned string will be rendered. |
| 103 | + - `getItemValue` **[Function][66]?** A function that specifies how the selected result should be rendered in the search bar. This function should accept a single [Carmen GeoJSON][67] object as input and return a string. HTML tags in the output string will not be rendered. Defaults to `(item) => item.place_name`. |
| 104 | + - `mode` **[String][57]** A string specifying the geocoding [endpoint][68] 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`) |
| 105 | + - `localGeocoderOnly` **[Boolean][61]** 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`) |
| 106 | + |
| 107 | + |
| 108 | +[56]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object |
| 109 | + |
| 110 | +[57]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String |
| 111 | + |
| 112 | +[58]: https://github.com/mapbox/mapbox-gl-js |
| 113 | + |
| 114 | +[59]: https://docs.mapbox.com/mapbox-gl-js/api/#marker |
| 115 | + |
| 116 | +[60]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number |
| 117 | + |
| 118 | +[61]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean |
| 119 | + |
| 120 | +[62]: https://docs.mapbox.com/mapbox-gl-js/api/#map#flyto |
| 121 | + |
| 122 | +[63]: https://docs.mapbox.com/mapbox-gl-js/api/#map#fitbounds |
| 123 | + |
| 124 | +[64]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array |
| 125 | + |
| 126 | +[65]: https://docs.mapbox.com/api/search/#data-types |
| 127 | + |
| 128 | +[66]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function |
| 129 | + |
| 130 | +[67]: https://github.com/mapbox/carmen/blob/master/carmen-geojson.md |
| 131 | + |
| 132 | +[68]: https://docs.mapbox.com/api/search/#endpoints |
0 commit comments