DataMaps/Data format

From Support Wiki
Jump to navigation Jump to search
This page describes the data format of an upcoming DataMaps version.

This page describes the JSON-based data format used by the DataMaps extension.

Versioning

The data format is versioned and described using JSON Schema. Those schema files areavailable in the extension's source code repository:

  • v0.16 (latest; support will be removed in v0.17)
  • v0.15 (contains some errors; support will be removed in v0.17)
  • The latest schema can be also targeted through the latest.json file.
    • This is, however, not recommended as validation issues may appear after a new extension version is deployed.

The schema a map follows must be specified in the $schema field at the top of the document - a link to a copy of the schema in the code repository or wiki's domain is expected: For example:

On most format updates, maps will be updated automatically by Bot4401.

Historical schemas

Primitive types

Point

Array of two decimals, where first element is the latitude and second is the longitude.

Dimensions

Array of two decimals, where first element is the width and second is the height. Alternatively, a number, which will be used for both axes.

Box

Box is an array of two Points, where first describes the start point of the box and second describes the end point.

Title

A file name of an image. The image **must exist**. The `File:` prefix is not required, but supported only in its English form.

RGB colour

Either a three element array of integers in `0..255` range, or a 3- or 6-long hex string beginning with `#`, representing an RGB colour with no transparency.

RGBA colour

Either a four element array of three integers in `0..255` range and one decimal between 0 and 1, or a 4- or 8-long hex string beginning with `#`, representing an RGBA colour (with an alpha channel).

Layer ID

A string that does not contain any whitespace, colons (:), or hashes (#).

Reserved names: bg.

Document structure

These tabs contain descriptions of various format versions (versioned separately from the extension) supported by the extension.

The version your map follows must be specified with a $schema property at the very start of the source code:

Fragments

Maps may be split into multiple source pages if desired or to share data or configuration between multiple maps.

To mark a map page as a source fragment, set $fragment to true. This will relax data validation (mostly by permitting required fields to be missing) and will prevent the map from being displayed.

To include fragments, list fragment pages in an include property (with the Map namespace), like such: 

...
"include": [
  "Map:Common groups"
],
...

Document format

Template:DataMaps type Template:DataMaps field Template:DataMaps field Template:DataMaps field Template:DataMaps field Template:DataMaps either field Template:DataMaps field Template:DataMaps field Template:DataMaps either field Template:DataMaps field Template:DataMaps field Template:DataMaps type

Object types

CoordinateSystem

Template:DataMaps type Template:DataMaps field Template:DataMaps field Template:DataMaps field Template:DataMaps type

Settings

Template:DataMaps type Template:DataMaps field Template:DataMaps field Template:DataMaps field Template:DataMaps field |- name="DataMap-field-backdropColor" | backdropColor | Optional. RGB colour.

When set, controls the backdrop colour of the map.

To change the backdrop for all maps on your wiki, you should use custom CSS via MediaWiki:DataMaps.css.

Since: v0.16.4

Default: none |- name="DataMap-field-disableZoom" | disableZoom | Optional. Boolean.

Whether zoom control will be disabled on this map. Individual Leaflet options can override this.

Default: false |- name="DataMap-field-enableTooltipPopups" | enableTooltipPopups | Optional. Boolean.

Whether simply moving mouse cursor over a marker should cause its popup to become visible. Such popup will be partially translucent. The user still has to click on the marker for the address bar to update with a permanent link.

Since: v0.16.3

Default: false |- name="DataMap-field-enableSearch" | enableSearch | Optional. Whether marker search will be enabled for this map. Accepted values:

  • false: disabled.
  • true: enabled; results will be shown only for this map.
  • tabberWide: enabled; search shows results from all maps within the same tabber.

|- name="DataMap-field-hideLegend" | hideLegend | Optional. Boolean.

Forces the legend (including collectible checklists and marker filters) to not be loaded on this map. |- name="DataMap-field-interactionModel" | interactionModel | Optional.

Accepted values:

  • "keybinds": two fingers or Control/Super need to be used to change map zoom.
  • "sleep" (experimental): zoom will be activated only after the map is clicked or a certain amount of time passes since the mouse cursor was moved over it.

Since: v0.16.3

Default: "keybinds" |- name="DataMap-field-iconRenderer" | iconRenderer |

Since: v0.16.0

Default: "auto" |- name="DataMap-field-requireCustomMarkerIDs" | requireCustomMarkerIDs | Optional. Boolean.

Makes data validation disallow automatically generated marker IDs - the `id` property will need to be specified for each marker manually.

These identifiers are used for persistent links and collectible progress tracking. By default, group and layers the marker is attached to along with its location on map are used to generate the identifier.

Default: false |- name="DataMap-field-showCoordinates" | showCoordinates | Optional. Boolean.

Whether coordinates from under the mouse cursor will be shown on this map in the bottom-left corner.

Default: true |- name="DataMap-field-sortChecklistsBy" | sortChecklistsBy | Optional.

Specifies marker group checklist sort order.

  • "groupDeclaration": Follows the order in which marker groups are declared in source data.
  • "amount": Follows the number of markers inside each group.

Default: "groupDeclaration |- name="DataMap-field-leaflet" | leaflet |

|} |- name="DataMap-field-groups" | groups | Dictionary of unique layer IDs to marker group settings (Record<string, MarkerGroup>). |- name="DataMap-field-layers" | layers | Dictionary of unique layer IDs to marker category settings (Record<string, MarkerCategory>). |- name="DataMap-field-markers" | markers | Dictionary of layer association strings to markers (Record<string, Marker>). Layer association strings consists of a marker group ID and any number of category IDs separated with a single space.

Type: Marker
lat

Latitude of marker

lon

Longitude of marker

x

x coordinate of marker

y

y coordinate of marker

name

Title of a popup appearing when clicking on the marker

description

Description text shown below the title when clicking on the marker

image

File name of image (without the File: part) shown below the description when clicking on the marker

isWikitext

boolean

|- name="DataMap-field-custom" | custom | Optional. Any JSON object (with strings as keys), with no structure or type checking (Record<string, any>). This property can be used to pass data to bots, gadgets and other custom JavaScript scripts. It is included in the generated HTML of a page including the map, so bigger payloads should be fetched with alternative methods. |}

Retrieved from "https://support.wiki.gg/index.php?title=DataMaps/Data_format&oldid=1291"