MapSVG WordPress and jQuery plugin interactive vector map documentation

This documentation is the for latest WordPress MapSVG 3.x.x.
Documentation for jQuery/WordPress MapSVG 2.x.x can be found here.

Installation

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.

Make sure that WP user upload folder is writable: set /wp-content/uploads permission to 777.

WordPress: upgrading to MapSVG 3.x from 2.x

MapSVG 3 has changed so much since version 2 so it isn't possible to automatically convert maps from v2 to v3. But no worries - your map will continue working in "compatibility mode". MapSVG Builder 2.x interface will be loaded in WP Admin for maps created in 2.x version.

Creating a new map

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.

Map modes

There are map 4 modes in MapSVG Builder:

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.
Tooltips on | off

Tooltips are info boxes which are being shown on mouseOver on a Region or Marker.

You have to define tooltip template in "Templates" section of MapSVG Builder.

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

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

Choropleth field Choose custom field in Region object which should be used for Choropleth map.

Gradient labels low - label for lowest values
high - label for highest values
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
Color Color of a Region.

Some color settings have more priority than others. Below is the color chain affecting final Region color, Gauge color has the biggest priority:
Gauge color < Region color < Disabled(?) color < Base color < SVG color
Disable Disable a Region to make it non-clickable

Database

This section lets to create a custom dataset which could be attached to Regions and/or represented as Markers.

List

If structure of database is already defined, you should see a table with your data. Click on Add button to add records into the database. Click on a row in the table to edit database record.

Structure

Structure section has form builder which lets to to create a form which would be used to add records into the database.

Settings
Parameter Description
Pagination on | off If you turn off pagination, all data would be loaded from MySQL database into MapSVG at map start. Use with caution - large data sets could take a long time to load. Pagination has effect on how many items is being shown in the Directory if source:Database is chosen for the Directory. Also pagination defines how many markers is being shown on the map (even if Directory is switched off, Markers on the map still can be paginated).
Items per page number Define how many items should be shown on each page.

Directory

You can show directory containing the list of Regions or Database Objects with search field.

Parameter Description
Data source Regions - use list of Regions to generate the directory
Database - use list of Databse objects to generate the directory
Container Default - directory is attached to left/right side of the map
Custom - directory is being inserted into any custom container
Container ID ID of custom container for the directory
Position left | right

Position of a directory, used only for when "Default" container is choosed.

Width number

Width of directory in pixels, used only when "Default" container is choosed.

Sort by Sort menu items by given attribute.
Sort direction A..Z | Z..A
Search on | off

Adds search field into a directory container. Search is being made by all attributes of provided data source.

Search placeholder Text shown in search input field when it's empty.

Details view

This section lets you to set a custom details view which you can show on click on a Directory item / Region / Marker.

Starting from MapSVG 3.0 it is recommended to use Details View instead of popovers for large amounts of information. Details View is reponsive, scrollable and is readable on any screen; and large popovers are problematic to position correctly without losing some data outside of the view. Use popovers only for small messages.

Actions

This section lets you to choose actions on click on a Directory item / Region / Marker.

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
popoverShown Use this event handler if you need to do something with the popover after it's been shown. For example, you may need to run some specific jQuery plugins or change popover CSS.

Parameters:
this - Popover jQuery object
e - jQuery event handler
mapsvg - MapSVG API
mapObject - Object which invoked a popover. It could be a Region or a Marker.

Example:
function(e, mapsvg, mapObject){
    this.find('.something').runSomeJqueryPlugin();
    // Set popover background color to the same color as clicked Region
    this.css({background: mapObject.fill});
}

Templates

If you want to show tooltips, popovers or directory - you need to create templates.

Templates are working on Handlebars (click on the link for more information).

For example, when popover is being shown for a Region, Region object is being passed into the template and then Handlebars renders the template to show formatted HTML content. You can use all parameters of passed object in a template with special Handlebars curly brakets {{ }}.

So if you click on a Texas state which has ID "US-TX", then the next popover template:

<b>{{id}}</b> - {{title}}
Would produce the next HTML:
US-TX - Texas

Please note that when you need to access an item in array, which you usually do this way: my_array[0], my_array[1], should be done slightly different in Handlebars templates:

{{my_array.[0]}}
{{my_array.[0].parameter}}

Examples: Region is passed into a template

Show Region ID and Title:

{{id}}
{{title}}

Accessing custom fields of a Region:

{{data.my_field}}
{{data.my_other_field}}

Accessing database objects attached to a Region:

{{objects.[0].my_field}}
{{objects.[1].my_field}}

Iterate over all database objects attached to a Region and show their fields:

{{#each objects}}
    {{my_field}}, {{my_other_field}}
{{/each}}

Show thumbnail of a first image of a Region:

<img src="{{data.images.[0].thumbnail}}" />

Show all images attached to a Region:

{{#each data.images}}
    <img src="{{thumbnail}}" />
    <img src="{{medium}}" />
    <img src="{{full}}" />
    <img src="{{original}}" />
{{/each}}

Examples: Database object is passed into a template

Show custom fields of a Database object

{{my_field}}
{{my_other_field}}

Show thumbnail of a first image of a Database object:

<img src="{{images.[0].thumbnail}}" />

Show all images of a Database object:

{{#each images}}
    <img src="{{thumbnail}}" />
    <img src="{{medium}}" />
    <img src="{{full}}" />
    <img src="{{original}}" />
{{/each}}

CSS

CSS editor. You can override default MapSVG styles or add your own.

Custom SVG files

One of the most important features of MapSVG is that you can always draw your own map or floorplan in any vector editor which is able to export images in SVG format - Adobe Illustrator, InkScape, Corel Draw, etc. Remember that you are not limited to maps - you can add interactivity to any vector image.

Most of the time custom SVG files are working "out of the box" - just upload an image to MapSVG and you're ready to go. However there are few things you need to keep in mind: