Skip to content

Tutorials

Jump to bottom
Kohei Otsuka edited this page Jul 23, 2026 · 1 revision

Tutorials

Step-by-step guides for setting up and deploying a Maplat application.

Note (2026-07): This page is based on the Maplat 0.2.6 era (August 2018) documentation. The current version (0.12.2) has a significantly different application structure and distribution format (ESM / CDN / npm package @maplat/ui). For the latest quick start, see the README.

Table of Contents

1. Download the sample package

First, download the Maplat sample package from this link. It is a zip file, so extract it. Place the extracted contents on a web server and access index.html — the sample Maplat with two Morioka historical maps will run.

Due to modern browser file-access security settings, Maplat cannot run from a local folder directly. Place it on a web server.

Once the sample runs, proceed to the next step.

2. Inspect the sample package contents

The package has roughly the following structure:

├apps
│  └sample.json
├dist
│  └several js/css files
├fonts
│  └several font files
├img
│  └several image files
├index.html
├locales
│  └several i18n files/folders
├maps
│  └several map definition json files
├parts
│  └several UI part images
├tiles
│  └several map tile folders
└tmbs
   └several thumbnail files for map selector UI

Files/folders that do not need modification:

  • dist folder
  • fonts folder
  • index.html (unless you rename apps/sample.json)
  • locales folder
  • parts folder
  • tmbs/gsi_menu.jpg, tmbs/osm_menu.jpg

Files that must be edited:

  • apps/sample.json

Folders whose contents must be replaced:

  • img — images referenced by POI definitions in apps/sample.json
  • maps — compiled map definition JSON files generated by MaplatEditor
  • tiles — map tile folders generated by MaplatEditor
  • tmbs — thumbnail images for the map selector UI (manually create 52px-long-edge images named {mapID}_menu.jpg)

3. After creating maps with MaplatEditor

After editing a map in MaplatEditor, the workflow is:

  1. Delete the JSON files in the sample maps folder, then copy the desired compiled JSON files from MaplatEditor's output.
  2. Delete the tile folders in the sample tiles folder, then copy the desired tile folders from MaplatEditor's output.
  3. Delete the JPG files in tmbs (except gsi_menu.jpg and osm_menu.jpg), then place manually created thumbnails for each map ID.
  4. Rewrite apps/sample.json as described in the next section.
  5. Delete images in the img folder, then place any POI images referenced by apps/sample.json.

4. Configure apps/sample.json

The apps/sample.json file looks like this:

{
    "app_name" : {
        "ja" : "盛岡市古地図アプリ",
        "en" : "Historical Map Application of Morioka"
    },
    "lang" : "ja",
    "fake_gps" : true,
    "fake_center" : {
        "ja" : "盛岡市",
        "en" : "Morioka"
    },
    "fake_radius" : 10,
    "home_position" : [141.149989, 39.699952],
    "default_zoom" : 17,
    "sources" : [
        { "mapID" : "morioka_ndl" },
        { "mapID" : "morioka" },
        "gsi",
        "osm"
    ],
    "pois" : [
        {
            "name" : { "ja" : "盛岡城", "en" : "Morioka Castle" },
            "address" : "岩手県盛岡市内丸1-37",
            "lat" : 39.69994722,
            "lng" : 141.1501111,
            "desc" : "南部（盛岡）藩南部氏の居城...",
            "image" : "moriokajo.jpg"
        }
    ]
}

Key fields to change:

  • app_name — application title
  • home_position — center coordinates [longitude, latitude] at start
  • sources — list of map IDs. Keep "gsi" and "osm" (shortcut strings). Other maps use { "mapID": "..." } form.
  • pois — POI definitions. If no POIs, keep "pois": []. If a POI has an "image", place that image in the img folder.

Note: The field names above (app_name, fake_gps, home_position) are the 0.2.6-era snake_case form. The current version uses camelCase (appName, fakeGps, homePosition). See Concepts for the current data format and the README for the latest API.

See App-data-format (archived in Concepts) for the full schema.

5. Controlling app behavior via query string

With the app running at http://localhost/, you can control behavior via query strings:

Query Effect
?appid=hoge Load hoge.json instead of sample.json
?lang=en Force English UI (normally auto-detected from browser settings)
?overlay=true Show historical map as an overlay on the standard map

You can also bake these defaults into index.html by setting the option object:

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

6. Other configuration samples

The app configuration supports many more features, including:

  • TMS/WMTS historical maps as base or overlay sources
  • Displaying external websites (e.g. Wikipedia) as POI content

Sample configuration files for reference:

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

See Also

Maplat

Language / 言語

Pages / ページ

English

日本語

External / 外部

Clone this wiki locally