Dynamic Map Model

The Dynamic Map Model is critical for generating a Dynamic Map. Thanks to the magic of chaining, it allows you to build maps that are as complex as they need to be.

Public Properties

id

string - The map's unique ID. Can be set manually or generated automatically.

Public Methods

__construct($locations = [], $options = [])

This method will be called when a new DynamicMap is initialized. It creates a starting point which sets the map-building chain in motion. You will be able to build upon the map by adding markers, etc.

• Twig
• PHP

{% set map = mapbox.map(locations) %}

The "map" variable

For each of the remaining examples on this page, the map variable will be an instance of a Dynamic Map Model. In each example, you will see how map methods can be chained at will.

It will be assumed that the map object has already been initialized, as demonstrated above.

Once you have the map object in hand, you can then chain other methods to further customize the map. There is no limit as to how many methods you can chain, nor what order they should be in.

Arguments

• $locations (mixed) - See a description of acceptable locations...
• $options (array) - Optional parameters to configure the map. (see below)

Dynamic Map Options

Option	Type	Default	Description
id	string	"map-{random}"	Set the id attribute of the map container.
width	int	null	Set the width of the map (in px).
height	int	null	Set the height of the map (in px).
zoom	int	via fitBounds	Set the default zoom level of the map. (1-22)
center	coords	via fitBounds	Set the center position of the map.
style	string|object	null	A string or object declaring the map style.
mapOptions	object	null	Accepts any Map options (opens new window).
markerOptions	object	null	Accepts any Marker options (opens new window)
popupOptions	object	null	Accepts any Popup options (opens new window)
popupTemplate	string	null	Template path to use for creating popups.
field	string|array	null	Address field(s) to be included on the map. (includes all by default)

Returns

• self - A chainable self-reference to this DynamicMap object.

Locations are Skippable

If you skip the locations parameter, a blank map will be created.

---

markers($locations, $options = [])

Append markers to an existing map object.

Arguments

• $locations (mixed) - See a description of acceptable locations...
• $options (array) - Optional parameters to configure the markers. (see below)

Option	Type	Default	Description
id	string	"marker-{random}"	Reference point for each marker.
markerOptions	object	null	Accepts any Marker options (opens new window)
popupOptions	object	null	Accepts any Popup options (opens new window)
popupTemplate	string	null	Template path to use for creating popups.
field	string|array	null	Address field(s) to be included on the map. (includes all by default)

Returns

• self - A chainable self-reference to this DynamicMap object.

• Twig
• PHP

{% do map.markers(locations) %}

---

style($mapStyle)

Style a map based on a given collection of styles.

Generating Styles

For more information on how to generate a set of styles, read Styling a Map.

Arguments

• $mapStyle (string|array) - A string specifying which style to use, or a JSON object declaring the map style. Defaults to streets-v12.

Returns

• self - A chainable self-reference to this DynamicMap object.

• Twig
• PHP

{% do map.style(mapStyle) %}

---

zoom($level)

Change the map's zoom level.

Arguments

• $level (string) - The new zoom level. Must be an integer between 1 - 22.

Returns

• self - A chainable self-reference to this DynamicMap object.

• Twig
• PHP

{% do map.zoom(level) %}

---

center($coords)

Re-center the map.

Arguments

• $coords (coords) - A simple key-value set of coordinates.

Returns

• self - A chainable self-reference to this DynamicMap object.

• Twig
• PHP

{% do map.center(coords) %}

---

fit($options)

Pan and zoom map to automatically fit all markers within the viewing area. Uses fitBounds (opens new window) internally.

Arguments

• $options (array) - Options as defined by the fitBounds documentation (opens new window).

Returns

• self - A chainable self-reference to this DynamicMap object.

• Twig
• PHP

{% do map.fit(options) %}

---

panToMarker($markerId)

Re-center map on the specified marker.

Arguments

• $markerId (string) - ID of the target marker.

Returns

• self - A chainable self-reference to this DynamicMap object.

• Twig
• PHP

{% do map.panToMarker(markerId) %}

---

changeMarker($markerId, $options)

Changes the configuration of an existing marker. Rebuilds and replaces the existing marker object.

Arguments

• $markerId (string|array|'*') - A marker ID, array of marker IDs, or '*' for all markers.
• $options (array) - Array of any Marker options (opens new window).

Returns

• self - A chainable self-reference to this DynamicMap object.

• Twig
• PHP

{% do map.changeMarker(markerId, options) %}

---

hideMarker($markerId)

Hide a marker.

Arguments

• $markerId (string|array|'*') - A marker ID, array of marker IDs, or '*' for all markers.

Returns

• self - A chainable self-reference to this DynamicMap object.

• Twig
• PHP

{% do map.hideMarker(markerId) %}

---

showMarker($markerId)

Show a marker.

Arguments

• $markerId (string|array|'*') - A marker ID, array of marker IDs, or '*' for all markers.

Returns

• self - A chainable self-reference to this DynamicMap object.

• Twig
• PHP

{% do map.showMarker(markerId) %}

---

openPopup($markerId)

Open the popup of a specific marker.

Arguments

• $markerId (string|array|'*') - A marker ID, array of marker IDs, or '*' for all popups.

Returns

• self - A chainable self-reference to this DynamicMap object.

• Twig
• PHP

{% do map.openPopup(markerId) %}

---

closePopup($markerId)

Close the popup of a specific marker.

Arguments

• $markerId (string|array|'*') - A marker ID, array of marker IDs, or '*' for all popups.

Returns

• self - A chainable self-reference to this DynamicMap object.

• Twig
• PHP

{% do map.closePopup(markerId) %}

---

tag($options = [])

Renders the necessary <div> container to hold the map. The final <div> will contain specific attributes and data, which are then used to generate the map. Each container must be initialized in order for its dynamic map to be created.

Arguments

• $options (array) - Configuration options for the rendered <div>.

Option	Type	Default	Description
init	bool	true	Whether to automatically initialize the map via JavaScript.
assets	bool	true	Whether to preload the necessary JavaScript assets.
callback	string	null	JavaScript function to run after the map has loaded.

By setting the init option to false, the map will not be automatically initialized in JavaScript. It must therefore be manually initialized in JavaScript when the page has completely rendered.

Returns

• Markup - A Twig Markup instance, ready to be rendered in Twig with curly braces.

• Twig
• PHP

{{ map.tag() }}

If you need to disable the automatic map initialization:

• Twig
• PHP

{{ map.tag({'init': false}) }}

---

getDna()

Get the complete map DNA, which is used to hydrate a map's container in the DOM.

Aliased as dna property via magic method.

Returns

• array - An array of data containing the complete map details.

• Twig
• PHP

{% set dna = map.dna %}
{% set dna = map.getDna() %}