diff --git a/.npmignore b/.npmignore index 3f7adfb..76d87a0 100644 --- a/.npmignore +++ b/.npmignore @@ -10,3 +10,4 @@ babel.config.js build-copy.js CONTRIBUTING.md jsconfig.json +docs diff --git a/docs/.npmignore b/docs/.npmignore new file mode 100644 index 0000000..595e215 --- /dev/null +++ b/docs/.npmignore @@ -0,0 +1,12 @@ +pids +logs +node_modules +npm-debug.log +coverage/ +run +dist +.DS_Store +.nyc_output +.basement +config.local.js +basement_dist diff --git a/docs/src/.vuepress/components/Foo/Bar.vue b/docs/src/.vuepress/components/Foo/Bar.vue new file mode 100644 index 0000000..7ee8286 --- /dev/null +++ b/docs/src/.vuepress/components/Foo/Bar.vue @@ -0,0 +1,15 @@ + + + diff --git a/docs/src/.vuepress/components/OtherComponent.vue b/docs/src/.vuepress/components/OtherComponent.vue new file mode 100644 index 0000000..1d97c7c --- /dev/null +++ b/docs/src/.vuepress/components/OtherComponent.vue @@ -0,0 +1,3 @@ + diff --git a/docs/src/.vuepress/components/demo-component.vue b/docs/src/.vuepress/components/demo-component.vue new file mode 100644 index 0000000..7d49de7 --- /dev/null +++ b/docs/src/.vuepress/components/demo-component.vue @@ -0,0 +1,15 @@ + + + diff --git a/docs/src/.vuepress/config.js b/docs/src/.vuepress/config.js new file mode 100644 index 0000000..7ccdb7b --- /dev/null +++ b/docs/src/.vuepress/config.js @@ -0,0 +1,99 @@ +const { description } = require('../../package') + +module.exports = { + /** + * Ref：https://v1.vuepress.vuejs.org/config/#title + */ + title: 'Vue 3 Google maps', + /** + * Ref：https://v1.vuepress.vuejs.org/config/#description + */ + description: description, + + /** + * Extra tags to be injected to the page HTML `` + * + * ref：https://v1.vuepress.vuejs.org/config/#head + */ + head: [ + ['meta', { name: 'theme-color', content: '#3eaf7c' }], + ['meta', { name: 'apple-mobile-web-app-capable', content: 'yes' }], + ['meta', { name: 'apple-mobile-web-app-status-bar-style', content: 'black' }] + ], + + /** + * Theme configuration, here is the default theme configuration for VuePress. + * + * ref：https://v1.vuepress.vuejs.org/theme/default-theme-config.html + */ + themeConfig: { + repo: '', + editLinks: true, + docsDir: '', + editLinkText: '', + logo: '/assets/logo.jpg', + head: [ + ['meta', { name: 'theme-color', content: '#000' }], + ], + lastUpdated: false, + nav: [ + { + text: 'Docs', + link: '/docs/', + }, + { + text: 'Github', + link: 'https://github.com/fawmi/vue-google-maps' + }, + { + text: 'NPM', + link: 'https://www.npmjs.com/package/@fawmi/vue-google-maps' + } + ], + sidebar: [ + { + title: 'Getting started', + path: '/docs/', + collapsable: false, + sidebarDepth: 0, + }, + { + title: 'Components', + collapsable: false, + path: '/components/', + collapsable: false, + sidebarDepth: 0, + children: [ + '/components/map', + '/components/marker', + '/components/info-window', + '/components/cluster', + '/components/circle', + '/components/polygon', + '/components/polyline', + '/components/rectangle', + '/components/autocomplete', + ] + }, + { + title: 'Examples', + collapsable: false, + collapsable: false, + sidebarDepth: 0, + path: '/examples/', + children: [ + '/examples/points-in-polygon', + ] + }, + + ] + }, + + /** + * Apply plugins，ref：https://v1.vuepress.vuejs.org/zh/plugin/ + */ + plugins: [ + '@vuepress/plugin-back-to-top', + '@vuepress/plugin-medium-zoom', + ] +} diff --git a/docs/src/.vuepress/enhanceApp.js b/docs/src/.vuepress/enhanceApp.js new file mode 100644 index 0000000..8452a86 --- /dev/null +++ b/docs/src/.vuepress/enhanceApp.js @@ -0,0 +1,14 @@ +/** + * Client app enhancement file. + * + * https://v1.vuepress.vuejs.org/guide/basic-config.html#app-level-enhancements + */ + +export default ({ + Vue, // the version of Vue being used in the VuePress app + options, // the options for the root Vue instance + router, // the router instance for the app + siteData // site metadata +}) => { + // ...apply enhancements for the site. +} diff --git a/docs/src/.vuepress/public/assets/logo.jpg b/docs/src/.vuepress/public/assets/logo.jpg new file mode 100644 index 0000000..9513852 Binary files /dev/null and b/docs/src/.vuepress/public/assets/logo.jpg differ diff --git a/docs/src/.vuepress/styles/index.styl b/docs/src/.vuepress/styles/index.styl new file mode 100644 index 0000000..420feb9 --- /dev/null +++ b/docs/src/.vuepress/styles/index.styl @@ -0,0 +1,8 @@ +/** + * Custom Styles here. + * + * ref：https://v1.vuepress.vuejs.org/config/#index-styl + */ + +.home .hero img + max-width 450px!important diff --git a/docs/src/.vuepress/styles/palette.styl b/docs/src/.vuepress/styles/palette.styl new file mode 100644 index 0000000..6490cb3 --- /dev/null +++ b/docs/src/.vuepress/styles/palette.styl @@ -0,0 +1,10 @@ +/** + * Custom palette here. + * + * ref：https://v1.vuepress.vuejs.org/zh/config/#palette-styl + */ + +$accentColor = #3eaf7c +$textColor = #2c3e50 +$borderColor = #eaecef +$codeBgColor = #282c34 diff --git a/docs/src/components/README.md b/docs/src/components/README.md new file mode 100644 index 0000000..f656146 --- /dev/null +++ b/docs/src/components/README.md @@ -0,0 +1,24 @@ +# Components +[[toc]] + +`@fawmi/vue-google-maps` provides a set of Vue.js 3 components wrapping the Google Maps API v3. + +Currently `Map`, `Marker`, `InfoWindow`, `Cluster`, `Circle`, `Polygon`, `Polyline` and `Rectangle` are supported. + +Checkout the docs page for each component to see how to use it. + +[Map](./map.md) + +[Marker](./marker.md) + +[InfoWindow](./info-window.md) + +[Cluster](./cluster.md) + +[Circle](./circle.md) + +[Polygon](./polygon.md) +[Polyline](./polyline.md) +[Rectangle](./rectangle.md) + +[Autocomplete](./autocomplete.md) diff --git a/docs/src/components/autocomplete.md b/docs/src/components/autocomplete.md new file mode 100644 index 0000000..aaa9c1e --- /dev/null +++ b/docs/src/components/autocomplete.md @@ -0,0 +1,61 @@ + +# Autocomplete +[[toc]] + + +## Load Google maps places +Before using Autocomplete, you should load the places library. + +```vue{5} +createApp(App) + .use(VueGoogleMaps, { + load: { + key: "", + libraries: "places" + } + }) + .mount("#app"); + +``` + + +## Add autocomplete to your components +You can add autocomplete to your maps using GMapAutocomplete component. +```vue + + + +``` + +## Custom options +You can pass google maps auto complete options using options prop + +```vue{9} + +``` diff --git a/docs/src/components/circle.md b/docs/src/components/circle.md new file mode 100644 index 0000000..2e3fb5c --- /dev/null +++ b/docs/src/components/circle.md @@ -0,0 +1,87 @@ +# Circle +[[toc]] +## Add circle to your maps +To add circles, just add the `GMapCircle` component inside `GMapMap` component. + +```vue + + + +``` + +## Add custom circle style + +Circle style and all other circle options can be added using `options` prop. + + +```vue + + + + +``` \ No newline at end of file diff --git a/docs/src/components/cluster.md b/docs/src/components/cluster.md new file mode 100644 index 0000000..1ae37ec --- /dev/null +++ b/docs/src/components/cluster.md @@ -0,0 +1,70 @@ +# Cluster +[[toc]] +## Cluster your markers +To cluster objects you simply wrap your markers with the cluster component. + + +```vue + + +``` + +## Props +The following props can be passed to control behavior of clusters. + +### minimumClusterSize + +Defines the minimum distance of markers to cluster them + +``` js +:minimumClusterSize="2" +``` + +### styles +With styles prop, you can control style and icon of clusters. + +``` js +:styles="clusterIcon" +``` + +### zoomOnClick +Defines whether clusters should zoom in, when clicked. + +``` js +:zoomOnClick="true" +``` diff --git a/docs/src/components/info-window.md b/docs/src/components/info-window.md new file mode 100644 index 0000000..8bebd7c --- /dev/null +++ b/docs/src/components/info-window.md @@ -0,0 +1,127 @@ +# Info Window +[[toc]] +## Add info window to your components +You can create info window by passing custom HTML or Vue components as the child of `Marker` component. +```vue + + + +
I am in info window +
+ + + +``` + +## Open/close info window +You can pass `opened` prop to open and close InfoWindows. + +```vue{7} + + + +
I am in info window +
+ + + +``` + + +### Open/close info window on marker click +You can open open and close info windows after marker click, by modifying the `:opened` prop and maintaining a state variable containing ID of the opened marker. + + +Check out [this interactive example on stackblitz](https://stackblitz.com/edit/vue-google-maps-marker-w4hxvd?file=src/components/ComponentWithMap.vue). + +Example: +```vue + + + + + +``` + + +## Options +You can pass any Google map InfoWindow component using `options` prop + + +```vue{8-14} + + + +
I am in info window +
+ + + +``` diff --git a/docs/src/components/map.md b/docs/src/components/map.md new file mode 100644 index 0000000..535ff2b --- /dev/null +++ b/docs/src/components/map.md @@ -0,0 +1,137 @@ +# Map +[[toc]] +## Install + +This is the base Map component. If no props are provided, it shows an empty map component with default controls. + +```vue + +``` +Example on [stackblitz](https://stackblitz.com/edit/vue-google-maps-basic-example) + +## Provide your own style +You can provide custom map styling by providing `style` property to the `options` prop. + +You can generate custom map styles at [https://mapstyle.withgoogle.com/](https://mapstyle.withgoogle.com/) +```vue{4} + +``` + +Example on [stackblitz](https://stackblitz.com/edit/vue-google-maps-marker-ssnfbn?file=src/components/ComponentWithMap.vue) + + +## Disable ui elements +You can disable all ui components at once +```vue{4} + +``` +You can also disable specific UI components + +```vue{4-11} + +``` + + +## Access google maps instance +You can easily access Map instance by accessing map ref in your component. + +```vue + +``` + +## Add custom button +You can use the map instance to add custom buttons to your map. + +```vue + + +``` diff --git a/docs/src/components/marker.md b/docs/src/components/marker.md new file mode 100644 index 0000000..045af93 --- /dev/null +++ b/docs/src/components/marker.md @@ -0,0 +1,113 @@ +# Marker +[[toc]] + +## Add marker to your components +With a marker, you can show specific locations on the map +```vue + + + +``` + +## Enable/Disable events +You can enable or disable map events by passing props. + +```vue{9,10} + +``` + +## Register events +You can register events like click, the same as you do in your vue components + +```vue{9} + +``` + +## Add custom icon +To use custom icon, pass `:icon` prop. You can pass a local resource or an image from internet. +```vue{9} + +``` + + +You can also pass an object to the icon `prop` to define custom size and label origin: + +```vue{9-13} + +``` diff --git a/docs/src/components/polygon.md b/docs/src/components/polygon.md new file mode 100644 index 0000000..8c622d8 --- /dev/null +++ b/docs/src/components/polygon.md @@ -0,0 +1,63 @@ +# Polygon +[[toc]] + +## Add polygon to the map + +You can add polygons to the map using polygon component. + +```vue + + +``` + + +## Set polygon options +You can set polygon style and other options using `options` prop. + +```vue + + +``` \ No newline at end of file diff --git a/docs/src/components/polyline.md b/docs/src/components/polyline.md new file mode 100644 index 0000000..8add8b6 --- /dev/null +++ b/docs/src/components/polyline.md @@ -0,0 +1,73 @@ +# Polyline +[[toc]] + +## Add Polyline to the map + +You can add Polyline to the map using `GMapPolyline` component. + +```vue + + +``` + +## Make polyline editable +You can make Polyline editable using `editable` prop. + +```vue + + +``` + +## Polyline options +You can set Polyline options using `options` prop. + +```vue + + +``` diff --git a/docs/src/components/rectangle.md b/docs/src/components/rectangle.md new file mode 100644 index 0000000..4d83b3c --- /dev/null +++ b/docs/src/components/rectangle.md @@ -0,0 +1,81 @@ +# Rectangle +[[toc]] + +## Add Rectangle to your map + +You can add rectangles to your map using `GMapRectangle` component + + +```vue + + + +``` + +## Add custom Rectangle options + +Like almost all components, you can pass all available Google maps rectangle options as prop. + +```vue + + + +``` diff --git a/docs/src/components/using-vue.md b/docs/src/components/using-vue.md new file mode 100644 index 0000000..71ac45b --- /dev/null +++ b/docs/src/components/using-vue.md @@ -0,0 +1,9 @@ +# Using Vue in Markdown + +## Browser API Access Restrictions + +Because VuePress applications are server-rendered in Node.js when generating static builds, any Vue usage must conform to the [universal code requirements](https://ssr.vuejs.org/en/universal.html). In short, make sure to only access Browser / DOM APIs in `beforeMount` or `mounted` hooks. + +If you are using or demoing components that are not SSR friendly (for example containing custom directives), you can wrap them inside the built-in `` component: + +## diff --git a/docs/src/config/README.md b/docs/src/config/README.md new file mode 100644 index 0000000..63a04b9 --- /dev/null +++ b/docs/src/config/README.md @@ -0,0 +1,15 @@ +--- +sidebar: auto +--- + +# Config + +## foo + +- Type: `string` +- Default: `/` + +## bar + +- Type: `string` +- Default: `/` diff --git a/docs/src/docs/README.md b/docs/src/docs/README.md new file mode 100644 index 0000000..18b08df --- /dev/null +++ b/docs/src/docs/README.md @@ -0,0 +1,83 @@ +# Introduction +`@fawmi/vue-google-maps` provides a set of Vue.js 3 components wrapping the Google Maps API v3. + +The following components are currently supported: + +`Map`, `Marker`, `Cluster`, `InfoWindow`, `Circle`, `Polygon`, `Polyline`, `Rectangle`, `Autocomplete` + +## Install + +To install it via NPM +```bash +npm install -S @fawmi/vue-google-maps +``` + +## Basic usage +You need an API Key. Learn how to [get an Api key ](https://developers.google.com/maps/documentation/javascript/get-api-key). + +Initialise the plugin in your `main.js`: +```js +import { createApp } from 'vue' +import VueGoogleMaps from '@fawmi/vue-google-maps' + +const app = createApp(App); +app.use(VueGoogleMaps, { + load: { + key: 'YOUR_API_KEY_COMES_HERE', + }, +}).mount('#app') +``` + +Use it anywhere in your components + +```vue + + + +``` + + +## Register google maps events + +In order to use Google maps events, they should either be enabled globally + +``` +app.use(VueGoogleMaps, { + load: { + key: 'YOUR_API_KEY_COMES_HERE', + }, + autobindAllEvents: true, +}).mount('#app') +``` + +Or better yet, they should be activated when needed. + + +In this example, we enable `closeclick` event for `GMapInfoWindow` component and register the event. + +``` + +
I am in info window {{ m.id }}
+ +``` diff --git a/docs/src/examples/README.md b/docs/src/examples/README.md new file mode 100644 index 0000000..12c1972 --- /dev/null +++ b/docs/src/examples/README.md @@ -0,0 +1,10 @@ +# List + +`@fawmi/vue-google-maps` provides a set of Vue.js 3 components wrapping the Google Maps API v3. + +Currently `Map`, `Marker`, `InfoWindow`, `Polyline`, `Polygon` and `Rectangle` are supported. + +Other components are still under development. + + +Checkout getting started to read, how to install and use vue-google-maps diff --git a/docs/src/examples/introduction.md b/docs/src/examples/introduction.md new file mode 100644 index 0000000..201b960 --- /dev/null +++ b/docs/src/examples/introduction.md @@ -0,0 +1,10 @@ +# Advanced + +`@fawmi/vue-google-maps` provides a set of Vue.js 3 components wrapping the Google Maps API v3. + +Currently `Map`, `Marker`, `InfoWindow`, `Polyline`, `Polygon` and `Rectangle` are supported. + +Other components are still under development. + + +Checkout getting started to read, how to install and use vue-google-maps diff --git a/docs/src/examples/points-in-polygon.md b/docs/src/examples/points-in-polygon.md new file mode 100644 index 0000000..3525db7 --- /dev/null +++ b/docs/src/examples/points-in-polygon.md @@ -0,0 +1,77 @@ +# How to get if a clicked area is within polygon in Google Maps. + + + +[Interactive example on Condesandbox](https://stackblitz.com/edit/vue-google-maps-marker-fnzw4j?file=src%2Fcomponents%2FComponentWithMap.vue) + + + +## Example + +```bash + +// Source of JS implementation: https://github.com/mattwilliamson/Google-Maps-Point-in-Polygon/blob/master/maps.google.polygon.containsLatLng.js + + + + +``` diff --git a/docs/src/index.md b/docs/src/index.md new file mode 100644 index 0000000..2e7d04b --- /dev/null +++ b/docs/src/index.md @@ -0,0 +1,84 @@ +--- +home: true +heroImage: 'assets/logo.jpg' +tagline: Reactive Vue 3 components for Google maps. +actionText: Read Docs → +actionLink: /docs/ +--- + + + +## Installation +You can install it using npm +``` +npm install -S @fawmi/vue-google-maps +``` + +## Basic usage +You need an API Key. Learn how to [get an Api key ](https://developers.google.com/maps/documentation/javascript/get-api-key). + +### Configure Vue to use the Components + +In your `main.js` or inside a Nuxt plugin: + +```js +import { createApp } from 'vue' +import VueGoogleMaps from '@fawmi/vue-google-maps' + +const app = createApp(App); +app.use(VueGoogleMaps, { + load: { + key: 'YOUR_API_KEY_COMES_HERE', + }, +}).mount('#app') + +``` +### Use it anywhere in your components +```vue + + +``` diff --git a/package.json b/package.json index 4f47b2f..3ccaa2d 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "@fawmi/vue-google-maps", "description": "Google Map components for Vue.js 3", - "version": "0.9.2", + "version": "0.9.3", "private": false, "main": "src/main.js", "keywords": [