MapSVG WordPress plugin interactive vector map builder documentation

Introduction

Both WordPress and jQuery versions of MapSVG now have the same MapSVG Map Builder and they share almost identical functionality so there is one common documentation for both versions.

If you have jQuery version of MapSVG Builder and you still want to dive into the code, there is a special jQuery documentation.

Installation

WordPress version

Download ZIP file from CodeCanyon and unpack it. You will get a mapsvg folder containing all plugin files. Upload it to your plugins folder (default path is /wp-content/plugins). Then go to your WP Admin Panel, choose Plugins > Installed plugins > MapSVG > click "Activate". MapSVG menu item will appear in menu on the left.

Also you need to change access rules for /wp-content/plugins/mapsvg/maps/user-uploads to 777.

WordPress: updating to MapSVG from previous versions

Just overwrite /wp-content/plugins/mapsvg folder with new version of MapSVG. Don't remove your previous installation or you will lose your custom maps and markers. Then go to MapSVG control panel: migration script will start and it will update all your maps to the new version.

jQuery version

Just put mapsvg folder with all its contents anywhere on your server. Then enter http://yoursite.com/path-to/mapsvg/ to get started.

Plugin is able to work in 2 modes:

Mode is being switched automatically: plugin tries to make an AJAX call to /mapsvg/functions.php file and in case of success it switches itself to PHP mode.

If you have PHP mode turned ON - you need to change access rules for .../mapsvg/maps/user-uploads to 777.

Creating a new map

WordPress version

SVG maps are located in /wp-content/plugins/mapsvg/maps folder. Plugin scans that folder each time you open MapSVG Control Panel to get the full list of available maps. Click on the search box on the start screen of MapSVG Builder and start typing the name of map you need.

jQuery version

If you have PHP mode ON - just start typing the name of map you need in the search box on the start screen of MapSVG builder, or upload a custom SVG file from your browser.

If you have PHP mode OFF - enter URL of a SVG file and click "Go". If you want to upload custom SVG file - put it into /mapsvg/maps/user-uploads folder.

Also you're able to edit the map you have previously created in MapSVG and inserted into your website. To do that, just enter URL of that page on the start screen of MapSVG Builder and it will get map settings from that page automatically.

Map modes

There are 3 modes for the map preview:

Settings

Parameter Description
Title Title of a map.
Width Width of a map. If Responsive is turned ON then width has effect only on width/height ratio of the map.
Height Height of a map. If Responsive is turned ON then height has effect only on width/height ratio of the map.
Lock aspect ratio Unlock if you want to change default width/height ratio of the map.
Start position Defines initial viewBox for the map. If you want your map to start with some initial zoom - zoom it in the preview and the click Set. Position will be remembered and you can continue editing your map.
Responsive

On: the map will always take all available width of its container, keeping width/height ratio defined above.

Off: the map will have static size with width/height deafined above.

Scroll on | off - enable or disable map scrolling.
Zoom on | off - enable or disable map zooming.
Zoom buttons hide | left | right - position of +/- zoom buttons.
Zoom limits Set min and max levels of zoom, starting from initial map position defined above.
Global popovers

Popovers are info boxes with close button which are being shown onClick on a Region or Marker.

Global popovers are being shown for all active (not disabled) Regions and Markers.

Local popovers (defined in Regions / Markers) have priority over globals.

off - don't use global popovers
function - custom JS function which should return a string. Example:

function(jQueryPopoverObj, mapObject, mapsvgInstance){
    // You can also use "this" word which refers to clicked mapObject
    if(this.mapsvg_type == "region")
        return 'Region - <b>'+this.id+'</b>: '+this.title;
    else if (this.mapsvg_type == "marker")
        return 'Marker - <b>'+this.id+'</b>';
}

Global tooltips

Tooltips are info boxes with are being shown on hover over a Region or Marker.

Global tooltips are being shown for all active (not disabled) Regions and Markers.

Local tooltips (defined in Regions / Markers) have priority over globals.

off - don't use global tooltips
SVG id - show Region ID defined in SVG file or in case of a Marker - ID defined in MapSVG Builder.
SVG title - show Region title defined in SVG file. Shows nothing for a Marker.
function - custom JS function which should return a string. Example:

function(jQueryTooltipObj, mapObject, mapsvgInstance){
    // You can also use "this" word which refers to clicked mapObject
    if(this.mapsvg_type == "region")
        return 'Region - <b>'+this.id+'</b>: '+this.title;
    else if (this.mapsvg_type == "marker")
        return 'Marker - <b>'+this.id+'</b>';
}

Curor Cursor style which is applied when you hover the mouse over a Region
Multiselect on | off - enable / disable an ability to select multiple Regions.
Gauge

on | off - use it to represent statistical information by every Region on your map with different shades of a color: population, income, fuel prices, etc. Such maps are called Choropleth Maps (link opens Wiki in new tab).

To get an idea how it works, turn Gauge on and then switch to Regions tab and set gaugeValue for a few Regions.

Gauge labels low - label for lowest Gauge values
high - label for highest Gauge values
Menu

on | off - adds clickable list of Regions into any container.

Menu contaier

ID of menu container. You have to add empty <ul id="id_example"></ul> container anywhere on your page by yourself. Then MapSVG will fill it automatically with list of active (not disabled) Regions.

Menu item template

JavaScript template function which should return a string. Default template:

function (region) {
    return '<li><a href="'+region.id+'">'+(region.title||region.id) + '</a></li>';
}

Preloader text

Text being shown during map loading process. Default is "Loading map...".

Colors

Parameter Description
Background Color of a background. Applied to MapSVG div container. Click on a grey button on the left of input field to show Color Picker. Also you can enter color value manually into the text input field. Besides color values you can use the word transparent to make a transparent background. Or you can use image URL in CSS format url(/path/to/image.png)
Base Base color for all Regions. Overrides Region colors defined in SVG file.
Disabled Color of disabled Regions
Strokes Color of strokes (Region borders)
Hover Color for Region hover state. There are 2 modes:
color - static color for all Regions
brightness (default) - change Region brightness relative to it's default color. This mode is useful when you have regions with different colors.
Selected Color for Region selected state. Two modes, same as for Hover.
Gauge low Color of Region with lowest gaugeValue
Gauge high Color of Region with highest gaugeValue

Regions

Parameter Description
Disabled Disable a Region to make it non-clickable (also hides it from automatically generated menu with list of Regions).
Color Color of a Region.

Some color settings have more priority than others. This is the color chain affecting final Region color, Gauge color has the biggest priority:
Gauge < Region color < Disabled(?) < Base < SVG
Tooltip Tooltip text / HTML. Has priority over Global Tooltips
Popover Popover text / HTML. Has priority over Global Popovers
Link URL to open on click.
Data Any data object which you can use in custom event handlers or global tooltips/popovers. Data can be in JSON format or javaScript object format. Example:
{myParameter: "Hello Wordl!"}
And then in onClick event handler:
function(){
    if (this.data.myParameter)
        alert(this.data.myParameter);
}

Markers

If a map is geo-calibrated, you will see New Marker input field in Markers tab. Just enter an address and marker will be added to the map.

Also you can add a Marker if you switch the map to Edit Markers mode: click on the map to add a marker.

Click on a Marker in Edit Markers mode to edit it.


Parameter Description
ID Unique ID of a Marker. Spaces not allowed here.
Lat/lon coordinates Visible only if map is geo-calibrated. Geo coordinates of a Marker.
Image Image for a Marker. You can add your custom Marker images into .../mapsvg/markers/ folder. Note that markers are being positioned by a center point at bottom of an image.
Link URL to open on click.
Data Any data object which you can use in custom event handlers or global tooltips/popovers. Data can be in JSON format or javaScript object format. Example:
{myParameter: "Hello Wordl!"}
And then in onClick event handler:
function(){
    if (this.data.myParameter)
    alert(this.data.myParameter);
}

JavaScript

Parameter Description
onClick Fires onClick on a Region or Marker. Example:
function(e,mapsvg){
    var region = this;
    alert(this.id);
}
Parameters:
this - MapObject (could be a Region or a Marker)
e - event object (same as in jQuery)
mapsvg - MapSVG instance
mouseOver Fires on mouseOver on a Region or Marker. Example:
function(e,mapsvg){
    var region = this;
    alert(this.id);
}
Parameters:
this - MapObject (could be a Region or a Marker)
e - event object (same as in jQuery)
mapsvg - MapSVG instance
mouseOver Fires on mouseOut on a Region or Marker. Example:
function(e,mapsvg){
    var region = this;
    alert(this.id);
}
Parameters:
this - MapObject (could be a Region or a Marker)
e - event object (same as in jQuery)
mapsvg - MapSVG instance
beforeLoad Fires before MapSVG starts rendering SVG file. Example:
function(){
    var mapsvg = this;
    mapsvg.setZoom({on: true});
}
Parameters:
this - MapSVG instance
afterLoad Fires after MapSVG finished rendering SVG file. Example:
function(){
    var mapsvg = this;
    mapsvg.setZoom({on: true});
}
Parameters:
this - MapSVG instance