From e64f9819dda9f94465bcbf561d7620748c888dc4 Mon Sep 17 00:00:00 2001 From: cybice Date: Tue, 31 Jan 2017 00:46:13 +0300 Subject: [PATCH] New documentation begin --- API.md | 320 +++++++++++++++++++++++++++++++++++++++++++++++++++++ DOC.md | 30 +++++ README.md | 324 +----------------------------------------------------- 3 files changed, 353 insertions(+), 321 deletions(-) create mode 100644 API.md create mode 100644 DOC.md diff --git a/API.md b/API.md new file mode 100644 index 0000000..13910db --- /dev/null +++ b/API.md @@ -0,0 +1,320 @@ +## GoogleMap API + +### parameters + +#### apiKey (string) (_Deprecated use bootstrapURLKeys_) + +Google maps api key. (Optional, but your map will be rate-limited with no key) + +#### bootstrapURLKeys (object) + +Example: + +```javascript + +``` + +#### defaultCenter (array or object) + +`[lat, lng]` or `{ lat: lat, lng: lng}` +Default lat/lng at which to center the map - changing this prop throws a warning + +#### center (array or object) + +`[lat, lng]` or `{ lat: lat, lng: lng}` +Lat/lng at which to center the map + +#### defaultZoom: (number) + +Default map zoom level - changing this prop throws a warning + +#### zoom (number) + +Map zoom level + +#### hoverDistance (number) + +Default: 30 + +#### margin (array) + +In onChange callback, gives you a marginBounds argument property, where lat lng will be shifted using margin you have set. For example, you could use a simple check pointInRect to not show Markers near map bounds. + +#### debounced (bool) + +Default: true + +#### layerTypes (string[]) + +You can add some "layers" for map like a +[traffic](https://developers.google.com/maps/documentation/javascript/examples/layer-traffic) or +[transit](https://developers.google.com/maps/documentation/javascript/examples/layer-transit) + +```javascript +layerTypes={['TrafficLayer', 'TransitLayer']} +``` + +### callbacks + +#### options (func|object) + +Set map options such as controls positions / styles, etc. + +Example: + +```javascript +createMapOptions: function (maps) { + return { + panControl: false, + mapTypeControl: false, + scrollwheel: false, + styles: [{ stylers: [{ 'saturation': -100 }, { 'gamma': 0.8 }, { 'lightness': 4 }, { 'visibility': 'on' }] }] + } + } + + +``` +See "Custom map options example" in Examples below for a further example. + +#### onClick (func) + +``` +({ x, y, lat, lng, event }) +``` + +The `event` prop in args is the outer div onClick event, not the gmap-api 'click' event. + +Example: + + ```javascript + _onClick = ({x, y, lat, lng, event}) => console.log(x, y, lat, lng, event) + // ES5 users + function _onClick(obj){ console.log(obj.x, obj.y, obj.lat, obj.lng, obj.event);} + + + ``` + +#### onBoundsChange (func) (_Deprecated use onChange_) + +``` +({ center, zoom, bounds, marginBounds }) +``` +``` +[lat, lng] = center; +[topLat, leftLng, bottomLat, rightLng] = bounds; +``` + +#### resetBoundsOnResize (bool) + +When true this will reset the map bounds if the parent resizes. + +Default: false + +#### onChildClick (func) + +#### onChildMouseEnter (func) + +#### onChildMouseLeave (func) + +#### onZoomAnimationStart (func) + +#### onZoomAnimationEnd (func) + +#### onMapTypeIdChange (func) +When the user changes the map type (HYBRID, ROADMAP, SATELLITE, TERRAIN) this fires + +#### distanceToMouse (func) + +#### googleMapLoader (func) + +#### onGoogleApiLoaded (func) +Directly access the maps API - *use at your own risk!* + +```javascript + console.log(map, maps)} /> +``` + +To prevent warning message add _yesIWantToUseGoogleMapApiInternals_ property to GoogleMap + +```javascript + console.log(map, maps)} + yesIWantToUseGoogleMapApiInternals + /> + ``` + +## Child Component API + +### parameters + +#### lat (number) +Latitude to place the marker component + +#### lng (number) +Longitude to place the marker component + +#### $hover (bool) [automatic] +GoogleMap passes a $hover prop to hovered components. To detect hover it an uses internal mechanism, explained in x_distance_hover example + +Example: +```javascript +render() { + const style = this.props.$hover ? greatPlaceStyleHover : greatPlaceStyle; + + return ( +
+ {this.props.text} +
+ ); + } + ``` + + +## Utility functions + +#### fitBounds (func) + Use fitBounds to get zoom and center. + +Example: + +```javascript +import { fitBounds } from 'google-map-react/utils'; + +const bounds = { + nw: { + lat: 50.01038826014866, + lng: -118.6525866875 + }, + se: { + lat: 32.698335045970396, + lng: -92.0217273125 + } +}; + +// Or + +const bounds = { + ne: { + lat: 50.01038826014866, + lng: -118.6525866875 + }, + sw: { + lat: 32.698335045970396, + lng: -92.0217273125 + } +}; + +const size = { + width: 640, // Map width in pixels + height: 380, // Map height in pixels +}; + +const {center, zoom} = fitBounds(bounds, size); +``` + +#### tile2LatLng (func) + +#### latLng2Tile (func) + +#### getTilesIds (func) + +## Tips + +### My map doesn't appear + +Make sure the container element has width and height. The map will try to fill the parent container, but if the container has no size, the map will collapse to 0 width / height. + +### Positioning a marker + +Initially any map object has its top left corner at lat lng coordinates. It's up to you to set the object origin to 0,0 coordinates. + +Example (centering the marker): + +```javascript +const MARKER_SIZE = 40; +const greatPlaceStyle = { + position: 'absolute', + width: MARKER_SIZE, + height: MARKER_SIZE, + left: -MARKER_SIZE / 2, + top: -MARKER_SIZE / 2 +} +``` + +```javascript +render() { + return ( +
+ {this.props.text} +
+ ); +} +``` + +### Rendering in a modal + +If at the moment of GoogleMap control created, a modal has no size (width,height=0) or/and not displayed, the simple solution is to add something like this in render: + +```javascript +render() { + return this.props.modalIsOpen + ? + : null; +} +``` + +### Adding a searchbox + +```javascript +import React from 'react'; + +export default class SearchBox extends React.Component { + static propTypes = { + placeholder: React.PropTypes.string, + onPlacesChanged: React.PropTypes.func + } + render() { + return ; + } + onPlacesChanged = () => { + if (this.props.onPlacesChanged) { + this.props.onPlacesChanged(this.searchBox.getPlaces()); + } + } + componentDidMount() { + var input = React.findDOMNode(this.refs.input); + this.searchBox = new google.maps.places.SearchBox(input); + this.searchBox.addListener('places_changed', this.onPlacesChanged); + } + componentWillUnmount() { + this.searchBox.removeListener('places_changed', this.onPlacesChanged); + } +} +``` + +You will need to preload the google maps API, but `google-map-react` checks if the base api is already loaded, +and if so, uses it, so it won't load a second copy of the library. + +```html + +``` + +### Override the default minimum zoom + +*WARNING*: Setting these options can break markers calculation, causing no homeomorphism between screen coordinates and map. + +You can use the `minZoomOverride` associated with the `minZoom` in the custom map options to prevent a minimum zoom from being calculated: + +```javascript +function createMapOptions() { + return { + minZoomOverride: true, + minZoom: 2, + }; +} +``` diff --git a/DOC.md b/DOC.md new file mode 100644 index 0000000..d7cea3a --- /dev/null +++ b/DOC.md @@ -0,0 +1,30 @@ +# Documentation + +Here I'll try to explain why some methods in google map react are needed and how to use them. + +For all examples I'll use [recompose](github.com/acdlite/recompose) +and you must understand what `css-modules` is. + +## Simple example. + +[Simple example](http://www.webpackbin.com/N1N_45Owz) + +At `Map.js` you will see the smallest possible boilerplate for GoogleMapReact component, + +And a `MyMarker.js` is a simple React component. + +I highly recommend you to use GoogleMapReact as a controllable component, +and always provide `center`, `zoom` and `onChange` props. (_see withState_) + +## Whats wrong with "Simple example" above + +The wrong part is that React components are placed on the map positioning from top, left corner. + +In most cases it's not the expected behaviour, so we need to change the MyMarker position by changing +it's `position` and `left`, `top` css properties, or use `flex` as like as in this example. + +[Good position](http://www.webpackbin.com/VJBKkj_vM) + +Now `MyMarker` centered well, see the `myMarker.css` css changes and `MyMarker.js` layout change. + +## To be continued diff --git a/README.md b/README.md index 0805391..d667671 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,6 @@ This algorithm allows you to tweak hover probability of map objects, for example ## Known Issues -* Small icons jiggle on Firefox (I don't see this in my older 'GoogleMap' version, so I will find the problem soon) * Older browsers (http://caniuse.com/#feat=promises) will need a ES6 Promise polyfill in order to work. ## Installation @@ -129,328 +128,11 @@ npm run start # open browser at localhost:4000 ``` -## GoogleMap API +## API -### parameters +[API](./API.md) -#### apiKey (string) (_Deprecated use bootstrapURLKeys_) - -Google maps api key. (Optional, but your map will be rate-limited with no key) - -#### bootstrapURLKeys (object) - -Example: - -```javascript - -``` - -#### defaultCenter (array or object) - -`[lat, lng]` or `{ lat: lat, lng: lng}` -Default lat/lng at which to center the map - changing this prop throws a warning - -#### center (array or object) - -`[lat, lng]` or `{ lat: lat, lng: lng}` -Lat/lng at which to center the map - -#### defaultZoom: (number) - -Default map zoom level - changing this prop throws a warning - -#### zoom (number) - -Map zoom level - -#### hoverDistance (number) - -Default: 30 - -#### margin (array) - -In onChange callback, gives you a marginBounds argument property, where lat lng will be shifted using margin you have set. For example, you could use a simple check pointInRect to not show Markers near map bounds. - -#### debounced (bool) - -Default: true - -#### layerTypes (string[]) - -You can add some "layers" for map like a -[traffic](https://developers.google.com/maps/documentation/javascript/examples/layer-traffic) or -[transit](https://developers.google.com/maps/documentation/javascript/examples/layer-transit) - -```javascript -layerTypes={['TrafficLayer', 'TransitLayer']} -``` - -#### resetBoundsOnResize (bool) - -When true this will reset the map bounds if the parent resizes. - -Default: false - -### callbacks - -#### options (func|object) - -Set map options such as controls positions / styles, etc. - -Example: - -```javascript -createMapOptions: function (maps) { - return { - panControl: false, - mapTypeControl: false, - scrollwheel: false, - styles: [{ stylers: [{ 'saturation': -100 }, { 'gamma': 0.8 }, { 'lightness': 4 }, { 'visibility': 'on' }] }] - } - } - - -``` -See "Custom map options example" in Examples below for a further example. - -#### onClick (func) - -``` -({ x, y, lat, lng, event }) -``` - -The `event` prop in args is the outer div onClick event, not the gmap-api 'click' event. - -Example: - - ```javascript - _onClick = ({x, y, lat, lng, event}) => console.log(x, y, lat, lng, event) - // ES5 users - function _onClick(obj){ console.log(obj.x, obj.y, obj.lat, obj.lng, obj.event);} - - - ``` - -#### onBoundsChange (func) (_Deprecated use onChange_) - -``` -({ center, zoom, bounds, marginBounds }) -``` -``` -[lat, lng] = center; -[topLat, leftLng, bottomLat, rightLng] = bounds; -``` - -#### onChildClick (func) - -#### onChildMouseEnter (func) - -#### onChildMouseLeave (func) - -#### onZoomAnimationStart (func) - -#### onZoomAnimationEnd (func) - -#### onMapTypeIdChange (func) -When the user changes the map type (HYBRID, ROADMAP, SATELLITE, TERRAIN) this fires - -#### distanceToMouse (func) - -#### googleMapLoader (func) - -#### onGoogleApiLoaded (func) -Directly access the maps API - *use at your own risk!* - -```javascript - console.log(map, maps)} /> -``` - -To prevent warning message add _yesIWantToUseGoogleMapApiInternals_ property to GoogleMap - -```javascript - console.log(map, maps)} - yesIWantToUseGoogleMapApiInternals - /> - ``` - -## Child Component API - -### parameters - -#### lat (number) -Latitude to place the marker component - -#### lng (number) -Longitude to place the marker component - -#### $hover (bool) [automatic] -GoogleMap passes a $hover prop to hovered components. To detect hover it an uses internal mechanism, explained in x_distance_hover example - -Example: -```javascript -render() { - const style = this.props.$hover ? greatPlaceStyleHover : greatPlaceStyle; - - return ( -
- {this.props.text} -
- ); - } - ``` - - -## Utility functions - -#### fitBounds (func) - Use fitBounds to get zoom and center. - -Example: - -```javascript -import { fitBounds } from 'google-map-react/utils'; - -const bounds = { - nw: { - lat: 50.01038826014866, - lng: -118.6525866875 - }, - se: { - lat: 32.698335045970396, - lng: -92.0217273125 - } -}; - -// Or - -const bounds = { - ne: { - lat: 50.01038826014866, - lng: -118.6525866875 - }, - sw: { - lat: 32.698335045970396, - lng: -92.0217273125 - } -}; - -const size = { - width: 640, // Map width in pixels - height: 380, // Map height in pixels -}; - -const {center, zoom} = fitBounds(bounds, size); -``` - -#### tile2LatLng (func) - -#### latLng2Tile (func) - -#### getTilesIds (func) - -## Tips - -### My map doesn't appear - -Make sure the container element has width and height. The map will try to fill the parent container, but if the container has no size, the map will collapse to 0 width / height. - -### Positioning a marker - -Initially any map object has its top left corner at lat lng coordinates. It's up to you to set the object origin to 0,0 coordinates. - -Example (centering the marker): - -```javascript -const MARKER_SIZE = 40; -const greatPlaceStyle = { - position: 'absolute', - width: MARKER_SIZE, - height: MARKER_SIZE, - left: -MARKER_SIZE / 2, - top: -MARKER_SIZE / 2 -} -``` - -```javascript -render() { - return ( -
- {this.props.text} -
- ); -} -``` - -### Rendering in a modal - -If at the moment of GoogleMap control created, a modal has no size (width,height=0) or/and not displayed, the simple solution is to add something like this in render: - -```javascript -render() { - return this.props.modalIsOpen - ? - : null; -} -``` - -### Adding a searchbox - -```javascript -import React from 'react'; - -export default class SearchBox extends React.Component { - static propTypes = { - placeholder: React.PropTypes.string, - onPlacesChanged: React.PropTypes.func - } - render() { - return ; - } - onPlacesChanged = () => { - if (this.props.onPlacesChanged) { - this.props.onPlacesChanged(this.searchBox.getPlaces()); - } - } - componentDidMount() { - var input = React.findDOMNode(this.refs.input); - this.searchBox = new google.maps.places.SearchBox(input); - this.searchBox.addListener('places_changed', this.onPlacesChanged); - } - componentWillUnmount() { - this.searchBox.removeListener('places_changed', this.onPlacesChanged); - } -} -``` - -You will need to preload the google maps API, but `google-map-react` checks if the base api is already loaded, -and if so, uses it, so it won't load a second copy of the library. - -```html - -``` - -### Override the default minimum zoom - -*WARNING*: Setting these options can break markers calculation, causing no homeomorphism between screen coordinates and map. - -You can use the `minZoomOverride` associated with the `minZoom` in the custom map options to prevent a minimum zoom from being calculated: - -```javascript -function createMapOptions() { - return { - minZoomOverride: true, - minZoom: 2, - }; -} -``` - ---- +[NEW DOCS](./DOC.md) (*Really big thanks to [April Arcus](https://github.com/AprilArcus) for documentation fixes*) (*thank you [Dan Abramov](http://gaearon.github.io/react-dnd/) for titles structure*)