<commit_before>## map-tools 2.0.2

[![Build](https://travis-ci.org/yagoferrer/map-tools.svg?branch=master)](https://travis-ci.org/yagoferrer/map-tools)
[![Coverage](https://coveralls.io/repos/yagoferrer/map-tools/badge.svg?branch=master)](https://coveralls.io/r/yagoferrer/map-tools)
[![Code Climate](https://codeclimate.com/github/yagoferrer/map-tools/badges/gpa.svg?branch=master)](https://codeclimate.com/github/yagoferrer/map-tools)
[![Dependency Status](https://david-dm.org/yagoferrer/map-tools.svg)](https://david-dm.org/yagoferrer/map-tools)
[![devDependency](https://david-dm.org/yagoferrer/map-tools/dev-status.svg)](https://david-dm.org/yagoferrer/map-tools#info=devDependencies)

[map-tools](http://map-tools.io/) is a Google Maps Feature-rich Javascript wrapper that makes things like:
[Marker Tagging](#tags); [asynchronous loading](#lazy-loading-the-map), working with [TopoJSON](#topojson-support) or [GeoJSON](#geojson-support), [custom controls](#add-panel), [animation](#animate-markers) and more. Much simpler with an easy-to-use API.


## Benefits
- Less Code: The [Google Maps API](https://developers.google.com/maps/documentation/javascript/reference) it is of considerable size. You'll be writing way **less** code with map-tools.js
- It helps you to keep track of elements created on the Map. Use [findMarker()](#find-marker) to find Markers by properties.
- More Fun: Add [Marker animations](#animate-markers), use [handlebars style](#info-window) variables.
- Non Intrusive: it extends the API; you can use any other native methods, properties and events anywhere.
- Query elements on the Map to update their options using [Crossfilter](#crossfilter-support-for-markers)
- [TopoJSON Support](#topojson-support): Add Topo/GeoJSON files, set styles and find references easier.
- Well tested. Good GPA rating.
- Framework agnostic.
- My ultimate goals are performance and Google API simplification.

## Get Started

it is recommended to use [npm](https://docs.npmjs.com/getting-started/what-is-npm) to install `map-tools` but you can also use *bower*.

NPM:
```bash
npm install map-tools --save-dev
```

Bower:
```bash
bower install map-tools --save-dev
```

Do you need to download it now? Use the direct download link. [map-tools.min.js](https://github.com/yagoferrer/map-tools/blob/2.0.2/dist/map-tools.min.js)

## Need Quick Examples?

Go to: [map-tools.io](http://map-tools.io/)

or pull the repo and run:
```bash
npm start
```

### Lazy Loading the Map
You can load the Google Maps JavaScript file asynchronously. This is useful for example: if you are planning on loading the Map on a different view from the Homepage.
Setting a callback function will help you to now when the Map is ready to be used.

If you don't want to lazy load the map, use the option `async: false` you can still keep the callback function to determine when the Map is ready to be used.

[Live example] (http://map-tools.io/examples/simple.map.html)

```javascript
var map = new mapTools({
  id: 'mymap',
  lat: 41.3833,
  lng: 2.1833,
  key: 'Your Google Maps API Key'
}, function (err, map) {
  if (!err) {
    console.log('Map Loaded!', map.instance);
  }
});
```

The first argument `id` represents the `id` of the HTML element container where you want to display the Map. If you want to use a `class` instead use `el: '.mymap'` to indicate the class name.


`lat` and `lng` are the coordenates used to first load the Map.

The callback function contains two arguments:
- `err` it will contain an error object in case something goes wrong during Map initialization.
- `map` the mapTools instanciated object. You can use this to trigger further API calls.

`id`, `lat` and `lng` are custom helpers that added to quicky create a Map but you can add many other *native* [Map Options](https://developers.google.com/maps/documentation/javascript/reference#MapOptions) take a look to the Google Maps reference.

Here it is what I think some other useful options:
```javascript
{
  disableDoubleClickZoom: true, // Disable double click zoom in google maps while drawing.
  streetViewControl: false // Disables the street view mode.
  scaleControl: true // Scale control that provides a simple map scale.
}
```

#### Map Option Helpers
This Google property is silly: `google.maps.MapTypeId.SATELLITE`. With map-tools, you can simple use:
```javascript
{
  type: 'SATELLITE'
}
```
Other types are: ROADMAP, HYBRID and TERRAIN.


## HTML

Don't forget to add a simple HTML tag to indicate where to render the Map.

```html
<div id="mymap"></div>
```

### Google Maps Native Instance
Sometimes you just need to go straight to the Google Maps API.
Once the Map is initialized you can either use: `map.instance` or globally `mapTools[YourMapId].instance`.
Notice that if you have multiple Maps, you can access all from the global scope.

### Map Events
Adding listeners for Map events it is easy. You can add handlers for any of the [Native Map Events] (https://developers.google.com/maps/documentation/javascript/events) using the `on` syntax.

[Live example](http://map-tools.io/examples/simple.map.html)

```javascript
var map = new mapTools({
  on: {
      zoom_changed: function() {
        console.log('the zoom level has changed!', map.zoom())
      }
  }
```
### Custom Map Events
- `marker_visibility_changed` it will get trigger anytime that any Marker changes visibility state.

[Live example](http://map-tools.io/examples/custom.events.html)
```javascript
var map = new mapTools({
  on: {
      marker_visibility_changed: function(numOfVisibleMarkers) {
        console.log('we have a total of %d visible Markers', numOfVisibleMarkers)
      }
  }
```
This event it is very useful if you are planning for example on clustering based on this value.

## Map Methods

#### Update Map
Apply *ANY* option to the Map by calling the `updateMap()` method like this example:

[Live example](http://map-tools.io/examples/update.map.html)
```javascript
map.updateMap({type: 'TERRAIN'});
```

#### Center Map
There are two ways you can use this method:
- Center the current Map using coordinates provided during initialitation.
```javascript
map.center();
```
- Pass specific latitude and longitude coordinates to jump into a location.
```javascript
map.center(41.3833, 2.1833);
```

#### Zoom Map
With this method you can either:
- Retrive the current Map Zoom Level
```javascript
map.zoom();
// Result: 8
```
- Set the Map to specific Zoom level.
```javascript
map.zoom(12);
```

#### Get Current Map Center Position
```javascript
map.locate()
// Result: {lat: 41.3833, lng: 2.1833}
```

## Markers
Adding Markers is simple. Use the `addMarker()` method to add **one or multiple** Markers at the same time. The method will return a reference of the Marker(s) added. It will also save a reference under `map.markers.all[uid]` The uid is either
an unique value that you can provide under `data.uid` or a self-generated value created by map-tools.

[Live example](http://map-tools.io/examples/add.marker.html)

```javascript
map.addMarker([{
  lat: 41.3833,
  lng: 2.1833,
  key: 'The Google API Key',
  title: 'Barcelona',
  on: {
    click: function() {
      alert(this.title);<commit_msg>No need key for add marker<commit_after>## map-tools 2.0.2

[![Build](https://travis-ci.org/yagoferrer/map-tools.svg?branch=master)](https://travis-ci.org/yagoferrer/map-tools)
[![Coverage](https://coveralls.io/repos/yagoferrer/map-tools/badge.svg?branch=master)](https://coveralls.io/r/yagoferrer/map-tools)
[![Code Climate](https://codeclimate.com/github/yagoferrer/map-tools/badges/gpa.svg?branch=master)](https://codeclimate.com/github/yagoferrer/map-tools)
[![Dependency Status](https://david-dm.org/yagoferrer/map-tools.svg)](https://david-dm.org/yagoferrer/map-tools)
[![devDependency](https://david-dm.org/yagoferrer/map-tools/dev-status.svg)](https://david-dm.org/yagoferrer/map-tools#info=devDependencies)

[map-tools](http://map-tools.io/) is a Google Maps Feature-rich Javascript wrapper that makes things like:
[Marker Tagging](#tags); [asynchronous loading](#lazy-loading-the-map), working with [TopoJSON](#topojson-support) or [GeoJSON](#geojson-support), [custom controls](#add-panel), [animation](#animate-markers) and more. Much simpler with an easy-to-use API.


## Benefits
- Less Code: The [Google Maps API](https://developers.google.com/maps/documentation/javascript/reference) it is of considerable size. You'll be writing way **less** code with map-tools.js
- It helps you to keep track of elements created on the Map. Use [findMarker()](#find-marker) to find Markers by properties.
- More Fun: Add [Marker animations](#animate-markers), use [handlebars style](#info-window) variables.
- Non Intrusive: it extends the API; you can use any other native methods, properties and events anywhere.
- Query elements on the Map to update their options using [Crossfilter](#crossfilter-support-for-markers)
- [TopoJSON Support](#topojson-support): Add Topo/GeoJSON files, set styles and find references easier.
- Well tested. Good GPA rating.
- Framework agnostic.
- My ultimate goals are performance and Google API simplification.

## Get Started

it is recommended to use [npm](https://docs.npmjs.com/getting-started/what-is-npm) to install `map-tools` but you can also use *bower*.

NPM:
```bash
npm install map-tools --save-dev
```

Bower:
```bash
bower install map-tools --save-dev
```

Do you need to download it now? Use the direct download link. [map-tools.min.js](https://github.com/yagoferrer/map-tools/blob/2.0.2/dist/map-tools.min.js)

## Need Quick Examples?

Go to: [map-tools.io](http://map-tools.io/)

or pull the repo and run:
```bash
npm start
```

### Lazy Loading the Map
You can load the Google Maps JavaScript file asynchronously. This is useful for example: if you are planning on loading the Map on a different view from the Homepage.
Setting a callback function will help you to now when the Map is ready to be used.

If you don't want to lazy load the map, use the option `async: false` you can still keep the callback function to determine when the Map is ready to be used.

[Live example] (http://map-tools.io/examples/simple.map.html)

```javascript
var map = new mapTools({
  id: 'mymap',
  lat: 41.3833,
  lng: 2.1833,
  key: 'Your Google Maps API Key'
}, function (err, map) {
  if (!err) {
    console.log('Map Loaded!', map.instance);
  }
});
```

The first argument `id` represents the `id` of the HTML element container where you want to display the Map. If you want to use a `class` instead use `el: '.mymap'` to indicate the class name.


`lat` and `lng` are the coordenates used to first load the Map.

The callback function contains two arguments:
- `err` it will contain an error object in case something goes wrong during Map initialization.
- `map` the mapTools instanciated object. You can use this to trigger further API calls.

`id`, `lat` and `lng` are custom helpers that added to quicky create a Map but you can add many other *native* [Map Options](https://developers.google.com/maps/documentation/javascript/reference#MapOptions) take a look to the Google Maps reference.

Here it is what I think some other useful options:
```javascript
{
  disableDoubleClickZoom: true, // Disable double click zoom in google maps while drawing.
  streetViewControl: false // Disables the street view mode.
  scaleControl: true // Scale control that provides a simple map scale.
}
```

#### Map Option Helpers
This Google property is silly: `google.maps.MapTypeId.SATELLITE`. With map-tools, you can simple use:
```javascript
{
  type: 'SATELLITE'
}
```
Other types are: ROADMAP, HYBRID and TERRAIN.


## HTML

Don't forget to add a simple HTML tag to indicate where to render the Map.

```html
<div id="mymap"></div>
```

### Google Maps Native Instance
Sometimes you just need to go straight to the Google Maps API.
Once the Map is initialized you can either use: `map.instance` or globally `mapTools[YourMapId].instance`.
Notice that if you have multiple Maps, you can access all from the global scope.

### Map Events
Adding listeners for Map events it is easy. You can add handlers for any of the [Native Map Events] (https://developers.google.com/maps/documentation/javascript/events) using the `on` syntax.

[Live example](http://map-tools.io/examples/simple.map.html)

```javascript
var map = new mapTools({
  on: {
      zoom_changed: function() {
        console.log('the zoom level has changed!', map.zoom())
      }
  }
```
### Custom Map Events
- `marker_visibility_changed` it will get trigger anytime that any Marker changes visibility state.

[Live example](http://map-tools.io/examples/custom.events.html)
```javascript
var map = new mapTools({
  on: {
      marker_visibility_changed: function(numOfVisibleMarkers) {
        console.log('we have a total of %d visible Markers', numOfVisibleMarkers)
      }
  }
```
This event it is very useful if you are planning for example on clustering based on this value.

## Map Methods

#### Update Map
Apply *ANY* option to the Map by calling the `updateMap()` method like this example:

[Live example](http://map-tools.io/examples/update.map.html)
```javascript
map.updateMap({type: 'TERRAIN'});
```

#### Center Map
There are two ways you can use this method:
- Center the current Map using coordinates provided during initialitation.
```javascript
map.center();
```
- Pass specific latitude and longitude coordinates to jump into a location.
```javascript
map.center(41.3833, 2.1833);
```

#### Zoom Map
With this method you can either:
- Retrive the current Map Zoom Level
```javascript
map.zoom();
// Result: 8
```
- Set the Map to specific Zoom level.
```javascript
map.zoom(12);
```

#### Get Current Map Center Position
```javascript
map.locate()
// Result: {lat: 41.3833, lng: 2.1833}
```

## Markers
Adding Markers is simple. Use the `addMarker()` method to add **one or multiple** Markers at the same time. The method will return a reference of the Marker(s) added. It will also save a reference under `map.markers.all[uid]` The uid is either
an unique value that you can provide under `data.uid` or a self-generated value created by map-tools.

[Live example](http://map-tools.io/examples/add.marker.html)

```javascript
map.addMarker([{
  lat: 41.3833,
  lng: 2.1833,
  title: 'Barcelona',
  on: {
    click: function() {
      alert(this.title);
{'fraction_non_alphanumeric': 0.12452987881320518, 'fraction_numerical': 0.007382643822259368, 'mean_word_length': 4.3399033097805875, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 30, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '995051', 'n_tokens_mistral': 4564, 'n_tokens_neox': 4307, 'n_words': 1637}