Skip to content
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

chore: Update project Readme. #7

Merged
merged 1 commit into from
Oct 25, 2021
Merged

chore: Update project Readme. #7

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
258 changes: 136 additions & 122 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,140 +1,87 @@
# Lowdefy Google Maps Block

The [Google Maps API](https://developers.google.com/maps/documentation/javascript/overview) is a feature rich javascript map API that lets you customize maps with your own content and imagery for display on web pages and mobile devices.
This repository provides Lowdefy blocks for the [Google Maps API](https://developers.google.com/maps/documentation/javascript/overview) is a feature rich javascript map API that lets you customize maps with your own content and imagery for display on web pages and mobile devices.

[google-map-react](https://github.com/google-map-react/google-map-react) is a component written over a small set of the [Google Maps API](https://developers.google.com/maps/).

## Running the blocks
## Blocks

1. You must have [node](https://nodejs.org/en/) and [yarn](https://yarnpkg.com/getting-started/install) installed.
2. Clone this repository.
3. Run `yarn install`, then `yarn start`, then check the you block is served by viewing the meta data at: http://localhost:3002/meta/GoogleMaps.json.
4. Add the `types` to your lowdefy.yaml file. For example:
To use this block, define a [Custom Block type](https://docs.lowdefy.com/custom-blocks) in your Lowdefy app:

```yaml
name: my-app
lowdefy: 3.22.0
types:
GoogleMaps:
url: http://localhost:3002/meta/GoogleMaps.json
# ...
```

5. Use your new block type in your Lowdefy app.

```yaml
- id: google_maps
type: GoogleMaps
loading:
type: Skeleton
properties:
height: 500
properties:
bootstrapURLKeys:
key: ''
libraries: ['visualization']
mapOptions:
zoomControl: true
fullscreenControl: true
styles:
- stylers:
- saturation: -100
- gamma: 0.8
- lightness: 4
- visibility: on
zoom: 14
center:
lat: -25.344
lng: 131.036
height: 500 # defaults to 500 when not set
style: # overrides the map block's default style
height: 550 # overrides the 'height: 500' property of the map block
width: 100%
markers:
- position:
lat: -25.344
lng: 131.036
label: Hi
url: https://blocks-cdn.lowdefy.com/v3.22.0/blocks-google-maps/meta/GoogleMaps.json
# ...
```

6. Start your Lowdefy app and test if it works, run: `npx lowdefy@latest dev`
7. Continue to develop your block React component. Changes to your block will need to auto reload the app in the browser, you need to hit refresh.
8. Before deploying your blocks to a static file server, remember to change the `remoteEntryUrl` field in the `webpack.prod.js` file to your block URL.
9. Deploy your blocks and enjoy your ☕️.

## Properties

1. `bootstrapURLKeys`: { key: '', language: 'en', region: 'en', libraries: ['places'], ...otherUrlParams, } If you want to include additional libraries to load with the maps api, indicate them in the libraries property of the bootstrapURLKeys object.
2. `center`: Can be set to [lat, lng] or { lat: lat, lng: lng}. A position object for the center.
3. `debounced`: Defaults to true. Whether map events are debounced.
4. `defaultCenter`: Can be set to [lat, lng] or { lat: lat, lng: lng}. A position object for the center.
5. `defaultZoom`: Map zoom level.
6. `heatmap`: To use the heatmap layer, add visualization to the libraries property array on bootstrapURLKeys and provide the data & configuration for the heatmap in heatmap as props. If you have multiple maps in your project and require a heatmap layer in at least one of them, provide libraries:['visualization'] to all of them.
7. `height`: The height of the map block.
8. `hoverDistance`: Defaults to 30. Map hover distance.
9. `layerTypes`: Examples ['TrafficLayer', 'TransitLayer']. The layer types to be included in the map.
10. `mapOptions`: Custom map options.
11. `margin`: Map margin.
12. `markers`: A list of Markers with properties, `map` is provided by the default by the block, see [Javascript API Markers](https://developers.google.com/maps/documentation/javascript/markers) for configuration details.
13. `resetBoundsOnResize`: Default: false, When true this will reset the map bounds if the parent resizes.
14. `style`: Custom map css properties to apply to map block.
15. `zoom`: Map zoom level.

## Events

1. `onClick` Trigger onClick actions when the map is clicked, returns `_event` object:

- `event`: event object
- `lat`: latitudinal coordinate
- `lng`: longitudinal coordinate
- `maps`: has functions removed
- `x`: position on map block
- `y`: position on map block
2. `onClickMarker` Trigger onClick actions when a marker is clicked, returns `_event` object:

- `domEvent`: event object
- `latLng`:

- `lat`: latitudinal coordinate
- `lng`: longitudinal coordinate
- `maps`: has functions removed
- `pixel`:

- `x`
- `y`
3. `onDrag` Trigger onDrag actions when a map is dragged, returns `_event` object:

- `maps`: has functions removed
4. `onDragEnd` Trigger onDragEnd actions when a map is finished being dragged, returns `_event` object:

- `maps`: has functions removed
5. `onGoogleApiLoaded` Trigger onGoogleApiLoaded actions when the map api is loaded, returns `_event` object:

- `maps`: has functions removed
6. `onMapTypeIdChange` Trigger onMapTypeIdChange actions when the map type is changed, returns `_event` object:

- `maps`: has functions removed
- `type`: the map
7. `onTilesLoaded` Trigger onTilesLoaded actions when the map tiles are loaded, returns `_event` object:

- `maps`: has functions removed
8. `onZoomAnimationStart` Trigger onZoomAnimationStart actions when the map is zoomed, returns `_event` object:

- `maps`: has functions removed
- `zoom`: map zoom level
9. `onZoomAnimationEnd` Trigger onZoomAnimationEnd actions after the map is zoomed, returns `_event` object:

- `maps`: has functions removed
- `zoom`: map zoom level

## Methods

1. `addMarker` Accepts a single parameter object `marker` with marker properties.
2. `removeMarker` Accepts a single parameter object `marker` with position property.
3. `fitBounds` Accepts a two parameters, `bounds` and `mapSize`.
4. `addHeatmap` Accepts a single parameter object `heatmap` with heatmap properties.
5. `toggleHeatmap` Doesn't require any parameters.
### Block type Urls

- `GoogleMaps`: https://blocks-cdn.lowdefy.com/v3.22.0/blocks-google-maps/meta/GoogleMaps.json

### Properties

- `bootstrapURLKeys`: { key: '', language: 'en', region: 'en', libraries: ['places'], ...otherUrlParams, } If you want to include additional libraries to load with the maps api, indicate them in the libraries property of the bootstrapURLKeys object.
- `center`: Can be set to [lat, lng] or { lat: lat, lng: lng}. A position object for the center.
- `debounced`: Defaults to true. Whether map events are debounced.
- `defaultCenter`: Can be set to [lat, lng] or { lat: lat, lng: lng}. A position object for the center.
- `defaultZoom`: Map zoom level.
- `heatmap`: To use the heatmap layer, add visualization to the libraries property array on bootstrapURLKeys and provide the data & configuration for the heatmap in heatmap as props. If you have multiple maps in your project and require a heatmap layer in at least one of them, provide libraries:['visualization'] to all of them.
- `height`: The height of the map block.
- `hoverDistance`: Defaults to 30. Map hover distance.
- `layerTypes`: Examples ['TrafficLayer', 'TransitLayer']. The layer types to be included in the map.
- `mapOptions`: Custom map options.
- `margin`: Map margin.
- `markers`: A list of Markers with properties, `map` is provided by the default by the block, see [Javascript API Markers](https://developers.google.com/maps/documentation/javascript/markers) for configuration details.
- `resetBoundsOnResize`: Default: false, When true this will reset the map bounds if the parent resizes.
- `style`: Custom map css properties to apply to map block.
- `zoom`: Map zoom level.

### Events

- `onClick`: Trigger onClick actions when the map is clicked, returns `_event` object:
- `event`: event object
- `lat`: latitudinal coordinate
- `lng`: longitudinal coordinate
- `maps`: has functions removed
- `x`: position on map block
- `y`: position on map block
- `onClickMarker`: Trigger onClick actions when a marker is clicked, returns `_event` object:
- `domEvent`: event object
- `latLng`:
- `lat`: latitudinal coordinate
- `lng`: longitudinal coordinate
- `maps`: has functions removed
- `pixel`:
- `x`
- `y`
- `onDrag`: Trigger onDrag actions when a map is dragged, returns `_event` object:
- `maps`: has functions removed
- `onDragEnd`: Trigger onDragEnd actions when a map is finished being dragged, returns `_event` object:
- `maps`: has functions removed
- `onGoogleApiLoaded` Trigger onGoogleApiLoaded actions when the map api is loaded, returns `_event` object:
- `maps`: has functions removed
- `onMapTypeIdChange`: Trigger onMapTypeIdChange actions when the map type is changed, returns `_event` object:
- `maps`: has functions removed
- `type`: the map
- `onTilesLoaded`: Trigger onTilesLoaded actions when the map tiles are loaded, returns `_event` object:
- `maps`: has functions removed
- `onZoomAnimationStart`: Trigger onZoomAnimationStart actions when the map is zoomed, returns `_event` object:
- `maps`: has functions removed
- `zoom`: map zoom level
- `onZoomAnimationEnd`: Trigger onZoomAnimationEnd actions after the map is zoomed, returns `_event` object:
- `maps`: has functions removed
- `zoom`: map zoom level

### Methods

- `addMarker`: Accepts a single parameter object `marker` with marker properties.
- `removeMarker`: Accepts a single parameter object `marker` with position property.
- `fitBounds`: Accepts a two parameters, `bounds` and `mapSize`.
- `addHeatmap`: Accepts a single parameter object `heatmap` with heatmap properties.
- `toggleHeatmap`: Doesn't require any parameters.

## Examples

Expand Down Expand Up @@ -166,6 +113,7 @@ types:
lng: 131.038
label: Two
```

2. Add a marker:

```yaml
Expand Down Expand Up @@ -198,6 +146,7 @@ types:
_event: lng
label: Hi
```

3. Remove a marker:

```yaml
Expand Down Expand Up @@ -234,6 +183,7 @@ types:
lng:
_state: latLng.lng
```

4. Fit bounds:

```yaml
Expand Down Expand Up @@ -268,6 +218,7 @@ types:
- width: 640 # Map width in pixels
height: 380 # Map height in pixels
```

5. Add a heatmap:

```yaml
Expand Down Expand Up @@ -351,6 +302,7 @@ types:
radius: 20
opacity: 1
```

6. Add a heatmap after api has loaded:

```yaml
Expand Down Expand Up @@ -392,6 +344,7 @@ types:
radius: 20
opacity: 1
```

7. Toggle a heatmap

```yaml
Expand All @@ -418,6 +371,67 @@ types:
method: toggleHeatmap
```

## Development

Running this block locally:

1. You must have [node](https://nodejs.org/en/) and [yarn](https://yarnpkg.com/getting-started/install) installed.
2. Clone this repository.
3. Run `yarn install`, then `yarn start`, then check the you block is served by viewing the meta data at: `http://localhost:3002/meta/GoogleMaps.json`.
4. Add the `types` to your lowdefy.yaml file. For example:

```yaml
name: my-app
lowdefy: 3.22.0
types:
GoogleMaps:
url: http://localhost:3002/meta/GoogleMaps.json
# ...
```

5. Use your new block type in your Lowdefy app.

```yaml
- id: google_maps
type: GoogleMaps
loading:
type: Skeleton
properties:
height: 500
properties:
bootstrapURLKeys:
key: ''
libraries: ['visualization']
mapOptions:
zoomControl: true
fullscreenControl: true
styles:
- stylers:
- saturation: -100
- gamma: 0.8
- lightness: 4
- visibility: on
zoom: 14
center:
lat: -25.344
lng: 131.036
height: 500 # defaults to 500 when not set
style: # overrides the map block's default style
height: 550 # overrides the 'height: 500' property of the map block
width: 100%
markers:
- position:
lat: -25.344
lng: 131.036
label: Hi
# ...
```

6. Start your Lowdefy app and test if it works, run: `npx lowdefy@latest dev`
7. Continue to develop your block React component. Changes to your block will need to auto reload the app in the browser, you need to hit refresh.
8. Before deploying your blocks to a static file server, remember to change the `remoteEntryUrl` field in the `webpack.prod.js` file to your block URL.
9. Deploy your blocks and enjoy your ☕️.

## Other Lowdefy Blocks Packages

- [@lowdefy/blocks-basic](https://github.com/lowdefy/lowdefy/tree/main/packages/blocks/blocksBasic): Official Lowdefy blocks some basic Html elements.
Expand Down