archive-gh-me/google-map-react
1
0
Fork 0
mirror of https://github.com/google-map-react/google-map-react.git synced 2025-12-08 18:26:32 +00:00
Code Issues Projects Releases Wiki Activity

Merge pull request #45 from mbrookes/master

Browse Source 
Add basic API docs and FAQs to the README
This commit is contained in:
Matt Brookes 2015-10-09 20:02:11 +01:00
commit 700517f5d9
1 changed files with 201 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

232
README.md
View File

@ -5,6 +5,30 @@
It allows you to create interfaces like this [example](http://istarkov.github.io/google-map-react/map/main) *(You can scroll the table, zoom/move the map, hover/click on markers, and click on table rows)*
##Features
###Works with your Components
Instead of the ugly Google Maps markers, balloons and other map components, you can render your cool animated react components on the map.
###Isomorphic Rendering
It renders on the server. *(Welcome search engines)* *(you can disable javascript in browser dev tools, and reload any example page to see how it works)*
###Component Positions Calculated Independently of Google Maps API
It renders components on the map before (and even without) the Google Maps API loaded.
###Google Maps API Loads on Demand
There is no need to place a `<script src=` tag at top of page. The Google Maps API loads upon the first usage of the `GoogleMap` component.
###Internal Hover Algorithm
Now every object on the map can be hovered (however, you can still use css hover selectors if you want). If you try zooming out here [example](http://istarkov.github.io/google-map-react/map/main), you will still be able to hover on almost every map marker.
This algorithm allows you to tweak hover probability of map objects, for example making some objects "more hoverable". [distance_hover example with different hover probabilities](http://istarkov.github.io/google-map-react/map/distance_hover)
##Known Issues
* Small icons jiggle on Firefox (I don't see this in my older 'GoogleMap' version, so I will find the problem soon)
##Installation
### npm
@ -18,10 +42,12 @@ bower install --save google-map-react
```
The global will be available at: `window.GoogleMapReact`
##What's it Look Like?
In the simple case you just need to add `lat` `lng` props to any child of `GoogleMap` component.
[simple example in action](http://istarkov.github.io/google-map-react/map/simple)
```javascript
[simple example in action](http://istarkov.github.io/google-map-react/map/simple)
```jsx
import React, {PropTypes, Component} from 'react/addons';
import shouldPureComponentUpdate from 'react-pure-render/function';
@ -54,50 +80,194 @@ export default class SimpleMapPage extends Component {
}
```
##Features
## API
### parameters
###Works with your Components
Instead of the ugly Google Maps markers, balloons and other map components, you can render your cool animated react components on the map.
####apiKey (string)
Google maps api key. (Optional, but your map will be rate-limited with no key)
###Isomorphic Rendering
It renders on the server. *(Welcome search engines)* *(you can disable javascript in browser dev tools, and reload any example page to see how it works)*
####defaultCenter (array or object)
`[lat, lng]` or `{ lat: lat, lng: ln}`
Default lat/lng at which to center the map - changing this prop throws a warning
###Component Positions Calculated Independently of Google Maps API
It renders components on the map before (and even without) the Google Maps API loaded.
####defaultCenter (array or object)
`[lat, lng]` or `{ lat: lat, lng: ln}`
Lat/lng at which to center the map
###Google Maps API Loads on Demand
There is no need to place a `<script src=` tag at top of page. The Google Maps API loads upon the first usage of the `GoogleMap` component.
####defaultZoom: (number)
Default map zoom level - changing this prop throws a warning
###Internal Hover Algorithm
Now every object on the map can be hovered (however, you can still use css hover selectors if you want). If you try zooming out here [example](http://istarkov.github.io/google-map-react/map/main), you will still be able to hover on almost every map marker.
####zoom (number)
Map zoom level
This algorithm allows you to tweak hover probability of map objects, for example making some objects "more hoverable". [distance_hover example with different hover probabilities](http://istarkov.github.io/google-map-react/map/distance_hover)
####hoverDistance (number)
Default: 30
##Known Issues
* Small icons jingle on Firefox (I don't see this in my older 'GoogleMap' version, so I will find the problem soon)
####margin (array)
####debounced (bool)
Default: true
##Examples (API is really simple, just look at the examples)
* Placing react components on the map
[simple](http://istarkov.github.io/google-map-react/map/simple/) ([source](https://github.com/istarkov/google-map-react-examples/blob/master/web/flux/components/examples/x_simple/simple_map_page.jsx))
### callbacks
* Custom map options example
[options example](http://istarkov.github.io/google-map-react/map/options/) ([source](https://github.com/istarkov/google-map-react-examples/blob/master/web/flux/components/examples/x_options/options_map_page.jsx))
####options (func)
Set map options such as controls positions / styles, etc.
* Hover effects
[simple hover](http://istarkov.github.io/google-map-react/map/simple_hover/) ([source](https://github.com/istarkov/google-map-react-examples/blob/master/web/flux/components/examples/x_simple_hover/simple_hover_map_page.jsx))
[distance hover](http://istarkov.github.io/google-map-react/map/distance_hover/) ([source](https://github.com/istarkov/google-map-react-examples/blob/master/web/flux/components/examples/x_distance_hover/distance_hover_map_page.jsx))
Example:
* GoogleMap events
[events](http://istarkov.github.io/google-map-react/map/events/) ([source](https://github.com/istarkov/google-map-react-examples/blob/master/web/flux/components/examples/x_events/events_map_page.jsx))
```jsx
createMapOptions: function (maps) {
return {
panControl: false,
mapTypeControl: false,
scrollwheel: false,
styles: [{ stylers: [{ 'saturation': -100 }, { 'gamma': 0.8 }, { 'lightness': 4 }, { 'visibility': 'on' }] }]
}
}
* All api examples
[main](http://istarkov.github.io/google-map-react/map/main/) ([source](https://github.com/istarkov/google-map-react-examples/blob/master/web/flux/components/examples/x_main/main_map_block.jsx))
[balderdash](http://istarkov.github.io/google-map-react/map/balderdash/) (same source as main)
<GoogleMap onptions={createMapOptions} ... />
```
See "Custom map options example" in Examples below for a further example.
* Example project
[google-map-react-examples](https://github.com/istarkov/google-map-react-examples)
####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:
```jsx
_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);}
<GoogleMap onClick={_onClick} ... />
```
####onBoundsChange (func)
####onChildClick (func)
####onChildMouseEnter (func)
####onChildMouseLeave (func)
####onZoomAnimationStart (func)
####onZoomAnimationEnd (func)
####distanceToMouse (func)
####googleMapLoader (func)
####onGoogleApiLoaded (func)
Directly access the maps API - *use at your own risk!*
```jsx
<GoogleMap onGoogleApiLoaded={({map, maps}) => console.log(map, maps)} />
```
To prevent warning message add _yesIWantToUseGoogleMapApiInternals_ property to GoogleMap
```jsx
<GoogleMap onGoogleApiLoaded={({map, maps}) => console.log(map, maps)}
yesIWantToUseGoogleMapApiInternals
/>
```
## 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
}
};
const size = {
width: 640, // Map width in pixels
height: 380, // Map height in pixels
};
const {center, zoom} = fitBounds({nw, se}, size);
```
####tile2LatLng (func)
####latLng2Tile (func)
####getTilesIds (func)
##Examples
* Placing react components on the map:
[simple](http://istarkov.github.io/google-map-react/map/simple/) ([source](https://github.com/istarkov/google-map-react-examples/blob/master/web/flux/components/examples/x_simple/simple_map_page.jsx))
* Custom map options:
[example](http://istarkov.github.io/google-map-react/map/options/) ([source](https://github.com/istarkov/google-map-react-examples/blob/master/web/flux/components/examples/x_options/options_map_page.jsx))
* Hover effects:
[simple hover](http://istarkov.github.io/google-map-react/map/simple_hover/) ([source](https://github.com/istarkov/google-map-react-examples/blob/master/web/flux/components/examples/x_simple_hover/simple_hover_map_page.jsx)),
[distance hover](http://istarkov.github.io/google-map-react/map/distance_hover/) ([source](https://github.com/istarkov/google-map-react-examples/blob/master/web/flux/components/examples/x_distance_hover/distance_hover_map_page.jsx))
* GoogleMap events:
[example](http://istarkov.github.io/google-map-react/map/events/) ([source](https://github.com/istarkov/google-map-react-examples/blob/master/web/flux/components/examples/x_events/events_map_page.jsx))
* Example project:
[main](http://istarkov.github.io/google-map-react/map/main/) ([source](https://github.com/istarkov/google-map-react-examples/blob/master/web/flux/components/examples/x_main/main_map_block.jsx))
[balderdash](http://istarkov.github.io/google-map-react/map/balderdash/) (same source as main)
* All api examples:
[google-map-react-examples](https://github.com/istarkov/google-map-react-examples)
## FAQs
### 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:
```jsx
render() {
return this.props.modalIsOpen
? <GoogleMap />
: null;
}
```
### Adding a searchbox
```javascript
mport React from 'react';
export default class SearchBox extends React.Component {
static propTypes = {
placeholder: React.PropTypes.string,
onPlacesChanged: React.PropTypes.func
}
render() {
return <input ref="input" {...this.props} type="text"/>;
}
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
<script type="text/javascript" src="https://maps.google.com/maps/api/js?libraries=places&sensor=false"></script>
```
---
(*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*)