Map

Properties

Property Type Description
components Object Holds the map's component arrays. All components added to the map will be stored within their respective component array.
controls Array<MVCArray> A reference to the map's native control property.
data Data A reference to the map's native data property.
obj Map A reference to the native google map object.
settings Object Holds the map's local settings.

Initializing

By default the map will be initialized inside the DOM element with an id of gmap. All default settings can be overwritten by passing in an object during initialization.

MapId, center and zoom are required. All three have default values.
Copy
var myMap = new gmap({
  mapId: "myMap",  // use DOM element with an id of myMap
  mapOptions: {
    mapTypeId: "satellite",
    zoom: 12
  }
})

Add components

To add components to the map, use the add method and specify the component type and options.

Every component must be assigned an id when it is added to the map. If an id is not specified, gmaps will autogenerate one for you.
Copy
myMap.add("marker", {
  id: "myMarker",
  position: {
    lat: 37.5,
    lng: -120
  }
})

To add multiple components at once, you can pass in an array of options as the second parameter.

Copy
myMap.add("markers", [
  {
    id: 43,
    position: {
      lat: 37.5,
      lng: -120
    }
  },
  ...
])

Remove components

To remove components from the map, use the remove method and specify the component type and the id(s).

If an id parameter is not supplied, it will remove all components of the specified type.

Copy
// single id
myMap.remove("marker", "myMarker")

// multiple ids
myMap.remove("markers", ["myMarker", 43])

// all markers
myMap.remove("markers")

Set options

To set the map's options after initialization, specify the option name and value. You can set multiple options at once by passing in an object as the only parameter.

This method is only for setting mapOptions. The map's other local settings must be updated manually.
Copy
// single option
myMap.setOptions("mapTypeId", "roadmap")

// multiple options
myMap.setOptions({
  mapTypeId: "roadmap",
  mapTypeControl: true
})

Get options

To get the value of a specifc option, pass in the option name. If you do not supply an option name, all the options will be returned in an object.

Copy
// get single option
myMap.getOptions("mapTypeId")

// get all options
myMap.getOptions()

Fit bounds

The fitBounds method works the same as the native method. It accepts a LatLngBounds and sets the map's viewport to it.

With gmaps, you can also pass in an object with the component(s) and id(s) you want to center the map's viewport on. Pass in null to select all components for that type.

Copy
myMap.fitBounds({
  markers: ["myMarker", 43],
  polygons: null  // select all polygons
})

You can also pass in initial to set the map's viewport to its initial value.

Copy
myMap.fitBounds("initial")

Geolocation

Gmaps leverages the HTML Geolocation API to center the map on the browser's current location. You can optionally pass in an object to overwrite the default options.

Copy
// default options
var defaults = {
  enableHighAccuracy: false,
  showMarkers: true,
  zoom: 12
})

myMap.geolocate({
  enableHighAccuracy: true,
  zoom: 16
})

Methods

Method Description
add(type, options) Adds the specified component(s) to the map.
circles(ids) Returns a CircleArray containing any circles with matching ids.
fitBounds(bounds) Sets the map's viewport to contain the given bounds. Can also pass in an object of component types and ids.
geolocate(options) Centers the map on the browser's current location.
getBounds() Returns the LatLngBounds of the map's current viewport.
getCenter() Returns the LatLng for the map's center.
getCenterString() Returns the map's center in a formatted string. If the delimitedStrings setting is false, it will return a string in JSON format; otherwise it will return a delimited string.
getDiv() Returns the DOM element the map was rendered in.
getOptions(option) Returns the value for the specified option. If you do not supply an option, it will return an object with all the map's options.
getProjection() Returns the map's current Projection.
getZoom() Returns the map's current zoom level.
labels(ids) Returns a LabelArray containing any labels with matching ids.
markers(ids) Returns a MarkerArray containing any markers with matching ids.
off(type) Removes all the map's event listeners for the specified type. You can also pass in all to remove all event listeners.
on(type, function) Adds the specified event listener to the map.
polygons(ids) Returns a PolygonArray containing any polygons with matching ids.
polylines(ids) Returns a PolylineArray containing any polylines with matching ids.
rectangles(ids) Returns a RectangleArray containing any rectangles with matching ids.
remove(type, ids) Removes the specified component(s) from the map. You can optionally supply id(s) to remove any matching component(s).
reset() Resets the map's bounds and options to its initial values.
setCenter(center) Sets the map's center.
setOptions(option, value) Sets the specified option to the supplied value. To set mulitple options, pass in a object as the only parameter.
setZoom(zoom) Sets the map's zoom level.
shape(type, options) Returns a LatLngArray for the specified shape.
trigger(type) Triggers the specified event type.

Events

Gmaps simplifies working with events by prodiving an API similar to jQuery. It also uses an internal lookup table to allow for more readable event names.

Copy
// add event
myMap.on("click", function() {
  console.log("You clicked my map!")
})

// trigger event
myMap.trigger("resize")

// remove all events by type
myMap.off("double click")

// remove all events
myMap.off("all")
Event Alias Description
bounds_changed bounds changed This event is fired when the viewport bounds have changed.
center_changed center changed This event is fired when the map center property changes.
click click This event is fired when the user clicks on the map.
dblclick double click This event is fired when the user double-clicks on the map. Note that the click event will also fire, right before this one.
drag drag This event is repeatedly fired while the user drags the map.
dragend drag end This event is fired when the user stops dragging the map.
dragstart drag start This event is fired when the user starts dragging the map.
heading_changed heading changed This event is fired when the map heading property changes.
idle idle This event is fired when the map becomes idle after panning or zooming.
maptypeid_changed mapTypeId changed This event is fired when the mapTypeId property changes.
mousemove mouse move This event is fired whenever the user's mouse moves over the map container.
mouseout mouse out This event is fired when the user's mouse exits the map container.
mouseover mouse over This event is fired when the user's mouse enters the map container.
projection_changed projection changed This event is fired when the projection has changed.
resize resize Developers should trigger this event on the map when the div changes size.
rightclick right click This event is fired when the DOM contextmenu event is fired on the map container.
tilesloaded tiles loaded This event is fired when the visible tiles have finished loading.
tilt_changed tilt changed This event is fired when the map tilt property changes.
zoom_changed zoom changed This event is fired when the map zoom property changes.

Settings

You can set the global defaults at gmap.settings.

Setting Default Description
circleOptions
Copy
{
  clickable: true,
  draggable: false,
  editable: false,
  fillColor: "#2196F3",
  fillOpacity: 0.75,
  strokeColor: "#000",
  strokeOpacity: 0.75,
  strokePosition: 0,
  strokeWeight: 1,
  visible: true
}
The default options for circle components. Refer to Google's documentation for a full list of the available options.
delimitedStrings false If true, the map will create/parse delimited strings. Otherwise strings will be in JSON format.
delimiter
Copy
{
  latLng: "|",
  latLngArray: "~",
  latLngBounds: "|"
}
The characters used to create/parse delimited strings.
labelOptions
Copy
{
  align: "center",
  fontColor: "#000",
  fontSize: 14,
  strokeColor: "#FFF",
  strokeWeight: 1,
  visible: true
}
The default options for label components.
mapId gmap The id of the DOM element the map will be rendered inside.
mapOptions
Copy
{
  center: {
    lat: 37.5,
    lng: -120
  },
  clickableIcons: false,
  disableDoubleClickZoom: false,
  gestureHandling: "auto",
  keyboardShortcuts: true,
  mapTypeControl: false,
  mapTypeId: "roadmap",
  scrollWheel: true,
  streetViewControl: false,
  zoom: 6,
  zoomControl: true
}
The default options for the map. Refer to Google's documentation for a full list of the available options.
markerOptions
Copy
{
  clickable: true,
  crossOnDrag: true,
  draggable: false,
  opacity: 1,
  optimized: true,
  visible: true
}
The default options for marker components. Refer to Google's documentation for a full list of the available options.
polygonOptions
Copy
{
  clickable: true,
  draggable: false,
  editable: false,
  fillColor: "#2196F3",
  fillOpacity: 0.75,
  geodesic: false,
  strokeColor: "#000",
  strokeOpacity: 0.75,
  strokeWeight: 1,
  visible: true
}
The default options for polygon components. Refer to Google's documentation for a full list of the available options.
polylineOptions
Copy
{
  clickable: true,
  draggable: false,
  editable: false,
  geodesic: false,
  strokeColor: "#000",
  strokeOpacity: 0.75,
  strokeWeight: 3,
  visible: true
}
The default options for polyline components. Refer to Google's documentation for a full list of the available options.
rectangleOptions
Copy
{
  clickable: true,
  draggable: false,
  editable: false,
  fillColor: "#2196F3",
  fillOpacity: 0.75,
  strokeColor: "#000",
  strokeOpacity: 0.75,
  strokePosition: 0,
  strokeWeight: 1,
  visible: true
}
The default options for rectangle components. Refer to Google's documentation for a full list of the available options.
urlPrecision 5 How many decimal places lat/lng values are rounded to.

Callbacks

Callback Context Description
onLoad(map) Map Is called after the map's tiles have finished loading for the first time.