Getting Started with Maps

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”¹⁾, 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:

• Map Name
  • The map's name.
• Namespace
  • What namespace/s the map will pull locations from. These namespaces need to have the right Struct assigned to define locations.
• Min and Max Zoom
  • What your minimum and maximum zoom should be. The “minimum” zoom is a negative number, because you're “pulling away” from the map. These values should change depending on your map's size.
• Initial Zoom
  • A number between the two numbers above.
• Map Media
  • Your map's image. Markers, etc, will be placed on this image.

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:

• Display Name
  • The name to show if you're using labels on the map. Also shows up in the tooltip users see when clicking the marker.
• Map Coordinates
  • The coordinates for the bottom-left of your marker. You can easily get these by using the 'marker' button on an existing map and clicking where you want to place the marker - it will copy the coordinates to your clipboard.
• RP Importance
  • The higher the importance, the more you'll see this marker. Lower importance markers become more visible as you zoom in.
• Marker Image
  • The image to use for this location's marker. Please keep in mind that there are no restrictions on marker size. For flags and other markers, we recommend no larger than 50px x 50px. Even that size may be too large, so see what works for your particular map.
• Short Description
  • If someone clicks on your marker, this is what is displayed. If you leave this blank, the tooltip will not display.

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:

~~MAP|maps:my_map|100,100|0~~

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.

• Struct schemas aren't using the correct names. Check the plugin's README, which stays up-to-date with the correct schema names.
• Typos or undefined namespaces in the map's struct data. The plugin has to have valid data to pull from.
• Your marker might be too large, transparent, or otherwise hard to see on the map.

Whisper created this article on 2022/09/22 13:27.

🚧 This article is a work-in-progress. Is it not currently approved.