OpenStreetMap

Pair framework: OpenStreetMap

Pair\Helpers\OpenStreetMap is the browser-side entrypoint for lightweight OpenStreetMap rendering in Pair views.

Use it when you want Pair to:

• load /assets/pair.css
• load /assets/PairOpenStreetMap.js
• render a dependency-free marker map from server-provided latitude and longitude points
• avoid a browser API key when you only need map tiles and markers
• keep OpenStreetMap markup and asset loading consistent across views

This helper does not perform geocoding or address autocomplete. Store or calculate coordinates separately, then pass them to the browser-side map payload.

Main method

load(string $assetsPath = '/assets'): void

Registers Pair's bundled OpenStreetMap stylesheet and JavaScript asset.

Parameters:

• $assetsPath points to the public directory that contains pair.css and PairOpenStreetMap.js

Important runtime behavior:

• Pair registers pair.css because the map canvas, tile layer, marker layer, status panel, and attribution panel rely on bundled styles
• Pair registers PairOpenStreetMap.js with defer
• if $assetsPath is passed as assets, /assets, or another slash-variant, Pair normalizes it
• no Google key or remote loader is required
• by default, tiles are loaded from https://tile.openstreetmap.org/{z}/{x}/{y}.png

Minimal example

use Pair\Helpers\OpenStreetMap;

OpenStreetMap::load();

$points = [
    [
        'marker' => 1,
        'title' => 'Main office',
        'location' => 'Milan',
        'latitude' => 45.4642,
        'longitude' => 9.1900,
        'url' => '/offices/1',
    ],
];

<?php
$pointsPayload = json_encode(
    ['points' => $points],
    JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_AMP | JSON_HEX_QUOT
);
?>
<div class="pair-osm-map" data-pair-osm-map>
    <div class="pair-osm-map__canvas" data-pair-osm-canvas>
        <div class="pair-osm-map__tiles" data-pair-osm-tiles></div>
        <div class="pair-osm-map__markers" data-pair-osm-markers></div>
        <div class="pair-osm-map__status" data-pair-osm-status hidden></div>
        <div class="pair-osm-map__attribution">
            &copy; <a href="https://www.openstreetmap.org/copyright" rel="noopener" target="_blank">OpenStreetMap</a> contributors
        </div>
    </div>
    <script type="application/json" data-pair-osm-points><?= $pointsPayload ?></script>
</div>

Point payload

PairOpenStreetMap.js reads a JSON script inside the map root:

{
  "points": [
    {
      "marker": 1,
      "title": "Main office",
      "location": "Milan",
      "latitude": 45.4642,
      "longitude": 9.19,
      "url": "/offices/1"
    }
  ]
}

Supported point fields:

• latitude and longitude are required and must be valid numeric coordinates
• marker is the visible marker label
• title and location are combined for marker accessibility labels and browser tooltips
• url or detailUrl controls the marker link; unsafe protocols are ignored
• category and status are normalized for project code that wants to extend marker styling later

Invalid points are discarded before rendering. If no valid points remain, the map shows the empty message from data-pair-osm-empty-message, or No points to show. by default.

Map options

Options can be passed as data-* attributes on the map root:

<div
    class="pair-osm-map"
    data-pair-osm-map
    data-pair-osm-min-zoom="11"
    data-pair-osm-max-zoom="17"
    data-pair-osm-single-point-zoom="15"
    data-pair-osm-padding="64"
    data-pair-osm-tile-url-template="https://tile.openstreetmap.org/{z}/{x}/{y}.png">
</div>

The same values can be provided when initializing a map manually:

window.PairOpenStreetMap.initMap(mapElement, {
    points,
    minZoom: 11,
    maxZoom: 17,
    singlePointZoom: 15,
    padding: 64,
    tileUrlTemplate: "https://tile.openstreetmap.org/{z}/{x}/{y}.png",
});

Zoom values are clamped to Pair's supported tile range, and marker links are normalized before they are assigned to anchors.

Browser API

PairOpenStreetMap.js exposes window.PairOpenStreetMap.

Public methods:

• initAll(root = document) scans a document or fragment for [data-pair-osm-map]
• initMap(root, options = {}) initializes one map root
• scheduleRenderAll() schedules a resize redraw
• renderAll() redraws all initialized maps immediately

Use initAll(fragment) after injecting map markup through AJAX or a modal body.

Asset deployment

The framework asset copy script copies PairOpenStreetMap.js because it recursively copies every bundled file under assets/.

For a normal deployment, copy all assets:

php vendor/viames/pair/scripts/copy-assets.php public/assets

If you use the js filter, remember that only JavaScript files are copied. Copy all assets, or copy CSS separately, when the map needs pair.css.

Notes

• Keep the OpenStreetMap attribution visible when using OpenStreetMap tiles.
• For production traffic beyond light usage, consider a project-owned tile provider and pass its URL through data-pair-osm-tile-url-template or tileUrlTemplate.
• OpenStreetMap::load() is additive: it does not change GoogleAddress, GoogleMaps, GoogleGeocoder, or GooglePlacesService.

See also: Integrations, GoogleMaps, GoogleAddress.