Our custom map plugin, “Ptolemy”, allows us to display interactive maps on our wiki pages. The content for these maps is generated from the wiki itself with the help of the excellent Struct plugin.
There are two components to Ptolemy's maps: the map itself and the map content.
Dokuwiki is made up of pages. When you access a page that has no content, you are given the chance to make that page. When it has no content, the page is deleted. When you make a page “under” another page, the “parent” page now also acts as a namespace.
For example, if we had “cities:restaurants”1), we would consider “cities” to be the namespace. We could go further by having “cities:restaurants:burrito_shop”, where both cities and restaurants act as namespaces.
Its important to know about namespaces, because the wiki's admins can assign different data schemas to them using Struct. In this way, one namespace can be for maps, another for locations, and so on.
The wiki's Struct plugin lets us add data to a page that can be used elsewhere. You'll see this in other places on the wiki with tables that auto-update whenever a page is created or updated. The map plugin uses Struct's data to define the map itself, as well as the markers that appear on it. You can find this data at the bottom of a page that has a Struct 'schema' associated with it, where it looks like part of the page's form.
If a map doesn't already exist, the first thing we have to do is define the map's attributes. We do this by creating a page on the wiki that has the right Struct fields. When you make a page in that namespace, you'll see fields at the bottom of the page that let you define:
Ptolemy can support multiple maps on the wiki, in addition to the basic one that covers the broader setting.
When you add or edit a page in a namespace that has the right Struct fields, it can act as a location on a map. Locations have a few important fields and some optional ones:
Once you have a map, you can display it! You don't need any locations to make a map visible - they'll appear as you add them.
~~MAP|(the page your map's struct is on)|(initial coordinates)|(initial zoom)~~
An example would be:
That would display the map defined on the “maps:my_map” page. The view would be centered at 100px by 100px, with an initial zoom of 0.
Dokuwiki aggressively caches its pages. This is usually a great thing, but when you add or edit a location elsewhere in the wiki, it doesn't trigger your map to update. You may need to edit a page where the map seems out-of-date to force the wiki to update your map.
Your markers may not be displaying for a few reasons.
Whisper created this article on 2022/09/22 13:27.
🚧 This article is a work-in-progress. Is it not currently approved.