en ru | docs

Map BBCode Syntax

The author expects this format of [map] bbcode to become a universal standard across forums and other collaboration tools, like mediawiki. This is a description of the bbcode itself.

Description

Map BBCode is usually enclosed in [map]...[/map] tags. Of course, it is not a requirement: for example, in wiki those might be converted to HTML tags: <map>...</map>. Opening tag may contain zoom level and optional coordinate (latitude, longitude): [map=10] or [map=12,59.9,30.5]. In this case automatically determined zoom level and bounds for features are overridden.

A map tag contains an unordered list of features, separated by semicolons. There might be zero features, in which case a map displays a location stated in its opening tag, or a default location if there isn't any.

A feature can be either a marker, a polyline or a polygon. All those are defined by a space-separated list of coordinates (also latitude,longitude). Markers have a single coordinate, polylines have several, polygons have their first coordinate equal to the last.

Usually coordinates are in WGS-84 projection, though for some instances it may be different. For example, for drawing on a fantasy map (e.g. videogame world) pixel coordinates may be used.

Features have optional parameters, a string in brackets after the coordinate list. It looks like (option,option|title): several comma-separated options (that may contain only letters and digits), then a vertical bar and a title. Both parts — options and a title — can be omitted. If there are no options, the vertical bar can be omitted also, but in this case the first vertical bat in the title should be screened: \|. Closing brackets in the title should also be screened: \). Apart from that, any characters are allowed in the title: usually it is an HTML or BBCode string.

The implementation in MapBBCodeUI.js assumes the title is HTML, but screens all special characters except a number of tags (<a>, <br>, <span> and some others). It also knows of colour options: red will make a polyline or a polygon red, and so on.

Examples

[map][/map]

Displays a map in a default location with no features.

[map=10,59.95,30.27][/map]

Displays a map of Saint-Petersburg with no features.

[map]59.939,30.3159(Dvortsovaya)[/map]

A map zoomed onto a Dvortsovaya Square with a marker in the center. The marker has a title (usually appears in a popup panel), "Dvortsovaya".

[map]59.939,30.3159; 59.93709,30.31265 59.93115,30.3602 (black|);
59.94577,30.33244 59.93904,30.3369 59.93408,30.33497 59.92257,30.30776[/map]

A marker is still on Dvortsovaya Square, Nevsky Prospect is a black line, and a part of Sadovaya Street is a line of a default colour (usually blue).

[map]55.7547,37.6181 55.7553,37.6191 55.7531,37.6232 55.7528,37.622
     55.7547,37.6181(red|Square)[/map]

Red Square in Moscow is covered with a red polygon, which shows a popup panel when clicked with "Square" word in it.

BNF

To reduce clutter, we'll define some base nonterminals with regular expressions.

<empty>   ::= ""
<zoom>    ::= [12]?[0-9]
<number>  ::= -?[0-9]+(\.[0-9]+)?
<word>    ::= [a-z0-9]+
<noslash> ::= .*?[^\\]

<coordinate>  ::= <number> "," <number>
<coordinates> ::= <coordinate> | <coordinate> " " <coordinate>
<title>       ::= <empty> | <noslash>
<words>       ::= <empty> | <word> | <word> "," <words>
<parameters>  ::= "(" <words> "|" <title> ")" | "(" <title> ")"
<element>     ::= <coordinates> | <coordinates> <parameters>
<elements>    ::= <empty> | <element> | <element> ";" <elements>
<position>    ::= <zoom> | <zoom> "," <coordinate>
<openingtag>  ::= "[map]" | "[map=" <position> "]"
<map>         ::= <openingtag> <elements> "[/map]"

Library

MapBBCode.js is a reference implementation of parsing and generating map bbcode. It contains complete regular expressions for the code and three methods you can use in your projects.

See complete description of that class in API reference.

Improvements

The format of map bbcode is set in stone. But element parameters, <words> nonterminal in BNF, may be whatever you want. For now only one parameter type is defined: colour. One can implement, for example, line width with w<number> parameter, or a marker type. Implementations of map bbcode are not required to support any of parameters, thus parameters should not alter behaviour or presentation of features much.