Mapbox plugin for Craft CMS

Chaining

# What & Why

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

const map = mapbox.map(locations)
    .style(mapStyle)
    .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.

# 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...

const map = mapbox.map(locations, options);

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

const map = mapbox.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.

There are three (roughly equal) ways to add a map to the DOM...

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

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.

← Locations →