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.

Methods

• setStrings( <Object> strings ): replaces strings with provided translations. See strings/English.js for default values.
• show( <HTMLElement/String> div, <String/HTMLElement> bbcode ): creates a map inside a given element (can be referenced by id) for given bbcode. can be extracted from an HTML element: it can be in bbcode or value attributes, or inside it.
• showExternal( <HTMLElement/String> div, <String> id, <Function> callback, context ): download a map from a map sharing service and display it, along with an export button and a link to the service. The callback function receives the control object (see below) after a successful initialization.
• editor( <HTMLElement/String> div, <String/HTMLTextArea> bbcode, <Function> callback, context ): creates an editor in the given panel, possibly pre-initialized with bbcode. The latter is either a string or a textarea, in latter case caret position is taken into account, and the code is replaced after applying changes. Calls callback when “Apply” or “Cancel” buttons are clicked, with a single parameter of new bbcode.
• editorWindow( <String/HTMLTextArea> bbcode, callback, context ): opens a new window with an editor for given bbcode (see editor()). Does not return anything.

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

• objectToLayer( <Object> obj ): converts an object that MapBBCodeProcessor produces into a Leaflet layer, applying all modifications by handlers.
• layerToObject( <ILayer> layer ): converts a Leaflet layer into an object for feeding to MapBBCodeProcessor. Note that some parameters processed by handlers may be lost or determined incorrectly due to extra initialization code in handlers.

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

• map: a reference to Leaflet map object.
• editor: boolean flag for UI type.
• close(): removes all elements, “closes” the panel.
• zoomToData(): zooms and pans the map view to the data.
• getBBCode(): returns BBCode string for objects currently displayed.
• updateBBCode( <String> bbcode, <Boolean> noZoom ): removes all objects in a panel and replaces them with those defined in the given bbcode. If noZoom is true, doesn’t zoom and pan to new objects.
• eachLayer( <Function> callback, context ): iterates over map objects, which are Leaflet layers.

Options

Usually configurable by a forum administrator:

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

Other options:

Handlers

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):

• <RegExp> reKeys: regular expression that matches parameters processed by this module.
• <Boolean> applicableTo( <ILayer> layer ): tests that given layer can contain module’s properties.
• ` objectToLayer( layer, <String[]> params, ui )`: modifies the layer according to the properties, which are filtered by `reKeys`, so there usually is no more than one.
• <String[]> layerToObject( <ILayer> layer, <String[]> lastParams, <MapBBCode> ui ): reads properties off the layer and returns them in a string array. lastParams array contains properties that the object had before it was edited.
• ` initLayer( layer )`: initializes newly created layer with default property values.
• ` initDrawControl( draw )`: modifies [Leaflet.draw](https://github.com/leaflet/leaflet.draw) control according to default property values.
• <HTMLElement> createEditorPanel( <ILayer>layer, <MapBBCode> ui ): creates a panel that will be included in an object popup. It should read and allow editing the property that’s processed by the module.
• ` panelHook(

MapBBCodeProcessor

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

• isValid( <String> bbcode ): tests that the string is a valid map bbcode.

• stringToObjects( <String> bbcode ) 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> objs ) takes an object in the same format as the stringToObjects produces and returns a bbcode string.
• setOptions( <Object> options ): changes option values (see below).

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

• getOpenTagSubstring(): returns an opening bracket and map, useful for finding where a bbcode starts.
• getOpenTag( <Number> zoom, <String> coords ): constructs an opening tag.
• getOpenTagWithPart( <String> extra ): constructs an opening tag using a whole extra part after map.
• getCloseTag(): returns a closing bbcode tag.

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.

Options

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:

Methods

• setStrings( <Object> strings ): replaces strings with provided translations. See strings/English.Config.js for default values.
• addLayer( <String> id ): adds a layer to the list. See window.layerList.
• show( <HTMLElement/String> div ): shows a map panel with controls inside a given element (can be specified by its id).
• bindLayerAdder( <Object> elements ): adds listeners and labels to several input elements for adding layers:

Events

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