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:- Preview - everything looks and works the same as a final version of your map after you insert it to your wesbite. But Responsive option is always turned on in MapSVG Builder (required for proper resizing of a map in the Builder) and Directory preview isn't available.
- Edit regions - markers are hidden, all custom event handlers are disabled. Zoom & Scroll are turned ON. Region tooltips are changed to show region's ID:title. When you click on a region - Builder switches to "Regions" tab and scrolls to the region to start editing.
- Edit markers - available only when you edit a Database record.
- Edit data - all custom event handlers are disabled. Zoom & Scroll are turned ON. Tooltips are changed to show region/marker ID. Clicking on a region/marker opens "Database" page and database records for that region/marker are being shown.
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 |
|
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 |
|
Choropleth field | Choose custom field in Region object which should be used for Choropleth map. |
Gradient labels |
low - label for lowest valueshigh - 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 Regionsbrightness (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 directoryDatabase - use list of Databse objects to generate the directory
|
Container |
Default - directory is attached to left/right side of the mapCustom - 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:
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:
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:
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:
Parameters:this - MapSVG instance
|
afterLoad | Fires after MapSVG finished rendering SVG file.
Example:
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 objecte - jQuery event handlermapsvg - MapSVG APImapObject - Object which invoked a popover. It could be a Region or a Marker.Example:
|
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:
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:
Regions
withfill="none"
are being disabled by MapSVG. If you want to have an activeRegion
without color - give thatRegion
some transparent fill likergba(0,0,0,0)
- It's always good to optimize your SVG files - remove unnecessary groups, join multiple paths with the same color into one - it improves map loading speed and overall performance (remember that every object in SVG file becomes a DOM node in HTML and too many DOM nodes slow down everything);
-
If you export SVG file from Adobe Illustrator - use the following settings:
File > Export > SVG
Styling = Internal CSS
ObjectIDs = Layer Names
Responsive = No (you will be able add responsiveness later in MapSVG)
Don't forget to set ID for each object you want to be active. You can do that in Layers palette in Adobe Illustrator - give each object a name and it will be used as objectID in SVG file; - If you edit your SVG file in InkScape you can set ID for an object in the next way: right-click on an object, choose "Object properties" from pop-up menu, set ID;
- If you have an image with lots of objects which don't need to be clickable, use "Disable all regions" button in "Settings" tab of MapSVG Builder. It disables all regions and then you go to "Regions" tab to enable back only those you need to be active.