en ru | docs

API Reference

MapBBCodeUI.js and MapBBCodeUI.Editor.js contain only 6 public methods combined. Note that when built separately, UI scripts require MapBBCode.js, EditorSprites.js (base64 contents of a PNG image with button icons) and FunctionButton.js (see below). They also support all other modules described in the Leaflet plugins page, but can work without them.


For custom bbcode processing two methods used internally were made public:

Methods show and editor return a control object with those properties and methods:


Usually configurable by a forum administrator:

Option Type Default Description
defaultPosition Number[] [22, 11] Coordinates of the center of a map when opened with empty bbcode.
defaultZoom Number 2 Default zoom of a map when bbcode is empty.
viewWidth Number 600 Width of a map panel when displaying a bbcode. Here and below 0 means 100%.
viewHeight Number 300 Height of a map panel when displaying a bbcode.
fullViewHeight Number 600 Height of an expanded map panel. Width is always 100%.
fullFromStart Boolean false Whether the map panel is opened already in expanded state. The button is hidden in this case.
fullScreenButton Boolean true Whether to show a button for expanding the map panel.
editorHeight Number 400 Height of an editor panel, if editor() method is used.
windowWidth Number 800 Width of an editor window, if editorWindow() method is used.
windowHeight Number 500 Height of an editor window, if editorWindow() method is used.
preferStandardLayerSwitcher Boolean true If this option is false and L.StaticLayerSwitcher class is present, it will be used instead of a standard Leaflet layers control.
allowedHTML String see source code Regular expression that matches all HTML tags allowed in object titles.
outerLinkTemplate String '' Template for outer link for displayed map center and zoom. Example: 'http://openstreetmap.org/#map={zoom}/{lat}/{lon}'. If not specified, outer link button is not shown.

Map layers are specified by any of those options. If none are included, an OpenStreetMap default layer is used.

Option Type Description
layers String[] Array of layer identifiers. See window.layerList below.
createLayers Function(L) Function that receives Leaflet object as a parameter and returns an array of Leaflet layers.

Other options:

Option Type Default Description
maxInitialZoom Number 15 Maximum zoom level for displayed features. Prevents zooming too close for single markers.
letterIconLength Number 2 Maximum title length for using L.LetterIcon for markers.
popupIconLength Number 30 Maximum title length for using L.PopupIcon for markers.
externalEndpoint String see source code URL of a map sharing server, for showExternal() and the upload button.
uploadButton Boolean false Whether to allow uploading maps to a sharing server from editor.
polygonOpacity Number 0.1 Fill opacity for polygons.
leafletOptions Object {} Additional options passed to L.Map constructor.
hideInsideClasses String[] [] List of classes inside which map panel will not be displayed (useful for disabling maps in signatures).
watchResize Boolean false Whether to watch the map panel for resizing (otherwise map may become buggy).
enablePolygons Boolean true Whether to show polygon drawing button in the editing toolbar.
helpButton Boolean true Whether to show help button in the editor.
editorCloseButtons Boolean true Whether to show "Apply" and "Cancel" buttons in the editor.
confirmFormSubmit Boolean true If the editor is opened inside a form, inform a user of losing changes when the form is submitted.
windowFeatures String 'resizable,status,dialog' Parameters for window.open() used for opening an editor window.
windowPath String 'lib/mapbbcode-window.html' Path (relative or absolute) to the editor window page (file name can be omitted).
panelHook Function null A function that receives a control object (see above) right after the UI has been initialized. Can be used to alter UI behaviour both in a viewing panel and in a window.


MapBBCode UI functionality can be extended with handlers. Usually they process bbcode parameters: the BBCode specification states that the only customizable part of [map] bbcode is object parameter set. But it is possible to do virtually anything with handlers, like add an extra buttons or a layer to the map, or create a useful control, like the length measurement handler does. Text and Color handlers are mandatory for MapBBCode (though it can work without them), others are optional.

To create a new handler, you have to push to window.mapBBCodeHandlers array an object with the following properties and methods (only applicableTo is mandatory):


MapBBCode.js is a reference implementation of parsing and generating map bbcode. It contains complete regular expressions for the code and following methods:

Option Type Default Description
decimalDigits Number 5 Number of decimal digits in coordinates in generated bbcode.
brackets String [] Brackets for bbcode. Can be replaced with <> or ().
tagParams Boolean false If set to true, opening tag should be specified with parameters: [map z="1" ll="2,3"]. Together with brackets option this allows for HTML-like tags.
shareTag String 'mapid' A bbcode tag for external map id.

Since brackets can be modified, there are some extra methods for getting opening and closing tags. All of them return strings.

Configuration Tool

To simplify configuring map panel dimensions and a list of available layers, there is a separate javascript module that can be easily integrated in an administration panel. It requires window.layerList and L.StaticLayerSwitcher for easier editing of layers. Also see a guide on integration.


The MapBBCodeConfig class includes all options listed above in "configurable by a forum administrator" table, except the last three (preferStandardLayerSwitcher, allowedHTML and outerLinkTemplate). Instead there are additional options for configuring the configuration panel:

Option Type Default Description
editorInWindow Boolean true Whether the editor is opened in a window or in an inline panel.
editorTypeFixed Boolean false Whether an administrator can change the above option, or the type is hard-coded into a template.
maxLayers Number 5 Maximum number of layers on a map.


bindLayerAdder option What does it reference
select <select size="1"> for a layer list
button <input type="button"> for adding a selected layer
keyBlock an initially hidden block for entering a key for layers that require it
keyBlockDisplay display CSS value for that block
keyTitle <span> where a title for key input field will be inserted
keyValue <input type="text"> for entering a key


There are a number of Leaflet events that the panel emits.

Event Data When fired
show options object Configuration panel has been created.
change options object Any of the options were changed.
layerselected { <String> id } A user selected another layer (does not affect options).