Project Multiverse

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 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 [[https://www.dokuwiki.org/plugin:struct|Struct]] plugin.

There are two components to Ptolemy's maps: the map itself and the map content.

===== Quick Note on Terms =====

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"((this is the bit of the url after 'doku.php?id=', the same as you'd use when making an internal wiki link)), 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.

===== Defining a Map =====

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 - in our case, we use [[maps:|maps:]]. 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.

===== Defining Locations =====

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.

===== Map Syntax =====

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.

<code>
~~MAP|(the page your map's struct is on)|(initial coordinates)|(initial zoom)~~
</code>

An example would be:

<code>
~~MAP|maps:my_map|100,100|0~~
</code>

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.

===== Problem Solving =====

==== Map not Updating ====
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.

==== Markers not Displaying ====
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.

===== OOC =====

  * [[user:whisper]] created this on 2022/09/22 13:08.