Chaining

# What & Why

Chaining refers to the ability to run multiple commands on a map sequentially...

var map = googleMaps.map(locations)
    .styles(styleSet)
    .center(coords)
    .zoom(level);

To ensure that our maps are as dynamic as possible, there are a series of methods which can be chained together, in any order you'd like.

Static & Dynamic

All the examples on this page demonstrate how Dynamic Map methods can be chained, but it's worth noting that Static Map methods can also be chained together.

# Starting a Chain

A chain must always begin with the creation of a map object. No matter how you intend to decorate your dynamic map, it will always start the same way...

var map = googleMaps.map(locations, options);

Or if you want to reference a map that has already been created, you can retrieve it like this...

var map = googleMaps.getMap(mapId);

Two flavors of "map object"

Internally, there are really two different things that are being referred to as the "map object".

The internal structure of this object varies greatly between JavaScript and Twig/PHP, but fortunately, you don't need to worry about the difference at all. The API has been designed to make usage nearly identical, regardless of language.

# Ending a Chain

Not all chains need to be concluded right away... you may sometimes find it helpful to keep a chain alive long enough to perform more operations on the map object. Eventually though, you'll probably want to end the chain.

To end the chain, apply the tag method to wrap it all up. Depending on which language you are working in, you'll notice properties unique to that context.

# Twig

In Twig, the tag method renders a finished map.

{# Renders a map #}
{{ map.tag() }}

# PHP

In PHP, the tag method creates a new Twig\Markup object.

// Creates a new Twig\Markup object
$twigMarkup = $map->tag();

# JavaScript

In JavaScript, the tag method creates a new HTML element, and optionally injects it into the DOM.

// Injects map into the DOM
map.tag({'parentId': 'my-map-container'});

// Initializes map in DOM element specified by map `id`
map.tag();

// Creates a new HTML element, detached from the DOM
var mapDiv = map.tag();

Multiple ways to set the DOM element

You may omit the parentId if a map id was already specified.

When the map is created, specify the DOM element id. It must match an existing, empty <div> element.