Skip to content

Commit cde868f

Browse files
BiniCodesBiniCodes
authored
Merge pull request #119 from ubilabs/docs/code-examples-readme
Docs/code examples readme
2 parents 32686f8 + 56207a8 commit cde868f

File tree

3 files changed

+236
-68
lines changed

3 files changed

+236
-68
lines changed

‎CONTRIBUTING.md

Lines changed: 51 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,20 @@ To get started there are some things that need to be set up.
66

77
---
88

9+
#### Table of contents
10+
11+
- [Setting Up Dev Environment](#setting-up-dev-environment)
12+
- [Fork the repo and start building](#fork-the-repo-and-start-building)
13+
- [Issue Tracker](#issue-tracker)
14+
- [Pull Requests / Merge Requests](#pull-requests--merge-requests)
15+
- [Code Style and Code Quality](#code-style-and-code-quality)
16+
- [Adding An Example](#adding-an-example)
17+
- [Run examples](#run-examples)
18+
- [Develop examples](#develop-examples)
19+
- [Publish library on npm](#publish-library-on-npm)
20+
21+
---
22+
923
## Setting Up Dev Environment
1024

1125
We will work on the `develop` branch.
@@ -87,27 +101,45 @@ Then open [`localhost:1234`](http://localhost:1234) in a browser.
87101

88102
- **IMPORTANT**: by submitting a patch, you agree to allow the project owners to license your work under this [LICENSE.md](LICENSE.md)
89103

90-
- please provide test cases for all features and bug fixes
104+
- please provide test cases for all features and bug fixes
91105

92-
- provide documentation for all public API methods
106+
- provide documentation for all public API methods
93107

94-
- commit messages should follow the format outlined in [CONVENTIONS.md](CONVENTIONS.md)
108+
- commit messages should follow the format outlined in [CONVENTIONS.md](CONVENTIONS.md)
95109

96110
### Code Style and Code Quality
97111

98-
- Testing
112+
- **Testing**
99113

100114
- [ESLint](https://eslint.org/) configuration files are provided
101115
- [TypeScript](https://www.typescriptlang.org/) check for types and TypeScript setup
102116
- [Prettier](https://prettier.io/) code formatter
103117

104-
- run `npm run test` before submitting a PR to ensure that your code uses correct style and passes all tests
118+
Run `npm run test` before submitting a PR to ensure that your code uses correct style and passes all tests
105119

106120
---
107121

108122
## Adding An Example
109123

110-
Each hook should have an example in the examples folder. If you want to provide an example for a hook, please follow these steps:
124+
Each hook should have an example in the examples folder.
125+
126+
### Run examples
127+
128+
To develop one of the examples, you have to create a `.env` file in the `/examples` directory first and add your [Google Maps API key](https://developers.google.com/maps/documentation/embed/get-api-key#:~:text=Go%20to%20the%20Google%20Maps%20Platform%20%3E%20Credentials%20page.&text=On%20the%20Credentials%20page%2C%20click,Click%20Close.) to it in the following format:
129+
130+
```
131+
GOOGLE_MAPS_API_KEY="<YOUR API KEY HERE>"
132+
```
133+
134+
An example can be found in `/examples/.env.example`.
135+
136+
Start the example locally with the appropriate task, e.g. `npm run start:map-example`. You can find the right task in the README of the example you want to start.
137+
138+
The example runs on [localhost:1234](http://localhost:1234).
139+
140+
### Develop examples
141+
142+
If you want to provide an example for a hook, please follow these steps:
111143

112144
1. Create a new folder in the [examples folder](./examples) with the new example's name.
113145

@@ -132,3 +164,16 @@ Please compare to the other example start tasks.
132164
5. Add a README to each example with an explanation of what the example does, a code snippet and an image of the example app in a ratio of 2:1.
133165

134166
6. Link the example in the [root README](./README.md) and the [README of the library workspace](./library/README.md) in the **Examples** overview of the **Table of contents** section.
167+
168+
---
169+
170+
## Publish library on npm
171+
172+
A new library version is automatically published by Github Actions as soon as a new version tag is available.
173+
To trigger a new release, run:
174+
175+
```sh
176+
npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease | from-git] -w library
177+
```
178+
179+
**NOTE**: Make sure to not forget setting the context to the library workspace with `-w library` when running the command from project root.

‎README.md

Lines changed: 161 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -8,58 +8,176 @@ This is a JavaScript library to easily implement a Google Maps map into your Rea
88

99
#### Table of contents
1010

11-
- [Google Maps React Hooks Library](./library)
12-
- [Examples](./examples)
13-
- [Basic Google Map](./examples/basic-google-map)
14-
- [Google Map with Markers](./examples/google-map-with-markers)
15-
- [Multiple Google Maps](./examples/multiple-google-maps)
16-
- [Directions Service](./examples/directions-service)
17-
- [Distance Matrix Service](./examples/distance-matrix-service)
18-
- [Elevation Service](./examples/elevation-service)
19-
- [Geocoding Service](./examples/geocoding-service)
20-
- [Maximum Zoom Imagery Service](./examples/max-zoom-service)
21-
- [Places Autocomplete Service](./examples/places-autocomplete-service)
22-
- [Places Autocomplete Widget](./examples/places-autocomplete-widget)
23-
- [Places Service](./examples/places-service)
24-
- [Places Service With Element](./examples/places-service-with-element)
25-
- [Street View Panorama Map](./examples/street-view-panorama-map)
26-
- [Street View Panorama With Element](./examples/street-view-panorama-with-element)
11+
- [Requirements](#requirements)
12+
- [Installation](#installation)
13+
- [Library](#library)
14+
- [Basic Google Map Setup](#basic-google-map-setup)
15+
- [Hooks](#hooks)
16+
- [Hooks Overview](#hooks-overview)
17+
- [Hooks Example Setup](#hooks-example-setup)
18+
- [Examples](#examples)
19+
- [Examples Overview](#examples-overview)
2720
- [Development](#development-only-for-maintainers)
28-
- [Library](#library)
29-
- [Examples](#examples)
30-
- [Publish library on npm](#publish-library-on-npm)
21+
- [Contribution](#contribution)
22+
- [Quick Start](#quick-start)
3123

32-
## Development (only for Maintainers)
24+
## Requirements
3325

34-
Clone the repository and run
26+
You need to have React [16.8.0](https://reactjs.org/blog/2019/02/06/react-v16.8.0.html) or later installed to use the Hooks API.
27+
28+
## Installation
3529

3630
```sh
37-
npm install
31+
npm install @ubilabs/google-maps-react-hooks -D
3832
```
3933

40-
in the project root to install all dependencies.
34+
## Library
4135

42-
### Library
36+
The full Google Maps React Hooks library can be found in the [library directory](./library).
4337

44-
To develop the Google Maps React Hooks library, start the project locally with
38+
## Basic Google Map Setup
4539

46-
```sh
47-
npm run start:library
40+
Import the `GoogleMapsProvider` and wrap it around your components.
41+
Make sure all components that should have access to the Google Maps map instance are nested inside the `GoogleMapsProvider`.
42+
43+
If you still can't see a map on your page, make sure that your map container has a `height` CSS property (by default it usually has no height) and that a `center` and `zoom` was set for your map.
44+
45+
```tsx
46+
import React, {useState, useCallback, forwardRef} from 'react';
47+
import {GoogleMapsProvider} from '@ubilabs/google-maps-react-hooks';
48+
49+
function App() {
50+
const [mapContainer, setMapContainer] = useState(null);
51+
const mapRef = useCallback(node => {
52+
node && setMapContainer(node);
53+
}, []);
54+
55+
const mapOptions = {
56+
// Add your map options here
57+
// `center` and `zoom` are required for every map to be displayed
58+
center: {lat: 53.5582447, lng: 9.647645},
59+
zoom: 6
60+
};
61+
62+
return (
63+
<GoogleMapsProvider
64+
googleMapsAPIKey="YOUR API KEY HERE"
65+
mapContainer={mapContainer}
66+
mapOptions={mapOptions}>
67+
<React.StrictMode>
68+
<div ref={ref} style={{height: '100%'}} />
69+
</React.StrictMode>
70+
</GoogleMapsProvider>
71+
);
72+
}
73+
74+
export default App;
4875
```
4976

50-
### Examples
77+
The `GoogleMapsProvider` makes the Google Maps map instance available to any nested components with the `useGoogleMap` hook.
78+
79+
```tsx
80+
import React from 'react';
81+
import {useGoogleMap} from '@ubilabs/google-maps-react-hooks';
5182

52-
To develop one of the examples, you have to create a `.env` file in the `/examples` directory first and add your [Google Maps API key](https://developers.google.com/maps/documentation/embed/get-api-key#:~:text=Go%20to%20the%20Google%20Maps%20Platform%20%3E%20Credentials%20page.&text=On%20the%20Credentials%20page%2C%20click,Click%20Close.) to it in the following format:
83+
const MyComponent = () => {
84+
const map = useGoogleMap();
5385

86+
// Do something with the Google Maps map instance
87+
88+
return (...);
89+
};
5490
```
55-
GOOGLE_MAPS_API_KEY="<YOUR API KEY HERE>"
91+
92+
## Hooks
93+
94+
All hooks can be find [here](./library/src/hooks/). Please checkout the [documentation](./library/docs) for each hook and have a look at the [examples directory](./examples) to see how each hook can be implemented.
95+
96+
### Hooks Overview
97+
98+
- [useGoogleMap](./library/docs/useGoogleMap.md)
99+
- [useDirectionsService](./library/docs/useDirectionsService.md)
100+
- [useDistanceMatrixService](./library/docs/useDistanceMatrixService.md)
101+
- [useElevationService](./library/docs/useElevationService.md)
102+
- [useGeocodingService](./library/docs/useGeocodingService.md)
103+
- [useMaxZoomService](./library/docs/useMaxZoomService.md)
104+
- [usePlacesService](./library/docs/usePlacesService.md)
105+
- [useAutocomplete](./library/docs/useAutocomplete.md)
106+
- [useAutocompleteService](./library/docs/useAutocompleteService.md)
107+
108+
### Hooks Example Setup
109+
110+
**useGeocodingService**
111+
112+
```tsx
113+
import React from 'react';
114+
import {useGeocodingService} from '@ubilabs/google-maps-react-hooks';
115+
116+
const MyComponent = () => {
117+
const geocoder = useGeocodingService();
118+
119+
// Do something with the geocoder
120+
121+
return (...);
122+
};
123+
```
124+
125+
**useAutocomplete**
126+
127+
```tsx
128+
import React, {useRef, useState} from 'react';
129+
import {useAutocomplete} from '@ubilabs/google-maps-react-hooks';
130+
131+
const MyComponent = () => {
132+
const inputRef = useRef(null);
133+
const [inputValue, setInputValue] = useState('');
134+
135+
const onPlaceChanged = place => {
136+
if (place) {
137+
setInputValue(place.formatted_address || place.name);
138+
}
139+
140+
// Keep focus on input element
141+
inputRef.current && inputRef.current.focus();
142+
};
143+
144+
useAutocomplete({
145+
inputField: inputRef && inputRef.current,
146+
onPlaceChanged
147+
});
148+
149+
const handleInputChange = event => {
150+
setInputValue(event.target.value);
151+
};
152+
153+
return (
154+
<input ref={inputRef} value={inputValue} onChange={handleInputChange} />
155+
);
156+
};
56157
```
57158

58-
An example can be found in `/examples/.env.example`.
159+
## Examples
160+
161+
Explore our [examples directory on GitHub](./examples) for full implementation examples.
59162

60-
Start the example locally with the appropriate task, e.g. `npm run start:map-example`. You can find the right task in the README of the example you want to start.
163+
### Examples Overview
61164

62-
The example runs on [localhost:1234](http://localhost:1234).
165+
- [Basic Google Map](./examples/basic-google-map)
166+
- [Google Map with Markers](./examples/google-map-with-markers)
167+
- [Multiple Google Maps](./examples/multiple-google-maps)
168+
- [Directions Service](./examples/directions-service)
169+
- [Distance Matrix Service](./examples/distance-matrix-service)
170+
- [Elevation Service](./examples/elevation-service)
171+
- [Geocoding Service](./examples/geocoding-service)
172+
- [Maximum Zoom Imagery Service](./examples/max-zoom-service)
173+
- [Places Autocomplete Service](./examples/places-autocomplete-service)
174+
- [Places Autocomplete Widget](./examples/places-autocomplete-widget)
175+
- [Places Service](./examples/places-service)
176+
- [Places Service With Element](./examples/places-service-with-element)
177+
- [Street View Panorama Map](./examples/street-view-panorama-map)
178+
- [Street View Panorama With Element](./examples/street-view-panorama-with-element)
179+
180+
## Development (only for Maintainers)
63181

64182
### Contribution
65183

@@ -68,13 +186,18 @@ We are happy about your contribution. Please checkout the following guide to get
68186

69187
Also, make sure to follow our [Coding Conventions](./CONVENTIONS.md) when making commits.
70188

71-
### Publish library on npm
189+
### Quick Start
72190

73-
A new library version is automatically published by Github Actions as soon as a new version tag is available.
74-
To trigger a new release, run:
191+
Clone the repository and run
75192

76193
```sh
77-
npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease | from-git] -w library
194+
npm install
78195
```
79196

80-
**NOTE**: Make sure to not forget setting the context to the library workspace with `-w library` when running the command from project root.
197+
in the project root to install all dependencies.
198+
199+
To develop the Google Maps React Hooks library, start the project locally with
200+
201+
```sh
202+
npm run start:library
203+
```

‎library/README.md

Lines changed: 24 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -12,32 +12,32 @@ This is a JavaScript library to easily implement a Google Maps map into your Rea
1212
- [Installation](#installation)
1313
- [Map Usage](#map-usage)
1414
- Documentation
15-
- [GoogleMapsProvider](https://github.com/ubilabs/google-maps-react-hooks/tree/main/library/docs/GoogleMapsProvider.md)
15+
- [GoogleMapsProvider](./docs/GoogleMapsProvider.md)
1616
- Hooks
17-
- [useGoogleMap](https://github.com/ubilabs/google-maps-react-hooks/tree/main/library/docs/useGoogleMap.md)
18-
- [useDirections](https://github.com/ubilabs/google-maps-react-hooks/tree/main/library/docs/useDirections.md)
19-
- [useDistanceMatrix](https://github.com/ubilabs/google-maps-react-hooks/tree/main/library/docs/useDistanceMatrix.md)
20-
- [useElevationService](https://github.com/ubilabs/google-maps-react-hooks/tree/main/library/docs/useElevationService.md)
21-
- [useGeocoder](https://github.com/ubilabs/google-maps-react-hooks/tree/main/library/docs/useGeocoder.md)
22-
- [useMaxZoomService](https://github.com/ubilabs/google-maps-react-hooks/tree/main/library/docs/useMaxZoomService.md)
23-
- [usePlacesService](https://github.com/ubilabs/google-maps-react-hooks/tree/main/library/docs/usePlacesService.md)
24-
- [useAutocomplete](https://github.com/ubilabs/google-maps-react-hooks/tree/main/library/docs/useAutocomplete.md)
25-
- [useAutocompleteService](https://github.com/ubilabs/google-maps-react-hooks/tree/main/library/docs/useAutocompleteService.md)
17+
- [useGoogleMap](./docs/useGoogleMap.md)
18+
- [useDirectionsService](./docs/useDirectionsService.md)
19+
- [useDistanceMatrixService](./docs/useDistanceMatrixService.md)
20+
- [useElevationService](./docs/useElevationService.md)
21+
- [useGeocodingService](./docs/useGeocodingService.md)
22+
- [useMaxZoomService](./docs/useMaxZoomService.md)
23+
- [usePlacesService](./docs/usePlacesService.md)
24+
- [useAutocomplete](./docs/useAutocomplete.md)
25+
- [useAutocompleteService](./docs/useAutocompleteService.md)
2626
- [Examples](https://github.com/ubilabs/google-maps-react-hooks/tree/main/examples)
27-
- [Basic Google Map](https://github.com/ubilabs/google-maps-react-hooks/tree/main/examples/basic-google-map)
28-
- [Google Map with Markers](https://github.com/ubilabs/google-maps-react-hooks/tree/main/examples/google-map-with-markers)
29-
- [Multiple Google Maps](https://github.com/ubilabs/google-maps-react-hooks/tree/main/examples/multiple-google-maps)
30-
- [Directions Service](https://github.com/ubilabs/google-maps-react-hooks/tree/main/examples/directions-service)
31-
- [Distance Matrix Service](https://github.com/ubilabs/google-maps-react-hooks/tree/main/examples/distance-matrix-service)
32-
- [Elevation Service](https://github.com/ubilabs/google-maps-react-hooks/tree/main/examples/elevation-service)
33-
- [Geocoding Service](https://github.com/ubilabs/google-maps-react-hooks/tree/main/examples/geocoding-service)
34-
- [Maximum Zoom Imagery Service](https://github.com/ubilabs/google-maps-react-hooks/tree/main/examples/max-zoom-service)
35-
- [Places Autocomplete Service](https://github.com/ubilabs/google-maps-react-hooks/tree/main/examples/places-autocomplete-service)
36-
- [Places Autocomplete Widget](https://github.com/ubilabs/google-maps-react-hooks/tree/main/examples/places-autocomplete-widget)
37-
- [Places Service](https://github.com/ubilabs/google-maps-react-hooks/tree/main/examples/places-service)
38-
- [Places Service With Element](https://github.com/ubilabs/google-maps-react-hooks/tree/main/examples/places-service-with-element)
39-
- [Street View Panorama Map](https://github.com/ubilabs/google-maps-react-hooks/tree/main/examples/street-view-panorama-map)
40-
- [Street View Panorama With Element](https://github.com/ubilabs/google-maps-react-hooks/tree/main/examples/street-view-panorama-with-element)
27+
- [Basic Google Map](../examples/basic-google-map)
28+
- [Google Map with Markers](../examples/google-map-with-markers)
29+
- [Multiple Google Maps](../examples/multiple-google-maps)
30+
- [Directions Service](../examples/directions-service)
31+
- [Distance Matrix Service](../examples/distance-matrix-service)
32+
- [Elevation Service](../examples/elevation-service)
33+
- [Geocoding Service](../examples/geocoding-service)
34+
- [Maximum Zoom Imagery Service](../examples/max-zoom-service)
35+
- [Places Autocomplete Service](../examples/places-autocomplete-service)
36+
- [Places Autocomplete Widget](../examples/places-autocomplete-widget)
37+
- [Places Service](../examples/places-service)
38+
- [Places Service With Element](../examples/places-service-with-element)
39+
- [Street View Panorama Map](../examples/street-view-panorama-map)
40+
- [Street View Panorama With Element](../examples/street-view-panorama-with-element)
4141

4242
## Requirements
4343

0 commit comments

Comments
 (0)