MapSVG WordPress and jQuery plugin interactive vector map documentation

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.
Preloader text

Text being shown during map loading process. Default is "Loading 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.

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.
Scroll
Scroll on | off - enable or disable map scrolling.
Limit scroll to boundaries on | off - defines if it's allowed to scroll outside of map boundaries
Zoom
Zoom on | off - enable or disable map zooming.
Zoom by mousewheel on | off - sometimes it's need to disable zoom by mousewheel to prevent page scrolling lock when mouse is over the map. Usually you need this only when map takes full width of a page - when there's no place for mouse pointer to start scrolling the page.
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
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.

Tooltips position botton-right | bottom-left | ...

Position of tooltip box relative to mouse pointer

Popovers
Center map on popovers on | off

Center the map on popover to prevent popover box going out of the view

Regions
Region ID prefix If not empty then then only objects with provided prefix in ID get into "Regions" list. Warning! Changing ID prefix resets all Region settings & data. Hide

This is useful when you create a custom SVG file with many small graphic details (for example a floorplan) which shouldn't be interactive and you want to filter out those details from "Regions" (interactive objects) list.

Example of IDs in SVG file with "region_" prefix: region_ABC, region_DFE.

And this is how you would see the same IDs in MapSVG: ABC, DFE.

If you work in Adobe Illustrator, layer names can be converted into IDs when you export the file to SVG format - such option is abailable in Adobe Illustrator SVG export settings.

If you work in InkScape, right-click on an object, choose "Object Properties" to set an ID.
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 map
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).

Region numeric 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
Mobile devices
Map button label label near "map" button which is shown on mobile devices to reveal the map
Directory button label label near "menu" button which is shown on mobile devices to reveal the directory

Colors

Parameter Description
Containers
Map 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)
Directory Color of directory
Search & filters Color of search & filters box shown above directory
Details view Color of a details view
Map 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)
Regions
Base Base color for all Regions. Overrides Region colors defined in SVG file.
Borders Color of Regions 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.
Chorolpleth map
Low Color of Region with lowest gaugeValue
High Color of Region with highest gaugeValue

Regions

List

List of all Regions from SVG file. Click on a row in the table to edit a region.

Structure

Here you can add custom fields to Regions.

Database

Database lets you to create a list of custom objects which could be attached to Regions and/or represented as Markers. Example of use could be dealers (Database objects) working in a different states (Regions) of USA.

If you need to add markers to a map you have do that with "Database" functionality - by adding "Marker" field to your database structure. Think of Markers as a visual representation of your database objects.
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 a form builder which lets you to create a form which will 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
MapSVG
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
Database
databaseLoaded Fires when all custom objects from current page are loaded from the database into MapSVG. Fires on each page. Example:
function(){
    var mapsvg = this;
    mapsvg.setZoom({on: true});
}
Parameters:
this - MapSVG instance
Region
click.region 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.region 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
mouseout.region 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
Details
shown.details Fired right after details view was is shown.

Parameters:
this - jQuery container with Details View
Example:
function(){
    this.find('.something').runSomeJqueryPlugin();
}
Popover
shown.popover 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 Region parameters and shows 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:

{{my_field}}
{{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="{{images.0.thumbnail}}" />

Show all images attached to a Region:

{{#each 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: