Skip to content

Sohaib-Sherif/destiny-maps

 
 

Repository files navigation

npm bundle size

This is a lightweight Google Maps plugin for Vue.

⚠️ This plugin is in development, so please let me know if you find any errors.

Credit

This library is originally forked from x5-maps which is a work done by Keagan Chisnall, you can checkout his tutorial creating a COVID Heatmap on medium and give him a clap.

Installation

# npm
npm install destiny-maps

Deployment

This plugin can be installed like any Vue plugin:

import destinyMaps from 'destiny-maps'
// Option 1: Just your key
Vue.use(destinyMaps, 'YOUR_GOOGLE_KEY')
// Option 2: With libraries
Vue.use(destinyMaps, { key: 'YOUR_GOOGLE_KEY', libraries: ['places'] })

new Vue({
  el: '#app',
  render: (h) => h(App),
})

⚠️ This plugin is not transpiled! If you want it compatible with IE, Edge, and Safari, you need to add this to your vue.config.js file:

module.exports = {
  transpileDependencies: ['destiny-maps'],
}

Usage

<template>
  <gmaps-map>
    <gmaps-marker :position="{ lat: -27, lng: 153 }" />
  </gmaps-map>
</template>
import { gmapsMap, gmapsMarker } from 'destiny-maps'

export default {
  components: { gmapsMap, gmapsMarker },
}

Provided Components

Some pre-built components have been provided for general use, or as examples for those who wish to take them further.

Map

Map

Maps can take many options. zoom is defaulted to 12 and center is defaulted to Brisbane (as these options are required).

This component supports the following events:

  • @boundsChanged returns new bounds
  • @centerChanged returns new center
  • @zoomChanged returns new zoom level
  • @click returns event
  • @doubleClick returns event
  • @rightClick returns event
  • @mouseover returns event
  • @mouseout returns event
<template>
  <gmaps-map :options="mapOptions" />
</template>

<script>
  import { gmapsMap } from 'destiny-maps'

  export default {
    components: { gmapsMap },
    data: () => ({
      mapOptions: {
        center: { lat: -27.47, lng: 153.025 },
        zoom: 12,
      },
    }),
  }
</script>

Marker

Marker

Markers are placed within Maps and can take many options. A position option is required within the options prop or as its own prop.

This component supports the following events:

  • @move returns new position { lat, lng }
  • @click returns event
  • @doubleClick returns event
  • @rightClick returns event
  • @positionChanged (depreciated) returns new position
Props Type Default Description
options* Object - An object of Google Maps Marker options
icon String - URL of the marker icon to be used
label String - Marker label
opacity Number 1.0 Opacity of the marker
position Object - An object that has lat and lng properties
title String - Marker title (shown on hover)
visible Boolean true If marker is visible
zIndex Number - Override position in DOM

* If you want to change values on the fly, use the named props instead of within the options prop. Changing named props will trigger an update.

<template>
  <gmaps-map>
    <gmaps-marker v-for="(item, i) in items" :key="i" :options="item.options" />
  </gmaps-map>
</template>

<script>
  import { gmapsMap, gmapsMarker } from 'destiny-maps'

  export default {
    components: { gmapsMap, gmapsMarker },
    data: () => ({
      items: [
        { options: { position: { lat: -27.41, lng: 153.01 } } },
        { options: { position: { lat: -27.42, lng: 153.02 } } },
        ...,
        { options: { position: { lat: -27.48, lng: 153.08 } } },
        { options: { position: { lat: -27.49, lng: 153.09 } } },
      ],
    }),
  }
</script>

InfoWindow

InfoWindow

InfoWindows are placed with Maps can take a few options. A position option is required.

They are used to put HTML in and have a close/dismiss button built-in.

This component only supports a @closed event (for when someone closes the window)

<template>
  <gmaps-map :options="mapOptions">
    <gmaps-info-window :options="options">
      <p>Example Text</p>
    </gmaps-info-window>
  </gmaps-map>
</template>

<script>
  import { gmapsMap, gmapsInfoWindow } from 'destiny-maps'

  export default {
    components: { gmapsMap, gmapsInfoWindow },
    data: () => ({
      options: {
        position: { lat: -27.46, lng: 153.02 },
      },
      mapOptions: {
        center: { lat: -27.47, lng: 153.025 },
        zoom: 12,
      },
    }),
  }
</script>

Popup

Popup

A Popup is a custom DOM Element. It is here primarily as an example of what is needed when creating your own map objects, but serves as a cleaner InfoWindow for Vue.

It takes the following props:

  • position (req'd)
  • background (style)
  • height (style)
  • width (style)

All events are registered from the markup/component you place inside it rather than the popup itself.

<template>
  <gmaps-map :options="mapOptions">
    <gmaps-popup :position="position" background="#BBF0FF">
      <span @click="doSomething()">Do Something</span>
    </gmaps-popup>
  </gmaps-map>
</template>

<script>
  import { gmapsMap, gmapsPopup } from 'destiny-maps'

  export default {
    components: { gmapsMap, gmapsPopup },
    data: () => ({
      position: { lat: -27.46, lng: 153.02 },
      mapOptions: {
        center: { lat: -27.47, lng: 153.025 },
        zoom: 12,
      },
    }),
  }
</script>

Heatmap

Heatmap

Heatmaps are placed within Maps and have several props which are derived from Google's Heatmap Options. Some are named differently as they have been enhanced/simplified.

Props Type Default Description
items Array<Object> required An array of objects that has lat and lng properties
colors Array<String> - An array of one or more colors to color heatmap e.g. ['red','#0F0','rgba(0,0,0,0)`]
dissipating Boolean true Specifies whether heatmaps dissipate on zoom
opacity Number 0.6 Opacity of the heatmap
maxIntensity Number - Number of points in one spot to reach "maximum heat" color
radius Number - The radius of influence for each data point, in pixels
weightProp String - The property of items that should be used as the weight (Numbers > 0)

This component does not have any events.

** Note require to include the "visualization" library as described in Deployment

<template>
  <gmaps-map>
    <gmaps-heatmap :data="items" :opacity="0.8" />
  </gmaps-map>
</template>

<script>
  import { gmapsMap, gmapsHeatmap } from 'destiny-maps'

  export default {
    components: { gmapsMap, gmapsHeatmap },
    data: () => ({
      items: [
        { lat: -27.41, lng: 153.01 },
        { lat: -27.42, lng: 153.02 },
        ...,
        { lat: -27.48, lng: 153.08 },
        { lat: -27.49, lng: 153.09 },
      ],
    }),
  }
</script>

Polylines / Polygons

Polyline Polygon

Polylines/polygons are placed within Maps and have several props which are derived from Google's Polyline Options and Polygon Options.

This component supports the following events:

Props Type Default Description
clickable Boolean true Indicates whether this Polyline handles mouse events
draggable Boolean false Allow the shape to be dragged over the map
editable Boolean false Allow editing the shape by dragging the control points
fillColor String black (Only polygons) The fill color ***
fillOpacity Number 0.3 (Only polygons) The fill opacity between 0.0 and 1.0
geodesic Boolean false When true, lines will follow the curvature of the Earth
icons Array [] (Only polylines) Add icons along your path **
path Array required Path points (objects with lat and lng properties)
strokeColor String black The stroke color ***
strokePosition Number 0 (Only polygons) The stroke position along the path (0 = CENTER / 1 = INSIDE / 2 = OUTSIDE)
strokeOpacity Number 1.0 The stroke opacity between 0.0 and 1.0
strokeWeight Number - The stroke width in pixels
visible Boolean true Whether this polyline is visible on the map
zIndex Number 0 The zIndex compared to other polys

** Note this is one of those things you're surprised Google couldn't do right. It doesn't take images like all the rest of the icon properties of other components. Here's their example
*** All CSS3 colors are supported except for extended named colors

<template>
  <gmaps-map>
    <gmaps-polygon :path="items" :strokeColor="blue" :fillColor="red" />
    <gmaps-polyline :path="items" :strokeColor="blue" />
  </gmaps-map>
</template>

<script>
  import { gmapsMap, gmapsPolyline, gmapsPolygon } from 'destiny-maps'

  export default {
    components: { gmapsMap, gmapsPolyline, gmapsPolygon },
    data: () => ({
      items: [
        { lat: -27.41, lng: 153.01 },
        { lat: -27.42, lng: 153.02 },
        ...,
        { lat: -27.48, lng: 153.08 },
        { lat: -27.49, lng: 153.09 },
      ],
    }),
  }
</script>

Rectangles / Circles

Rectangles/Circles

Rectangles/circles are placed within Maps and have several props which are derived from Google's Rectangle Options and Circle Options.

This component supports the following events:

Props Type Default Description
bounds Array required (Only rectangles) Position of your rectangle { east, north, south, west }
center Object required (Only circles) The center of the Circle (object with lat and lng properties)
radius Number required (Only circles) The radius in meters on the Earth's surface
clickable Boolean true Indicates whether this Polyline handles mouse events
draggable Boolean false Allow the shape to be dragged over the map
editable Boolean false Allow editing the shape by dragging the control points
fillColor String black The fill color ***
fillOpacity Number 0.3 The fill opacity between 0.0 and 1.0
strokeColor String black The stroke color ***
strokePosition Number 0 The stroke position along the path (0 = CENTER / 1 = INSIDE / 2 = OUTSIDE)
strokeOpacity Number 1.0 The stroke opacity between 0.0 and 1.0
strokeWeight Number - The stroke width in pixels
visible Boolean true Whether this polyline is visible on the map
zIndex Number 0 The zIndex compared to other polys

*** All CSS3 colors are supported except for extended named colors

<template>
  <gmaps-map>
    <gmaps-rectangle :bounds="bounds" :strokeColor="blue" :fillColor="red" />
    <gmaps-circle :center="center" :radius="radius" :strokeColor="green" :fillColor="yellow" />
  </gmaps-map>
</template>

<script>
  import { gmapsMap, gmapsRectangle, gmapsCircle } from 'destiny-maps'

  export default {
    components: { gmapsMap, gmapsPolyline, gmapsPolygon },
    data: () => ({
      bounds: {
        east: 153.12,
        north: -27.44,
        west: 153.0,
        south: -27.58,
      },
      center: { lat: -27.479, lng: 152.937 },
      radius: 5000,
    }),
  }
</script>



Google Places Library (and $GMaps())

As mentioned above, additional libraries can be used in conjunction with this package, and as an example, this is how you would include the Places Library.

// main.js
Vue.use(destinyMaps, { key: 'YOUR_GOOGLE_KEY', libraries: ['places'] })

⚠️ This is an example taken from a project of mine; you may be able to find a more efficient way to do this. It is focused around using the AutocompleteService.

ℹ️ $GMaps() is the little promise that returns the Google maps object once the Google Maps code has successfully loaded. This is the little trick with getting it to work with Vue and is what you need to access the maps object references in all of the Google Maps documentation.

<template>
  ...
</template>

<script>
  // I leave these as external variables so they can be used inside
  // my arrow functions without confusing the "this" context.
  let PlacesService
  let PlacesServiceOK

  export default {
    methods: {
      query(input) {
        return new Promise((resolve, reject) => {
          PlacesService.getPlacePredictions({ input }, (results, status) => {
            if (status !== PlacesServiceOK) reject(new Error(status))
            else resolve(results)
          })
        })
      },
    },
    // The `maps` object from Google is only available after the pages
    // has been loaded; which hopefully happens before mounted() but
    // that is not guaranteed. That is why I use the `$GMaps()` promise
    // which returns the `maps` object once the Google code has loaded.
    mounted() {
      this.$GMaps().then((maps) => {
        PlacesServiceOK = maps.places.PlacesServiceStatus.OK
        PlacesService = new maps.places.AutocompleteService()
      })
    },
  }
</script>


Custom map slots

While you shouldn't see these for too long while the map loads (if at all), there are two customisable slots: Loading and Error.

<template>
  <gmaps-map>
    <template v-slot:loading>
      <div>
        <span>This is now loading...</span>
      </div>
    </template>
    <template v-slot:error="{ error }">
      <div>
        <span>You broke it: {{ error }}</span>
      </div>
    </template>
  </gmaps-map>
</template>


Authors

License

This project is licensed under the MIT License - see the LICENSE.md file for details

About

A lightweight Google Maps plugin for Vue

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Vue 84.2%
  • JavaScript 11.7%
  • SCSS 3.1%
  • HTML 1.0%