DataMaps/Using source editor

This page instructs on creating interactive maps using the source editor.

[no it doesn't, this is still largely a draft heh]

Basics

Source code pages

The Map: namespace (unless configured otherwise) is the only area of a wiki that maps may be created in. These maps should later be embedded in actual articles.

Optionally, documentation can be provided to each map as a /doc sub-page. Its contents will be displayed right at the top of the source page. This may be useful to provide help resources to editors, or to document your setups in a more human-friendly form.

Format

Each map page is a document following the relatively uncomplicated JavaScript Object Notation (JSON) and the extension's strict data structure rules (the format or schema).

In short, JSON recognises three main forms: [awkward, needs to be rewritten]

Values

These are numbers, boolean values (true and false), strings (text), or arrays and objects themselves.

Text in a string is always started with a single double quote character " and ended with another one. It also may only be placed on a single line.

To type a double quote without ending the string, a backslash may be put before it: "This is my favourite quote: \"Which is still a part of the same string\"".

To type a new line in a string, use \n.

Arrays (lists)

Ordered lists of values.

An array begins with a square right-facing bracket [, followed by the values delimited with single comma characters ,, and ends with a left-facing square bracket ]. Trailing commas (found immediately before the end symbol) are disallowed.

Objects (also known as records, structs, associative arrays or dictionaries in various programming languages)

Collections of properties: key (name)/value pairs.

An object begins with a curly right-facing bracket {, followed by the the name/value pairs delimited with single comma characters ,, and ends with a left-facing curly bracket }. Trailing commas (found immediately before the end symbol) are disallowed.

Each pair consists of a name (which is always a string) and a value. These two are separated with a single colon character :.

For example, the following object has two properties: Hello with a value of string "world!", this is with a value of "JSON".

{ "Hello": "world!", "this is": "JSON" }

A map is always an object with a specific set of properties, most of which are described further in this guide.

Format versioning

The format, that the DataMaps extension expects a map to follow, is itself defined as a JSON document following the rules set in the JSON Schema specification - but really, you don't need to know or care what "JSON Schema" is. All that matters is that DataMaps comes with such documents for every supported version, and which ruleset your map follows must be specified in a special $schema property:

{
  "$schema": "https://<span style="color: #b6a">yourwiki's domain.wiki.gg</span>/extensions/DataMaps/schemas/<span style="color: #b6a">format version</span>.json"
}

... for example:

{
 "$schema": "https://temtem.wiki.gg/extensions/DataMaps/schemas/v16.json"
}

This guide refers to the latest format version v16.

Because DataMaps is still considered beta software, this data format may change. In that scenario the format version will be increased, all of the changes will be documented, and a bot will update all maps on the platform to the newest format.

Coordinate system

[no clue what to write here, it's very likely the box setup itself will be deprecated] First of all, things are positioned with coordinates. Maps are two-dimensional canvases: there is a horizontal X axis and a vertical Y axis. These are, however, by default called longitude and latitude respectively in the map's viewing interface.

[crs object, topLeft and bottomRight - these determine the (0, 0) point/directionality, (kinda redundantly) the coordinate scale (only needs to be adjusted in rare cases, like ARK's future world-space coordinates project)]

Order of the coordinates in the user interface and in the array box notation (used by backgrounds below) is determined by crs's order property:

latlon (default)

Uses latitude and longitude naming. Points composing boxes will be written in order of [Y coordinate, X coordinate].

xy

Uses X and Y naming, in that order. Points composing boxes will be written in order of [X coordinate, Y coordinate].

yx

Uses Y and X naming, in that order. Points composing boxes will be written in order of [Y coordinate, X coordinate].

Rotation

The system can be rotated, and all backgrounds and markers will follow, through crs's rotation property (which takes a value in degrees - for example 45 to rotate everything 45 degrees clock-wise). This feature is, however, still experimental and there may be issues.

Backdrop

Single background image

To use one uploaded image as a background, you may set the background property to your image's file name. This will display the image with default settings filling the coordinate system. For example:

{
  ...,
  "background": "Throne World map.jpg"
}

To have higher control over the background's positioning or settings (described in a section beneath), the complete notation may be used. This notation involves a JSON object with a mandatory image property. For example, to place the image from the previous example at Y=50, X=50 spanning to Y=75, X=80.

{
  ...,
  "background": {
    "image": "Throne World map.jpg",
    "at": [
      [ 50, 50 ],
      [ 75, 80 ]
    ]
  }
}

Multiple backgrounds

[awkward, needs to be rewritten] To have multiple backgrounds a reader could switch through, use the backgrounds property. It is an array of background configuration objects, essentially identical to the complete notation of the background property. However, each of the objects must have a non-empty name property (string), which is shown in the backgrounds selection dropdown.

{
 ...,
 "backgrounds": [
   {
     "name": "Render",
     "image": "Scorched Earth map render.jpg"
   },
   {
     "name": "Drawn (in-game texture)",
     "image": "Scorched Earth map drawing.jpg"
   }
 ]
}

Tiled backgrounds

[.background.tiles, .backgrounds.#n.tiles for multiple uploaded images, divides the viewport into a grid of a given .tileSize starting in .at, distributes images in a grid coordinate system]

At the moment images must be cut manually into tiles. Automated generation is not supported, but will be investigated in the second half of 2024.

Background settings

at

rectangle (array) - The bounds the image should occupy on the map. This defaults to the entire bounds of the configured coordinate system.

pixelated

boolean - If set to true, browsers will be told to render the image in such a way that preserves pixelation. This should be set on pixel-art backgrounds.

associatedLayer

string (alphanumeric characters only) - Check the Tying markers to a background section. This defaults to the background object's position in the backgrounds array following declaration order, or 0 if only one background is being used.

overlays

array - See the Overlays section.

Image format recommendations

The JPEG format is preferred over PNGs when the image's pixelation does not matter and the image has no transparent features or the transparency is not crucial. JPEGs tend to be significantly smaller than PNGs.

Furthermore, the image's size should be kept under four megabytes. This may change in future if automated tiling with levels of detail is added.

Solid color fallback

Images alone cannot span the entire canvas. The viewer may pan or zoom out enough to make the edges visible. To make that less noticeable, a matching background color can be set as fallback with the backdropColor property on the map's settings object.

Only RGB input in hex form is accepted. [editor's note: needs checking, but v0.16 is probably buggy]

{
  ...,
  "settings": {
    "backdropColor": "#0b120d"
  },
  "background": "Throne World map.jpg"
}

Overlays

[low priority section. rectangles, images, polylines.]

Marker layers

[this loses coherency] DataMaps has a concept of "layers": collections of markers that may define various common traits, or may simply allow the user to hide or show these collections. There are two types of layers: groups and categories.

Each layer has an identifier (ID) that identifies it in the source code. This identifier is chosen by editors, and may only consist of alphanumeric characters, dashes, and underscores.

Groups

Primary collections of markers: they determine what size and shape their markers are presented with, and what those markers are collectively known by. Groups are also listed in the map's legend, where they may choose to hide or show entire groups of markers. Every marker must belong to exactly one group.

All marker groups are configured in the groups property of a map. That property is an object, where in each pair the key is the group's identifier (as described above).

Group settings

Group objects have the following properties:

name (required)

string - The name of the group, which will be shown to the viewer.

description

string - TODO

icon

file name - TODO

article

string - TODO

isDefault

boolean - If true (default), markers within the group are immediately shown (without manual toggling) to the reader when the map is loaded.

isCollectible

true, "individual", "group" or "globalGroup" - TODO

wantsChecklistNumbering

boolean - TODO

canSearchFor

boolean - TODO

Presentation styles

A group must also configure exactly one of the following presentation types:

Icons

Icon markers are simply shown as icons on the map.

Properties:

icon (required)

file name - sets the image that markers will be displayed as.

size

2D dimensions (in the form of [ X, Y ], both greater than zero) - determines the size of each marker in the group. Default is [32, 32] (width first, then height).

Pins

Pin markers are shown as coloured pins on the map.

Properties:

pinColor (required)

RGB color (three/six digit long hex string) - sets the colour each pin will have.

size

number (greater than zero) - sets the width each marker in the group will have. Default is 32.

Circles/Points

Circular markers are shown as circles on the map.

Properties:

fillColor (required)

RGB color (three/six digit long hex string) - sets the circles' inner colour.

size

number (greater than zero) - sets the size of each marker in the group. Default is 5.

Due to a bug, circles use different units from the other two types. This will be fixed in a future release.

strokeColor

RGB color (three/six digit long hex string) - sets the circles' outer border colour. This defaults to a colour slightly darker than the specified fill.

strokeWidth

number (greater or equal to zero) - sets the circles' outer border width. Default is 1.

{
 ...,
 "groups": {
   "executioner": {
     "name": "Weekly Lucent Executioner",
     "icon": "Throne World executioner icon.png",
     "size": [ 50, 50 ],
     "article": "Lucent Executioners"
   },
   "patrol": {
     "name": "Random Patrols",
     "fillColor": "#aaa",
     "strokeColor": "#aba",
     "strokeWidth": 1,
     "size": 15
   },
   "moth": {
     "name": "Lucent Moths",
     "pinColor": "#b892de",
     "size": 30
   }
 }
}

[executioner's size can be shortened to 50, for both axes]

Grouping groups

This is planned for an upcoming release, but not currently supported.

Categories

[tbh they're so limited atm i have no idea what to write here] [proper filtering planned in early 2024 around v0.19?]

Markers

Now that you have some background and marker groups configured, it's time to add the markers. Let's start with the positioning:

lat (short for latitude), or y (required)

number - The vertical (Y) coordinate the marker will be placed at.

lon (short for longitude), or x (required)

number - The horizontal (X) coordinate the marker will be placed at.

To help with picking the coordinates, you may:

• Use the default percentage-based scale (from 0 to 100) if your background is using default positioning.
• Adjust your background's at property to match the image's resolution. This will let you use pixel positions from the actual image as your locations.
• Point your mouse cursor at a desired spot on the map. The coordinates will be shown in the viewport's bottom-left corner.

[todo Y axis flip (flipped topleft/bottomright corners) needs to be covered above, and this needs to be rewritten]

Aside from location, markers can also have the following individual properties:

id

string or number - This is used when linking to a specific marker on a page (with the marker parameter in the URL). The viewport will be automatically adjusted to focus on the marker, and its details panel will be opened.

If not set, an ID is generated automatically from the layers the marker is assigned to and its location.

icon (only in icon groups)

file name - Use this to give specific markers unique icons without creating extra groups.

[move search props to its own section]

canSearchFor

boolean - TODO. Only valid if marker search is configured. See below.

searchKeywords

array of number (weight) and string (text) pairs - TODO. Only valid if marker search is configured. See below.

Description properties

When a marker is clicked on, a details panel appears over it. To customize the information shown within:

name

string - Self-explanatory.

Wikitext is supported.

description

string - Self-explanatory. Can be multiline (use an array of strings).

Wikitext is supported.

image

file name - Set this to show an image within the details panel. While only a thumbnail is shown in the panel, a reader can still click on it to expand (if MultimediaViewer is enabled on your wiki).

article

string - Set this to a page's name if you want it linked inside the details panel. This will show up as a "Read more" button.

If a single article applies to all the markers within a group, instead of duplicating this property multiple times you can simply set it on the group.

To make the button display custom text instead of "Read more", add a pipe character | after the article's name and write your own button label. For example: "Lost Sectors#Sepulcher|About Sepulcher".

isWikitext

boolean - Usually you won't ever need to set this. Setting this to true forces the name and description properties to be treated as wikitext.

By default, the server tries to be smart and decides if the text needs processing or not (as evaluating wikitext is a rather slow process). Therefore, changing this property is not needed in 99% cases.

Adding markers to the map

Now that you've decided on your marker's contents, it's time to add it to the map's markers property:

{
 ...,
 "markers": {
   "executioner": [
     {
       "id": "quagmire-executioner"
       "x": 62,
       "y": -372,
       "name": "Alluring Curtain Executioner",
       "description": [
         "Weekly target for the Ascended Bounty Hunter triumph.",
         "",
         "To progress the triumph, remember to open the chest guarded by this Lucent Hunter."
       ],
       "image": "Alluring Curtain Executioner screenshot.jpg"
     }
   ]
 }
}

Tying markers to a background

[todo, PoE night ig as an example?]

Embedding in articles

Source code pages of maps in the Map namespace are not meant to be visited directly by readers and do not get indexed by search engines such as Google. From the perspective of a crawler (a bot indexing sites on the web), those pages have no text relevant to a potential reader and will rank low.

In an upcoming release, source code pages will start displaying source code validation errors and recommendations, which are only relevant to editors.

It is therefore best for maps to be shown in articles with, at a bare minimum, at least a short introduction. To do so, use the {{DataMap:title}} function (or its alias {{Map:title}}).

For example, if you have a source code page of Map:Throne World use {{Map:Throne World}}.

Tuning

Hiding coordinates

When mouse cursor is moved over the map, current coordinates under the cursor are shown in the bottom-left corner. To disable this behavior, set the showCoordinates property to false on the settings object.

{
 ...,
 "settings": {
   "showCoordinates": false
 },
 ...
}

Advanced topics

Collectibles

[gotta go back to the lucent moth above above, and turn it into a collectible]

Fragments

[reusable split-up bits of map source pages. low priority section.]

In a future release, it will be possible to reference Scribunto modules and have them generate source code snippets.

Including fragments from other wikis via the interwiki system is currently not supported, but may be investigated in future (along with a localisation system).