Map

Embeds a Google Maps instance for displaying GPS coordinates as pins. Accepts coordinates directly from the Address component's getCoordinates() API or any other source. The two components are intentionally independent — wiring them together is done in application-level JS.

API Key required. A Google Maps JavaScript API key must be provided via ->apiKey(). The demos below will show a placeholder until a valid key is configured. Get an API key →

Static Map with Marker

Pre-set centre and a marker via PHP fluent API. Renders immediately on page load.

Loading map…

<?= $m->map('venueMap')
    ->apiKey($_ENV['GOOGLE_MAPS_KEY'])
    ->center(-36.8485, 174.7633)
    ->zoom(13)
    ->marker(-36.8485, 174.7633, 'Auckland CBD')
    ->height('350px') ?>

// Map is auto-initialised. Access via:
var map = m.map('venueMap');

// Add a marker programmatically
map.addMarker(-36.8485, 174.7633, 'Auckland CBD');

// Move the centre
map.setCenter(-36.8485, 174.7633);

// Listen for map ready
document.getElementById('venueMap')
    .addEventListener('m:map:ready', function(e) {
        console.log('Map ready:', e.detail.map);
    });

Multiple Markers

Pass an array of markers to ->markers(). Each must have lat, lng, and optional title.

Loading map…

<?= $m->map('nzCitiesMap')
    ->apiKey($_ENV['GOOGLE_MAPS_KEY'])
    ->center(-41.2865, 174.7762)
    ->zoom(5)
    ->markers([
        ['lat' => -36.8485, 'lng' => 174.7633, 'title' => 'Auckland'],
        ['lat' => -41.2865, 'lng' => 174.7762, 'title' => 'Wellington'],
        ['lat' => -43.5321, 'lng' => 172.6362, 'title' => 'Christchurch'],
        ['lat' => -45.8788, 'lng' => 170.5028, 'title' => 'Dunedin'],
    ])
    ->height('350px') ?>

// Access and manage markers via JS
var map = m.map('nzCitiesMap');

// Add another marker later
map.addMarker(-37.6878, 176.1651, 'Tauranga');

// Fit all markers in view
map.fitMarkers();

// Remove all markers
map.clearMarkers();

// Get current markers array
var pins = map.getMarkers(); // [{lat, lng, title, marker}, ...]

Dynamic Marker Management

Use the JS API to add, clear, and re-centre the map at runtime.

Loading map…

Click a button to interact with the map...

<?= $m->map('myMap')
    ->apiKey($_ENV['GOOGLE_MAPS_KEY'])
    ->center(-41.2865, 174.7762)
    ->zoom(5)
    ->height('350px') ?>

document.addEventListener('DOMContentLoaded', function() {
    var map = m.map('myMap');

    document.getElementById('addBtn').addEventListener('click', function() {
        map.addMarker(-36.8485, 174.7633, 'Auckland');
        map.setCenter(-36.8485, 174.7633);
    });

    document.getElementById('clearBtn').addEventListener('click', function() {
        map.clearMarkers();
    });

    document.getElementById('fitBtn').addEventListener('click', function() {
        map.fitMarkers();
    });
});

Address Picker + Map Workflow

The Address component now exposes getCoordinates() — returns {lat, lng} if the selected address suggestion includes GPS data, or null otherwise. This example shows how to wire an address picker to a map in application JS.

// In your view:
<?= $m->address('deliveryAddress')
    ->suggestUrl('/manhattan/addressSuggest')
    ->mode('nz') ?>

<?= $m->map('deliveryMap')
    ->apiKey($_ENV['GOOGLE_MAPS_KEY'])
    ->height('350px') ?>

document.addEventListener('DOMContentLoaded', function() {
    var addr = m.address('deliveryAddress');
    var map  = m.map('deliveryMap');

    document.getElementById('deliveryAddress')
        .addEventListener('m:address:select', function(e) {
            var coords = addr.getCoordinates();
            if (coords) {
                map.clearMarkers();
                map.setCenter(coords.lat, coords.lng);
                map.setZoom(15);
                map.addMarker(coords.lat, coords.lng, e.detail.label);
            }
        });
});

Recenter Button

Enable ->recenterButton() to add a crosshairs button to the map. Clicking it resets the viewport back to the original centre coordinates and zoom level supplied at initialisation. Implemented as a native Leaflet control (bottom-left) — consistent with Leaflet's built-in zoom controls.

Loading map…

Pan or zoom the map, then click the button in the bottom-left to reset. The recenter() JS method does the same programmatically.

<?= $m->map('venueMap')
    ->provider('leaflet')
    ->center(-36.8485, 174.7633)
    ->zoom(13)
    ->marker(-36.8485, 174.7633, 'Auckland CBD')
    ->height('350px')
    ->recenterButton() ?>

// Programmatic recenter via the JS API
var map = m.map('venueMap');
map.recenter();   // snaps back to original centre + zoom

PHP PHP Methods (Fluent)

Method / Property	Parameters	Description
`$m->map($id)`	`string`	Create a map component.
`->provider($name)`	`string`	Map provider: `'leaflet'` (default, free) or `'google'`.
`->apiKey($key)`	`string`	Google Maps JavaScript API key. Required when provider = `'google'`.
`->center($lat, $lng)`	`float, float`	Default map centre coordinates. Defaults to Wellington, NZ if not set.
`->zoom($zoom)`	`int`	Initial zoom level (1–21). Default: `14`.
`->height($css)`	`string`	Container height as a CSS value. Default: `'400px'`.
`->marker($lat, $lng, $title)`	`float, float, string`	Add a single initial marker. `$title` optional; shown in info window on click.
`->markers($array)`	`array`	Set all initial markers at once. Each element: `['lat' => …, 'lng' => …, 'title' => …]`.
`->recenterButton()`	`bool`	Show a recenter button on the map. Click resets the view to the original centre and zoom. Default: `false`.

JS JS Methods

Method / Property	Parameters	Description
`m.map(id)`	`string`	Get the map API instance (auto-initialised on DOMContentLoaded).
`setCenter(lat, lng)`	`float, float`	Pan the map to the given coordinates.
`setZoom(zoom)`	`int`	Set the zoom level.
`recenter()`		Reset the map to the original centre coordinates and zoom level.
`addMarker(lat, lng, title)`	`float, float, ?string`	Add a pin at the given coordinates. Returns the native marker instance.
`clearMarkers()`		Remove all pins from the map.
`getMarkers()`		Returns an array of `{lat, lng, title, marker}` objects.
`fitMarkers()`		Adjust the map bounds to fit all current markers.

JS Address Component Extension

Method / Property	Parameters	Description
`m.address(id).getCoordinates()`		Returns `{lat, lng}` if the selected suggestion includes GPS coordinates, or `null`.

EVENT Events

Event Name	Detail	Description
`m:map:ready`	`{map}`	Fired once Google Maps has initialised. `detail.map` is the raw `google.maps.Map` instance.
`m:map:markeradded`	`{lat, lng, title}`	Fired after each `addMarker()` call.
`m:map:markerscleared`	`{}`	Fired after `clearMarkers()`.