Skip to content

Docs/migrate app to 6 0 0 #345

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tomchentw merged 4 commits into from
Oct 4, 2016
Merged

Docs/migrate app to 6 0 0 #345

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
fcaae9b
docs: revamp app for v6.0.0
tomchentw Jul 14, 2016
6edf000
docs: add AsyncGettingStartedExample
tomchentw Sep 30, 2016
3db5c74
chore(package.json): remove unused devDependencies "react-addons-update"
tomchentw Oct 4, 2016
fc9617a
docs(README.md): update for v6.0.0
tomchentw Oct 4, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
295 changes: 182 additions & 113 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,168 +4,237 @@
[![Version][npm-image]][npm-url] [![Travis CI][travis-image]][travis-url] [![Quality][codeclimate-image]][codeclimate-url] [![Coverage][codeclimate-coverage-image]][codeclimate-coverage-url] [![Dependencies][gemnasium-image]][gemnasium-url] [![Gitter][gitter-image]][gitter-url]


## Call for maintainers
## Under development for [v6.0.0](https://github.com/tomchentw/react-google-maps/issues/318)

As the author ([tomchentw][tomchentw]) currently doesn't actively use this module, he's looking for awesome contributors to help and keep the community healthy. Please don't hensitate to [contact him][tomchentw] directly. See [#266][call-for-maintainers] for more information.
Try it via:

```sh
npm install --save react-google-maps@beta
```

## Quick start: SimpleMap

Declare your Google Maps components using React components.
## Call for maintainers

```jsx
import {GoogleMapLoader, GoogleMap, Marker} from "react-google-maps";

export default function SimpleMap (props) {
return (
<section style={{height: "100%"}}>
<GoogleMapLoader
containerElement={
<div
{...props.containerElementProps}
style={{
height: "100%",
}}
/>
}
googleMapElement={
<GoogleMap
ref={(map) => console.log(map)}
defaultZoom={3}
defaultCenter={{ lat: -25.363882, lng: 131.044922 }}
onClick={props.onMapClick}
>
{props.markers.map((marker, index) => {
return (
<Marker
{...marker}
onRightclick={() => props.onMarkerRightclick(index)} />
);
})}
</GoogleMap>
}
/>
</section>
);
}
```
As the author ([tomchentw][tomchentw]) currently doesn't actively use this module, he's looking for awesome contributors to help and keep the community healthy. Please don't hensitate to [contact him][tomchentw] directly. See [#266][call-for-maintainers] for more information.


## Documentation

### Rule 1

Define `<GoogleMap>` component in the top level. Use `containerProps`, `containerTagName` to customize the wrapper DOM for the component.
Basically just a simple wrapper around [Google Maps Javascript API][Google Maps Javascript API]. Also check out the [demo][demo] app and it's source under [src/app][src_app] folder.

Other components like `<Marker>` belong to the children of `<GoogleMap>`. You already know this from the example code above.
**Note**: this doc is under development for [v6.0.0](https://github.com/tomchentw/react-google-maps/issues/318). Find docs for [v5.x][docs_v5] and [v4.x][docs_v4] with the git tags.

### Rule 2
### withGoogleMap

Everything in the `Methods` table in the [official documentation](https://developers.google.com/maps/documentation/javascript/3.exp/reference#Marker) of the component could be set directly via component's *props* . For example, a `<Marker>` component has the following *props*:

```
animation, attribution, clickable, cursor, draggable, icon, label, opacity, options, place, position, shape, title, visible, zIndex
```jsx
// Wrap all `react-google-maps` components with `withGoogleMap` HOC
// and name it GettingStartedGoogleMap
const GettingStartedGoogleMap = withGoogleMap(props => (
<GoogleMap
ref={props.onMapLoad}
defaultZoom={3}
defaultCenter={{ lat: -25.363882, lng: 131.044922 }}
onClick={props.onMapClick}
>
{props.markers.map((marker, index) => (
<Marker
{...marker}
onRightClick={() => props.onMarkerRightClick(index)}
/>
))}
</GoogleMap>
));
// Then, render it:
render(
<GettingStartedGoogleMap
containerElement={
<div style={{ height: `100%` }} />
}
mapElement={
<div style={{ height: `100%` }} />
}
onMapLoad={_.noop}
onMapClick={_.noop}
markers={markers}
onMarkerRightClick={_.noop}
/>,
document.getElementById('root')
);
```

### Rule 3

Every props mentioned in __Rule 2__ could be either [controlled](https://facebook.github.io/react/docs/forms.html#controlled-components) or [uncontrolled](https://facebook.github.io/react/docs/forms.html#uncontrolled-components) property. Free to use either one depends on your use case.

### Rule 4

Anything that is inside components' `options` property can __ONLY__ be accessible via `props.options`. It's your responsibility to manage the `props.options` object during the React lifetime of your component. My suggestion is, always use __Rule 3__ if possible. Only use `options` when it's necessary.

### Rule 5

Event handlers on these components can be bound using React component convention. There's a list of event names that exist in the `eventLists` folder. Find the supported event name and use the form of `on${ camelizedEventName }`. For example, If I want to add `center_changed` callback to a map instance, I'll do the following with `react-google-maps`:
### GoogleMap

```jsx
<GoogleMap
// onCenterChanged: on + camelizedEventName(center_change)
onCenterChanged={this.handleCenterChanged}
onClick={_.noop}
onRightClick={_.noop}
onDragStart={_.noop}
/>
```

The list of event names can be found [here](https://github.com/tomchentw/react-google-maps/blob/master/src/eventLists/GoogleMapEventList.js).

### Check the examples
### Marker

Static hosted [demo site][demo] on GitHub. The code is located under [examples/gh-pages][examples_gh_pages] folder.
```jsx
<Marker
onClick={_.noop}
onRightClick={_.noop}
onDragStart={_.noop}
/>
```

### Circle

## Usage
```jsx
<Circle
onClick={_.noop}
onRightClick={_.noop}
onDragStart={_.noop}
/>
```

`react-google-maps` requires __React >= 0.14__
### Rectangle

```sh
npm install --save react-google-maps
```jsx
<Rectangle
onClick={_.noop}
onRightClick={_.noop}
onDragStart={_.noop}
/>
```

All components are available on the top-level export.
### Polyline

```js
import { GoogleMap, Marker, SearchBox } from "react-google-maps";
```jsx
<Polyline
onClick={_.noop}
onRightClick={_.noop}
onDragStart={_.noop}
/>
```

### Loading Libraries
### Polygon

To use this component, you are going to need to load the [Google Maps Javascript API].
It is optional, but recommended, to specify the libraries you will be using as well as your API key.
```jsx
<Polygon
onClick={_.noop}
onRightClick={_.noop}
onDragStart={_.noop}
/>
```

You could do it synchronously like so:
### KmlLayer

```html
<script type="text/javascript"
src="https://maps.googleapis.com/maps/api/js?key=[YOUR_API_KEY]&libraries=geometry,places,visualization">
</script>
```jsx
<KmlLayer
onClick={_.noop}
onDefaultViewportChanged={_.noop}
onStatusChanged={_.noop}
/>
```

### InfoWindow

```jsx
<GoogleMapLoader
query={{ libraries: "geometry,drawing,places,visualization" }}
...
<InfoWindow
onCloseClick={_.noop}
onDomReady={_.noop}
onZIndexChanged={_.noop}
/>
```

Or asynchronously using the ScriptjsLoader:
### drawing/DrawingManager

```jsx
<ScriptjsLoader
hostname={"maps.googleapis.com"}
pathname={"/maps/api/js"}
query={{ key: "[YOUR_API_KEY]", libraries: "geometry,drawing,places" }}
...
<DrawingManager
onCircleComplete={_.noop}
onOverlayComplete={_.noop}
/>
```

### Trigger events

`triggerEvent(component, ...args)`: One common event trigger is to resize map after the size of the container div change.
### places/SearchBox

```jsx
import {triggerEvent} from "react-google-maps/lib/utils";

function handleWindowResize () {
triggerEvent(this._googleMapComponent, "resize");
}
// and you'll get `this._googleMapComponent` like this:
<GoogleMap ref={it => this._googleMapComponent = it} />
<SearchBox
inputPlaceholder="Customized your placeholder"
inputStyle={INPUT_STYLE}
/>
```

### Optimize bundle size

You could of course import from individual modules to save your [webpack][webpack]'s bundle size.
### addons/MarkerClusterer

```jsx
import GoogleMap from "react-google-maps/lib/GoogleMap"; // Or import {default as GoogleMap} ...
<MarkerClusterer
onClusteringBegin={_.noop}
onMouseOut={_.noop}
/>
```

### Additional Addons

Some addons component could __ONLY__ be accessible via direct import:
### addons/InfoBox

```jsx
import InfoBox from "react-google-maps/lib/addons/InfoBox";
<InfoBox
onCloseClick={_.noop}
onDomReady={_.noop}
onZIndexChanged={_.noop}
/>
```

### async/withScriptjs

```jsx
// Wrap all `react-google-maps` components with `withGoogleMap` HOC
// then wraps it into `withScriptjs` HOC
// It loads Google Maps JavaScript API v3 for you asynchronously.
// Name the component AsyncGettingStartedExampleGoogleMap
const AsyncGettingStartedExampleGoogleMap = withScriptjs(
withGoogleMap(
props => (
<GoogleMap
ref={props.onMapLoad}
defaultZoom={3}
defaultCenter={{ lat: -25.363882, lng: 131.044922 }}
onClick={props.onMapClick}
>
{props.markers.map(marker => (
<Marker
{...marker}
onRightClick={() => props.onMarkerRightClick(marker)}
/>
))}
</GoogleMap>
)
);
// Then, render it:
render(
<GettingStartedGoogleMap
googleMapURL="https://maps.googleapis.com/maps/api/js?v=3.exp"
loadingElement={
<div style={{ height: `100%` }}>
<FaSpinner
style={{
display: `block`,
width: `80px`,
height: `80px`,
margin: `150px auto`,
animation: `fa-spin 2s infinite linear`,
}}
/>
</div>
}
containerElement={
<div style={{ height: `100%` }} />
}
mapElement={
<div style={{ height: `100%` }} />
}
onMapLoad={_.noop}
onMapClick={_.noop}
markers={markers}
onMarkerRightClick={_.noop}
/>,
document.getElementById('root')
);
```

## Changelog

Expand All @@ -190,9 +259,9 @@ The changelog is automatically generated via [conventional-changelog][convention

[tomchentw]: https://github.com/tomchentw
[call-for-maintainers]: https://github.com/tomchentw/react-google-maps/issues/266
[demo]: http://tomchentw.github.io/react-google-maps/
[examples_gh_pages]: https://github.com/tomchentw/react-google-maps/tree/master/examples/gh-pages
[webpack]: http://webpack.github.io/docs/tutorials/getting-started/
[conventional-changelog]: https://github.com/ajoslin/conventional-changelog

[demo]: https://tomchentw.github.io/react-google-maps/
[src_app]: https://github.com/tomchentw/react-google-maps/tree/master/src/app
[Google Maps Javascript API]: https://developers.google.com/maps/documentation/javascript/
[conventional-changelog]: https://github.com/ajoslin/conventional-changelog
[docs_v5]: https://github.com/tomchentw/react-google-maps/tree/v5.1.0#documentation
[docs_v4]: https://github.com/tomchentw/react-google-maps/tree/v4.11.0#documentation
1 change: 0 additions & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,6 @@
"raf": "^3.3.0",
"raw-loader": "^0.5.1",
"react": "^15.0.0",
"react-addons-update": "^15.0.0",
"react-bootstrap": "^0.30.3",
"react-dom": "^15.0.0",
"react-github-fork-ribbon": "^0.4.4",
Expand Down
Loading