Mapify - Google Maps jQuery Plugin


Contents

- Third Party Libraries
- Installation
- The Big Picture
- Creating a Map
- Map with a Single Marker
- Map with Multiple Markers
- Basic Options
- Map Center Position
- Gesture Handling
- Zoom Level
- Zoom on Scroll
- Map Background Color
- Map Types
- Map Controls
- Map Control Positioning
- Custom Map Styles
- Custom Marker Icons
- Custom Default Icon
- Custom Icon on Marker Hover
- Custom Icon when Info Window is Open
- Marker Label and Title
- Fit Markers on the Map
- Fit All Markers on the Map
- Fit Specific Markers on the Map
- Fit Markers on the Map with Extra Padding
- Marker Clustering
- Cluster Options
- Cluster Tooltip
- Center Cluster Icon
- Cluster Grid Size
- Cluster Min Size
- Cluster Max Zoom
- Cluster Zoom on Click
- Cluster Retina Icons
- Cluster Icon
- Cluster Icon Size
- Cluster Icon Text Color
- Cluster Icon Text Size
- Multiple / Advanced Cluster Icons
- Dynamic Cluster Text, Tooltip and Icon
- Marker Spiderfier
- Spiderfy Options
- Trigger Marker Click Event when Spiderfying
- Spider Leg Colors
- Advanced Spiderfier Options
- Auto Pan to Marker with its HTML Element
- Add Class to Marker Element on Hover
- Add Class to Marker Element when Info Window is Open
- Info Window
- Inline Info Window
- Info Window via Selector
- Automatically Detect Info Window
- Single Info Window on the Map
- Info Window Options
- Info Window Max Width
- Info Window Groups
- Open Info Window on Load
- Open Info Window on Click or Hover (Marker Object)
- Open Info Window on Click or Hover (Marker Element)
- Close Info Windows on Map Click
- Events
- Development
- Changelog
- License

Third Party Libraries

This plugin requires a few 3rd party libraries to fully function.

- jQuery
- Google Maps API

The following packages are compiled into the main plugin version (mapify.min.js),
but if you want you can download the scripts manually and use the core plugin version (mapify.core.min.js) instead.

- Google Maps MarkerClustererPlus
- OverlappingMarkerSpiderfier

Installation

$3

``
bower install codezero-mapify --save
`

$3

`
npm install codezero-mapify --save
`

$3

You probably want to create an API key to work with the Google Maps API. You can use the API without a key, but there will be a warning in the console window and I don't know what restrictions apply.

`html




`

> The initMap function will be called when the Google Maps script is loaded.

$3

Make sure your map has a width and a height.

`html

`

The Big Picture

My goal with this plugin is to make it as easy and as powerful as you need it to be.

The map is configurable via javascript options when you invoke the plugin. These are considered your default settings for every map on your page (that falls under your .map selector of course).

`javascript
$('.map').mapify({
zoom: 8
});
`

Alternatively you can apply the same options with data attributes on the .map element. These will override their javascript equivalent if both exist.

`html


> In any case you will need a map element and run .mapify() on it with jQuery. Where you put the options is up to you.

Creating a Map

$3

If you only need to show one marker on a map, it couldn't be simpler:

`html



`

This will add a default marker on the lat and lng coordinates and center the map there.

This is the equivalent of doing:

`html



`

> The values of the data attributes will always take precedence over the javascript options!

$3

Creating a map with multiple markers is basically the same as the previous example, except that you omit the lat and lng options and instead use marker objects or elements.

You can add marker objects with a javascript array:

`html



`

Or you can refer to HTML elements using any selector you want:

`html



`

You can also set the marker selector with a data-markers attribute:

`html



`

> If you set a data-markers attribute, but also an array in javascript, the array will be ignored.

The HTML marker elements could look like this minimal setup:

`html


• Marker A


• Marker B

> You can use any HTML structure, it doesn't have to be a ul. Just make sure the selector matches and your markers have the necessary data attributes.

Basic Options

$3

Default: first marker's position

When the fitbounds option is set to false, the map will be centered on on the first (or only) marker's lat and lng coordinates by default.

You can override the default center point in a few ways.

#### By defining an explicit center position...

With javascript options:

`javascript
$('.map').mapify({
lat: 51.251245,
lng: 4.497890,
centerLat: 50.963258,
centerLng: 3.706874
});
`

Or with data attributes to the map

`html


`javascript
$('.map').mapify({
markers: [
{ lat: 51.251245, lng: 4.497890 },
{ lat: 50.963258, lng: 3.706874, center: true }
]
});
`

Or by adding a data-center attribute to a marker element:

``html


• data-lat="51.251245"
  data-lng="4.497890">
  Marker A
  


• data-lat="50.963258"
  data-lng="3.706874"
  data-center="true">
  Marker B
  

Default: 'cooperative'

Straight from the Google Maps documentation:

'none': The map cannot be panned or zoomed by user gestures.

'greedy': All touch gestures pan or zoom the map.

'cooperative': Two-finger touch gestures pan and zoom the map. One-finger touch gestures are not handled by the map. In this mode, the map cooperates with the page, so that one-finger touch gestures can pan the page.

'auto': Gesture handling is either cooperative or greedy, depending on whether the page is scrollable or not.

Set one of the above values with javascript:

`javascript
$('.map').mapify({
gestures: 'cooperative'
});
`

Or with a data attribute:

`html


Default: 15

The initial zoom level can be set to a value between 1 and 20, where 1 is the most zoomed out.
This option has no effect while the fitbounds option is set to true (see: Fit Markers on the Map).

- 1: World
- 5: Landmass/continent
- 10: City
- 15: Streets
- 20: Buildings

With javascript:

`javascript
$('.map').mapify({
zoom: 8
});
`

With a data attribute:

`html


Default: false

To enable zooming with the scrollwheel of the mouse, set the scrollwheel option to true.

With javascript:

`javascript
$('.map').mapify({
scrollwheel: true
});
`

With a data attribute:

`html


Default: '#ffffff'

The background color of the map that is visible when map tiles are not yet loaded.

Set it via javascript:

`javascript
$('.map').mapify({
backgroundColor: '#ffffff'
});
`

Or with a data attribute:

``html


Default: 'roadmap'

The available map types you want the user to be able to switch between.
This can be a comma separated string or an array.
The first type is the initial map type to show.
If you only set one type, the UI control will be hidden.

Available map types:

- 'roadmap'
- 'terrain'
- 'satellite'
- 'hybrid'

Set it via javascript:

`javascript
$('.map').mapify({
mapTypes: ['roadmap', 'satellite']
});
`

Or with a data attribute:

``html


Default: 'zoom'

The UI controls you want to enable. This can be a comma separated string or an array.
If you want to disable all controls, set an empty string or array or just 'none' as the value.

> Note: The mapTypeControl is enabled automatically if you set more than one value in the mapTypes option.

Available controls:

- 'zoom'
- 'fullscreen'
- 'streetview'
- 'rotate'
- 'scale'

Set it via javascript:

`javascript
$('.map').mapify({
controls: ['zoom', 'fullscreen']
});
`

Or with a data attribute:

``html


- 'BOTTOM_CENTER'
- 'BOTTOM_LEFT'
- 'BOTTOM_RIGHT'
- 'LEFT_BOTTOM'
- 'LEFT_CENTER'
- 'LEFT_TOP'
- 'RIGHT_BOTTOM'
- 'RIGHT_CENTER'
- 'RIGHT_TOP'
- 'TOP_CENTER'
- 'TOP_LEFT'
- 'TOP_RIGHT'

Via javascript:

`javascript
$('.map').mapify({
mapTypeControlPosition: 'TOP_LEFT',
zoomControlPosition: 'RIGHT_BOTTOM',
fullscreenControlPosition: 'TOP_RIGHT',
streetviewControlPosition: 'RIGHT_BOTTOM',
rotateControlPosition: 'RIGHT_BOTTOM'
});
`

Or with data attributes:

``html


An easy way to make a map blend in with the rest of your website is to create or find a theme or custom styles. One great resource for premade Google Maps themes is SnazzyMaps. Applying one is also easy: open a theme, copy its "javascript style array" and set it as the value of the styles option.

Note that for satellite/hybrid and terrain modes, these styles will only apply to labels and geometry.

This option can only be set via javascript.

`javascript
$('.map').mapify({
styles: / styles array here /
});
`

$3

Default: standard Google icons

#### Custom Default Icon

To use a custom image as a marker, set one or more of the following options:

`javascript
$('.map').mapify({
icon: '/path/to/marker.png',
iconSize: '40,40',
iconOrigin: '0,0',
iconAnchor: '0,40'
});
`

Or use the data attributes:

`html


The size, origin and anchor are optional. All three expect two numbers, separated by a comma, representing x and y coordinates relative to the icon. An origin of 0,0 means the top left corner of the icon. An anchor (where it "points") of 0,40 means the bottom left corner in the example.

You can further override the icon settings per marker by defining the same options on a marker.

On a marker object:

`javascript
$('.map').mapify({
markers: [
{
lat: 51.251245,
lng: 4.497890,
icon: '/path/to/marker.png',
iconSize: '40,40',
iconOrigin: '0,0',
iconAnchor: '0,40'
}
]
});
`

On a marker element:

``html


• data-lat="51.251245"
  data-lng="4.497890"
  data-icon="/path/to/marker.png"
  data-icon-size="40,40"
  data-icon-origin="0,0"
  data-icon-anchor="0,40">
  Marker A
  

`
iconHover: '/path/to/marker.png',
iconHoverSize: '40,40',
iconHoverOrigin: '0,0',
iconHoverAnchor: '0,40'
`

Or use the data attributes:

`
data-icon-hover="/path/to/marker.png"
data-icon-hover-size="40,40"
data-icon-hover-origin="0,0"
data-icon-hover-anchor="0,40">
`

#### Custom Icon when Info Window is Open

And another icon can be used when a marker's info window is open.

If you don't specify the size, origin or anchor, the default (custom) icon settings will be used.

In javascript:

`
iconOpen: '/path/to/marker.png',
iconOpenSize: '40,40',
iconOpenOrigin: '0,0',
iconOpenAnchor: '0,40'
`

Or use the data attributes:

`
data-icon-open="/path/to/marker.png"
data-icon-open-size="40,40"
data-icon-open-origin="0,0"
data-icon-open-anchor="0,40">
`

$3

Default: none

The label is some text that is shown on a marker image. The title is a small tooltip that appears when you hover over a marker and is basically the same as a normal title HTML attribute.

You can set it on the marker object:

`javascript
$('.map').mapify({
markers: [
{
lat: 51.251245,
lng: 4.497890,
label: 'A',
title: 'Some more information...'
}
]
});
`

Or on the marker element:

``html


• data-lat="51.251245"
  data-lng="4.497890"
  data-label="A"
  data-title="Some more information...">
  Marker A
  

Default: false if only 1 marker, true if more than 1 marker

Most likely you will want all of your markers to show up on the map initially. So if you add more than one marker, the fitbounds option is set to true by default. This will override any zoom level and center position you have set. If you do want to take control over this yourself, you can set fitbounds to false.

With javascript:

`javascript
$('.map').mapify({
fitbounds: false
});
`

With a data attribute:

`html


Default: true for all markers

If you only want to zoom in on a few important markers initially, you can add a fitbounds option only to those markers. You don't have to disable fitbounds on the map, this is done automatically when the option is detected on a marker.

With javascript:

`javascript
$('.map').mapify({
markers: [
{ lat: 51.251245, lng: 4.497890, fitbounds: true },
{ lat: 50.963258, lng: 3.706874, fitbounds: true }
]
});
`

With a data attribute:

``html


• data-lat="51.251245"
  data-lng="4.497890"
  data-fitbounds="true">
  Marker A
  


• data-lat="50.963258"
  data-lng="3.706874"
  data-fitbounds="true">
  Marker B
  

> Note from Google Maps Reference: When the map is set to display: none, the fitBounds function reads the map's size as 0x0, and therefore does not do anything. To change the viewport while the map is hidden, set the map to visibility: hidden, thereby ensuring the map div has an actual size.

$3

Default: 50

The fitboundsPadding option is not well documented by Google, but after some experimenting it seems to work as follows… You set a pixel value that adds a "padding zone" to the map's boundaries. Google Maps will keep zooming in until one of your markers gets within the padding zone. This option can only be set on the map, as it doesn't make sense to set in on multiple markers.

With javascript:

`javascript
$('.map').mapify({
fitbounds: true,
fitboundsPadding: 50
});
`

With a data attribute:

`html


Default: true up to a zoom level of 15

When 2 or more markers are too close and would overlap, those markers will be replaced by a new cluster icon, showing how many markers there are in that area. Clicking the cluster will zoom in and fit its markers on the map.

> Marker clustering will only work when markerclusterer.js is loaded. This script is already included in mapify.min.js.

If you don't want marker clustering, you can disable it.

With javascript:

`javascript
$('.map').mapify({
clusters: false
});
`

With a data attribute:

`html


Default: '' (no tooltip)

Show a default browser tooltip when hovering over a cluster icon.

- clusterTitle: 'Click to see markers!' (JavaScript)
- data-cluster-title="Click to see markers!" (HTML)

$3

Default: true

Position the cluster icon in the center of its markers if set to true, or on top of the first marker if set to false.

- clusterCenter: true (JavaScript)
- data-cluster-center="true" (HTML)

$3

Default: 40

How close markers need to be to eachother before being clustered. The lower the value, the closer the markers need to be.

- clusterGridSize: 40 (JavaScript)
- data-cluster-grid-size="40" (HTML)

$3

Default: 2

The minimum number of markers that should be clustered.

- clusterMinSize: 2 (JavaScript)
- data-cluster-min-size="2" (HTML)

$3

Default: 15 (street level)

The maximum zoom level that markers will be clustered.

- clusterMaxZoom: 15 (JavaScript)
- data-cluster-max-zoom="15" (HTML)

$3

Default: true

When you click on a cluster icon, zoom in to fit the cluster's markers on the map.

- clusterZoomOnClick: true (JavaScript)

- data-cluster-zoom-on-click="true" (HTML)

$3

Default: true

Enable the use of retina images as a cluster icon.

- clusterRetina: true (JavaScript)
- data-cluster-retina="true" (HTML)

If this is true, sprites cannot be used as cluster icons (advanced).

$3

Default: /images/cluster.png

You can change the default cluster icon by setting a few basic options.

- clusterIcon: '/path/to/icon.png' (JavaScript)
- data-cluster-icon="/path/to/icon.png" (HTML)

$3

Default: '50,50'

The default width and height is 50 pixels. You must either save your image in that size, or specify the correct actual width and height of your image. The option expects a value of 'width,height'.

- clusterIconSize: '50,50' (JavaScript)
- data-cluster-icon-size="50,50" (HTML)

> Important Note! If the sizes don't match the actual image sizes, the text inside the cluster will not be positioned correctly.

$3

Default: '#ffffff'

- clusterTextColor: '#ffffff' (JavaScript)
- data-cluster-text-color="#ffffff" (HTML)

$3

Default: 12

- clusterTextSize: 12 (JavaScript)
- data-cluster-text-size="12" (HTML)

$3

If you set the clusterIcons option, you override the basic icon options with advanced settings. The option expects an array of ClusterIconStyle objects. This also allows you to define multiple cluster icons. This can only be set via javascript.

For example:

``javascript
$('.map').mapify({
clusterIcons: [
{
// Required:
width: 50, //=> actual image width !!!
height: 50, //=> actual image height !!!
url: '/path/to/icon.png',
// Optional:
backgroundPosition: '0, 0', //=> 'X, Y' (mind the space!)
anchorIcon: [25, 25], //=> [Y,X] (defauls to center of the icon)
anchorText: [0, 0], //=> [Y,X] (from the center of the icon)
textColor: '#000000',
textSize: 11,
textDecoration: 'none',
fontFamily: 'Arial, sans-serif',
fontStyle: 'normal',
fontWeight: 'bold'
},
{
...
}
]
});
`

With the clusterCalculator function (see below) you can choose to show specific icons based on the markers and the number of available icons.

$3

Using the clusterCalculator function, you can choose what text to display inside of the icon, what tooltip (title) to show on hover and which icon from the clusterIcons array to show, based on the cluster's markers and the number of available icons.

`javascript
$('.map').mapify({
clusterCalculator: function (markers, totalAvailableIcons) {
var index = 0,
title = '',
count = markers.length.toString();

// Your logic here...

return {
text: count,
index: index,
title: title
};
}
});
`

This is the default function, taken from markerclusterer.js, which will show the next icon in the array for every ten markers in the cluster:

`javascript
function (markers, totalAvailableIcons) {
var index = 0,
title = '',
count = markers.length.toString(),
dv = count;

while (dv !== 0) {
dv = parseInt(dv / 10, 10);
index++;
}

index = Math.min(index, totalAvailableIcons);

return {
text: count,
index: index,
title: title
};
}
`

Marker Spiderfier

Default: true

By default, when the map is zoomed in to street level (15), markers that are too close to each other will no longer be clustered.
Instead, the markers will be spiderfied. This will move the markers away from each other in a circular path so they can be clicked easily.

> The Marker Spiderfier will only work when OverlappingMarkerSpiderfier is loaded. This script is already included in mapify.min.js.

If you don't want to spiderfy markers, you can disable it.

With javascript:

`javascript
$('.map').mapify({
spiderfy: false
});
`

With a data attribute:

`html


Default: true

Trigger the click event on a marker even when it (un)spiderfies nearby markers.

- spiderClick: true (JavaScript)
- data-spider-click="true" (HTML)

$3

These options can only be set via javascript, as it would get a bit ugly with data attributes.

Here are the default settings... You can also add custom map types.

`javascript
$('.map').mapify({
spiderLegColors: {
roadmap: '#444',
terrain: '#444',
satellite: '#fff',
hybrid: '#fff'
},
spiderLegColorsHighlighted: {
roadmap: '#f00',
terrain: '#f00',
satellite: '#f00',
hybrid: '#f00'
}
});
`

Advanced Spiderfier Options

There are some advanced options for the Spiderfier that you can set via javascript.
This options accepts any constructor option from OverlappingMarkerSpiderfier.

Your options will be merged with these defaults:

`javascript
$('.map').mapify({
spiderfierOptions: {
markersWontMove: true, //=> set true for performance if markers will not be moved
markersWontHide: false, //=> set true for performance if markers will not be hidden
keepSpiderfied: true, //=> keep spider open when one of its markers is clicked
ignoreMapClick: false, //=> keep spider open when the map is clicked
nearbyDistance: 20,
circleSpiralSwitchover: 9,
legWeight: 2,

// With the "onSpiderMarkerFormat" event handler you can manipulate
// the marker based on its spider state (spiderfied/unspiderfied/...).
//
// Set this option to true if you only need to detect
// the "SPIDERFIED" and (initial) "UNSPIDERFIED" state changes.
// This will trigger the event on each affected marker when
// it is spiderfied and unspiderfied.
//
// Set this option to false if you need to detect
// the "SPIDERFIED", "SPIDERFIABLE" and "UNSPIDERFIABLE" states.
// This will additionally trigger the event on every marker
// when the map loads and zoom level changes.
// So setting this option to true is a performance boost!
basicFormatEvents: true
}
});
`

Auto Pan to Marker with its HTML Element

Default: false

If you create marker HTML elements, you can automatically pan and zoom to the related marker on the map when you click on or hover over the element.
When enabled, the marker will be centered on the map and if the marker is clustered, the map will zoom in until it is unclustered.

This behavior is disabled by default, but you can configure this on the map, using these possible values..

Pan to marker only if it is clustered or outside the map's boundaries:

- click
- hover

Pan to marker even if it's within the map's boundaries:

- 'hover-always'
- 'click-always'

Disable panning (default):

- false

With javascript:

`javascript
$('.map').mapify({
panToMarker: 'click'
});
`

With a data attribute:

`html


Default: null

When you create marker HTML elements, a class can be added whenever you hover over such an element or its related marker on the map.

You set this option on the map. This is disabled by default.

With javascript:

`javascript
$('.map').mapify({
hoverClass: 'marker-hover'
});
`

With a data attribute:

`html


Default: null

If you create marker HTML elements with info windows, a class can be added to the marker element when its info window is opened on the map.

You set this option on the map. This is disabled by default.

With javascript:

`javascript
$('.map').mapify({
openClass: 'marker-open'
});
`

With a data attribute:

`html


`javascript
$('.map').mapify({
markers: [
{ lat: 51.251245, lng: 4.497890, infoWindow: '

INFO

You can't really write HTML in a data attribute, but you could get away with some simple text...
Do note that strings starting with a . or # are handled as selectors.
As usual, the data attribute will override the javascript setting.

``html


• data-lat="51.251245"
  data-lng="4.497890"
  data-info-window="Very basic info...">
  Marker A
  

A slightly better approach is to create any