Skip to content

Latest commit

 

History

History
122 lines (91 loc) · 5.19 KB

bbcode.md

File metadata and controls

122 lines (91 loc) · 5.19 KB
Raw
layout title
default
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.

  • isValid(string) tests that the string is a valid map bbcode.

  • stringToObjects(string) parses a bbcode string into an object:

      {
    objs: [{
      coords: [<coordinate>, ...],
      text: <string>,
      params: [<string>, ...]
    }, ...],
    zoom: <number>,
    pos: <coordinate>
  }

    Format of <coordinate> depends of whether you have Leaflet library included: it will be either L.LatLng object or an array of two numbers: [latitude, longitude].

  • objectsToString(object) takes an object in the same format as the stringToObjects produces and returns a bbcode string.

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.