Skip to content

Tutorials

Jump to bottom
Kohei Otsuka edited this page Aug 10, 2026 · 5 revisions

Tutorials

Two step-by-step guides: publishing an app you built with MaplatEditor, and embedding the Maplat viewer into a page of your own.

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

Which route is for you?

What you want Route
Publish the app you built in MaplatEditor, as it is Route A — recommended for real use
Put a Maplat map inside a page or site you already have Route B

These are not two alternatives — they are two stages. The viewer loads its app definition, map settings, tiles and thumbnails from files laid out next to the page, and those files are produced by MaplatEditor. So Route B still needs what Route A gives you. Read Route A first, even if your goal is Route B.

Route A — Publish an app built with MaplatEditor

A1. Export the app

Build the maps, the POI sources and the app in MaplatEditor, then use its Export function. The result is a single ZIP named after the app ID.

Everything up to that point — creating maps, tiling, ground control points, POIs, app settings, export — is covered by the MaplatEditor Wiki Tutorials. This page picks up after you have the ZIP.

A2. What is inside the package

Unzip it and you get a complete static site:

{appID}/
├ index.html          entry page; loads the viewer and starts it
├ favicon.ico
├ service-worker.js   only when Cache is enabled
├ apps/               the app definition
├ maps/               map and base map settings
├ tiles/              map tiles
├ tmbs/               thumbnails for the map selector UI
├ merc/               Mercator tile sets, if the app uses them
├ pois/               POI sources (GeoJSON)
├ imgs/               POI icons
├ img/                splash image
├ pwa/                manifest and icons, when PWA is enabled
└ assets/             the viewer itself, plus OpenLayers and the UI locales

Two things follow from this layout.

  • The package is self-contained. The viewer, OpenLayers and the interface translations all live in assets/, so the app does not depend on a CDN at runtime. The one exception is MapLibre GL JS / Mapbox GL JS, which are loaded from a CDN and only when the app actually contains a source of that kind.
  • Nothing in here is meant to be edited by hand. When the data changes, change it in MaplatEditor and export again. The exceptions are the two behaviour switches described in A4.

A3. Put it on a web server

Upload the whole unzipped folder and open index.html.

The viewer fetches its app definition and map settings over HTTP, so it cannot run from a local folder (file://). Put it on a web server — any static hosting will do.

A sub-directory is fine. Every path the viewer uses is relative to the page, so https://example.com/maps/morioka/ works exactly like a site root.

A4. Change behaviour without re-exporting

The generated index.html copies any query parameter into the option object before it starts the viewer. So you can change behaviour by URL alone:

Query Effect
?lang=en Force the English UI (otherwise detected from the browser)
?overlay=true Show the historical map as an overlay on the modern map
?appid=hoge Load apps/hoge.json instead of the exported app definition — useful only if you place more than one definition under apps/

Values true and false become booleans; everything else is passed through as a string. There is no fixed list of accepted keys — any property of the option object works this way. See API-Reference § MaplatAppOption Categories for what those properties are.

This is a property of the generated page, not of the library. @maplat/ui never reads the URL query by itself. If you build your own page (Route B), you get this behaviour only if you write those few lines yourself.

To bake in a default instead, edit the option object near the bottom of index.html:

var option = {
  "appid": "myApp",
  "lang": "en",
  "overlay": true
};

A5. Shareable URLs

When State URL is enabled in the app settings, the viewer keeps the current map, position, zoom and rotation in the URL after #!. The address bar always holds a link back to exactly what the visitor is looking at:

https://example.com/myApp/#!s:morioka/b:gsi/x:141.149989/y:39.699952/z:17

That URL can be bookmarked, shared, or reopened later. Enabling Share in the same settings adds the sharing UI that hands the visitor this link directly.

The individual keys are an internal encoding and may grow between releases — treat the URL as opaque rather than assembling one by hand.

Route B — Embed the viewer in your own page

B1. Load OpenLayers and Maplat UI from a CDN

For a page of your own without a build step, load OpenLayers first and Maplat UI after it. Maplat UI expects the global ol namespace to exist.

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

<!-- Replace <version> with the release listed in the README release block. -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@maplat/ui@<version>/dist/maplat_ui.css">
<!-- Replace <version> with the release listed in the README release block. -->
<script src="https://cdn.jsdelivr.net/npm/@maplat/ui@<version>/dist/maplat_ui.umd.js"></script>

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

<script>
  MaplatUi.createObject({ appid: "myApp" }).then(function (app) {
    console.log("Maplat initialized", app);
  });
</script>

createObject returns a Promise that resolves once the map data is loaded and the coordinate transform is ready.

B2. The data files the viewer expects

The snippet above will not show a map on its own. appid tells the viewer to fetch apps/myApp.json relative to your page, and that definition points at further files, again relative to the page:

your-page/
├ index.html      your own page, with the snippet above
├ apps/           apps/<appid>.json — the app definition
├ maps/           maps/<mapID>.json — one per map and base map
├ tiles/          tiles/<mapID>/{z}/{x}/{y}.<ext>
├ tmbs/           thumbnails for the map selector UI
└ pois/           POI sources referenced by the app definition

Take these folders from the package you exported in Route A and drop them next to your page. They are the same files, laid out the same way; Route A's index.html and assets/ are the parts you are replacing with your own page and your CDN tags.

Because these are fetched over HTTP, your page has the same constraint as Route A: it cannot run from file://. Use a local dev server while you are building it.

For what goes inside those files, see Concepts § Application Data Format and Concepts § POI in the current version. A working, current app definition lives in the repository at public/apps/sample.json.

B3. Bundler usage

For a project with a bundler, install the package and import it as an ES module. OpenLayers is a peer dependency and is installed separately.

pnpm add @maplat/ui ol
import { MaplatUi } from '@maplat/ui';
import '@maplat/ui/dist/maplat_ui.css';

MaplatUi.createObject({ appid: 'myApp' }).then(app => {
  // Application initialized
});

The data files from B2 still apply: place them where the built page can reach them (in most bundlers, the public or static directory).

B4. Options and signatures

This page deliberately does not list the option properties or the method signatures, so that there is only one place to keep them correct.

  • API-Reference — the lifecycle, the option categories, and framework integration patterns
  • docs/api/ — the authoritative signature list
  • MaplatCore Wiki Tutorials — the layer below the UI (@maplat/core): event handling, runtime POI layer management, lines and vectors

Common pitfalls

  • Nothing renders when opened from the file system. The viewer fetches JSON, which browsers refuse over file://. Serve the folder over HTTP instead.
  • Invalid Maplat option key: … Use "…" instead. App definitions written for old releases used snake_case names such as app_name or home_position. The current version rejects them instead of converting them. The mapping to the current camelCase names is in Concepts § Application Data Format.
  • A base map silently disappears. Mapbox and MapLibre base maps need their GL library, which is loaded from a CDN. If the CDN is unreachable, that one source is dropped with a warning and the rest of the app keeps working.

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

See Also

  • Home
  • Concepts — data formats and coordinate transform theory
  • API-Reference — API concepts and usage patterns
  • Gallery — published Maplat apps you can open and try
  • README — latest quick start

Maplat

Language / 言語

Pages / ページ

English

日本語

External / 外部

Clone this wiki locally