Tutorials

Tutorials

Step-by-step guides for using MaplatCore in a browser and via a bundler.

Note: For the latest quick start (install commands, CDN URLs, version numbers), see the README. This page covers release-independent tutorial material.

Table of Contents

• 1. Browser usage (ES Modules + CDN)
• 2. Bundler usage (Vite / TypeScript)
• 3. Event handling
• 4. POI layer management
• 5. Lines and vectors
• See Also

---

1. Browser usage (ES Modules + CDN)

For usage directly in the browser without a bundler, you must load OpenLayers before loading MaplatCore. MaplatCore expects the global ol namespace to exist when loaded as a UMD script.

<!-- OpenLayers CSS (required) -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ol@10/ol.css">
<!-- OpenLayers JS (required) -->
<script src="https://cdn.jsdelivr.net/npm/ol@10/dist/ol.js"></script>

<div id="map_div" style="width: 100%; height: 100vh;"></div>

<!-- MaplatCore -->
<script src="https://cdn.jsdelivr.net/npm/@maplat/core@0.13.2/dist/maplat_core.umd.js"></script>

<script>
  var option = {
    startFrom: 'gsi',     // Initial map ID
    div: 'map_div'        // Target div ID (optional, default 'map_div')
  };

  MaplatApp.createObject(option).then(function (app) {
    console.log('Maplat initialized', app);
  });
</script>

Optional: MapLibre GL JS / Mapbox GL JS

If you use vector tiles, load MapLibre GL JS or Mapbox GL JS as well and inject the global into the option:

var option = {
  maplibregl: maplibregl,
  // mapboxgl: mapboxgl,
  // mapboxToken: 'YOUR_ACCESS_TOKEN',
  startFrom: 'gsi',
};

Make sure to use the latest compatible versions.

2. Bundler usage (Vite / TypeScript)

import { MaplatApp } from '@maplat/core';
import 'ol/ol.css'; // REQUIRED: OpenLayers CSS

const option = {
  startFrom: 'gsi',
};

MaplatApp.createObject(option).then((app) => {
  console.log('Maplat initialized', app);
});

Peer dependency: ol (OpenLayers) v9 or v10 must be installed separately.

pnpm add @maplat/core ol

3. Event handling

Use app.addEventListener(type, callback) to react to user interaction.

MaplatApp.createObject(option).then(function (app) {
  app.addEventListener('clickMarker', function (evt) {
    console.log('Marker clicked:', evt.detail);
    app.selectMarker(evt.detail.namespaceID);
  });

  app.addEventListener('clickMap', function (evt) {
    console.log('Map clicked:', evt);
  });
});

Events:

• clickMarker — fired when a marker is clicked. evt.detail holds marker data.
• clickMap — fired when the map background is clicked.
• gps_result — fired when a GPS position update happens.
• gps_error — fired when GPS fails.

4. POI layer management

Maplat manages markers in "layers". The default layer is 'main'. You can create additional layers and toggle their visibility.

MaplatApp.createObject(option).then(function (app) {
  // Add a custom layer
  app.addPoiLayer('main2', {
    icon: 'parts/blue_marker.png',
    selected_icon: 'parts/red_marker.png',
  });

  // Add a marker to the custom layer
  app.addMarker(
    {
      lng: 141.151995,
      lat: 39.701599,
      name: 'Sakurayama Shrine',
      desc: 'A historical shrine in Morioka.',
    },
    'main2',
  );

  // Toggle visibility
  app.showPoiLayer('main2');
  app.hidePoiLayer('main2');

  // List available layer IDs
  console.log(app.listPoiLayers());
});

5. Lines and vectors

Lines and vectors are GeoJSON-compatible feature collections rendered on the map.

app.addLine({
  lnglats: [
    [141.151995, 39.701599],
    [141.151137, 39.703736],
    [141.1521671, 39.7090232],
  ],
  stroke: { color: '#ffcc33', width: 2 },
});

app.addVector({ /* GeoJSON polygon */ });

To reset / clear:

app.resetLine();
app.clearLine();
app.resetVector();
app.clearVector();

---

日本語版はこちら / Read this page in Japanese

See Also

• Home
• Concepts — data format and coordinate transform theory
• API-Reference — API concepts and usage patterns
• README — latest quick start
• docs/api/ — authoritative API signatures