Overview

Components can be added to maps to help visualize data and provide an interactive user-interface.

Integrated id system

Gmaps implements an id system to make managing multiple components a breeze. When a component is added to a map, it is assigned an id and stored within its respective component array. These component arrays are located within the components property of the map.

Copy
var myMap = new gmap()

myMap: {
  components: {
    Circle: { ... },    // CircleArray
    Label: { ... },     // LabelArray
    Marker: { ... },    // MarkerArray
    Polygon: { ... },   // PolygonArray
    Polyline: { ... },  // PolylineArray
    Rectangle: { ... }  // RectangleArray
  },
  ...
}

This structure allows you to easily interact with several components at once as well as search for a specifc component by its id.

Searching

Gmaps prevents you from having to directly interact with the component arrays by providing an intuitive searching API. The search methods will return a component array containing any components with matching ids.

Copy
// get all markers
myMap.markers()

// search for specific polygon
myMap.polygons("myPolygon")

// search for multiple labels
myMap.labels(["myLabel", 43])

Calling methods

Most of the time you will be using the map's search and calling methods on the returned component arrays. The called method will then be executed on every component within the array.

Copy
// hide all markers
myMap.markers().hide()

// show specific polygon
myMap.polygons("myPolygon").show()

// toggle multiple labels
myMap.labels(["myLabel", 43]).toggle()

Chaining methods

Most methods in gmaps can be changed together allowing for shorter, more readable code.

Copy
// add and immediately zoom to marker
myMap.add("marker", {
  id: "myMarker",
  position: {
    lat: 51.178835,
    lng: -1.826240
  }
}).zoom()

The others method allows you to easily call methods for two groups of components.

Copy
// show specific marker and hide all others
myMap.markers("myMarker").show().others().hide()

Base component

The base class that every component is extended from.

Property Type Description
id string All ids are converted into strings upon creation. When searching by id, gmaps will treat 43 and "43" as the same. Component ids must be unique within their respective component array.
map Map A reference to the map the component belongs too.
obj object A reference to the native Google Maps object.

Base component methods

Method Description
getBounds() Returns the LatLngBounds of the component.
getCenter() Returns the LatLng for the center of the component.
getCenterString() Returns the component'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.
getOptions(option) Returns the value for the specified option. If you do not supply an option, it will return an object with all the component's options.
hide() Sets the component's visibility to false.
others() Returns a new component array containing all the components except this one.
reset() Resets the components's coordinates and options to its initial values.
setOptions(options, value) Sets the specified option to the supplied value. To set mulitple options, pass in a object as the only parameter.
show() Sets the component's visibility to true.
toggle(condition) Toggles the component's visibility. You can supply a Boolean value to determine the component's visibilty.
zoom() Calculates the component's bounds and automatically sets the map's viewport to it.

Base component array

The base class that every component array is extended from.

Property Type Description
data array An array where all the components are stored. Whenever a component is added to a map, it will be added to the end of this array.
map Map A reference to the map the component array belongs too.
seed number The number used for auto-generating component ids. These ids will include a double underscore prefix and suffix to avoid name collision.

Base component array methods

Method Description
copy() Returns a copy of the component array.
filter(function) Returns an array with all the components that pass the test provided by the function.
find(function) Returns the first component in the array that satisfies the test provided by the function.
findById(id) Returns the component in the array that matches the provided id.
forEach(function) Executes the provided function once for each component in the array.
getBounds() Returns the LatLngBounds containing all the components inside the array.
getCenter() Returns the LatLng for the center of the component array's bounds.
getCenterString() Returns the component array'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.
getGoogleObjects() Returns an array containing all of the native Google Maps objects.
getIds() Returns an array containing all of the component ids.
getOptions(option) Returns the value for the specified option. If you do not supply an option, it will return an object with all the component's options. If there are multiple components inside the array, the return value will be an object using the component's ids as the key.
hide() Sets all the components' visibility to false.
includes(id) Returns a boolean indicating whether the array contains a component with the specified id.
others() Returns a new component array containing all the components that are not included inside the array.
pop(count) Removes the last component in the array from the map and returns it inside a new component array. You can pass in a number indicating how many components you want to remove. Defaults to 1.
reset() Resets all the components' coordinates and options to their initial values.
shift(count) Removes the first component in the array from the map and returns it inside a new component array. You can pass in a number indicating how many components you want to remove. Defaults to 1.
setOptions(options, value) Sets the specified option to the supplied value. To set mulitple options, pass in a object as the only parameter. This will get executed on every component inside the array.
show() Sets all the components' visibility to true.
toggle(condition) Toggles all the components' visibility. You can supply a Boolean value to determine the components' visibilty.
zoom() Calculates the component array's bounds and automatically sets the map's viewport to it.