Files

After purchasing Mapplic - Custom Interactive Map WordPress Plugin, you can download the package from CodeCanyon, containing two folders and a zip install file:

• docs - documentation, a detailed user guide with an SVG map tutorial on creating Mapplic compatible maps

• mapplic - main plugin files with the required libraries, all the built-in and demo maps

• mapplic-install.zip - installable WordPress plugin

Update

Mapplic comes with free, lifetime updates. Customers can always download the latest version from their CodeCanyon Downloads Page (must be logged in). We will send out notifications on every major update.

Floors panel

Each map can have unlimited number of floors but it must have at least one. Floors can be reordered by drag&drop.

• Name - name/title of the floor, displayed in the level switcher if there's more than one floor.

• ID (unique) - valid floor ID that is required and cannot be changed later.

• Show by default - check it for the floor you want to be visible when the page loads (in case of multi-floor maps).

• Map - path to map file. Files can be directly uploaded using the WordPress media uploader by clicking on Add button.

• Minimap - (optional) path to minimap file. Files can be directly uploaded using the WordPress media uploader by clicking on Add button.

Styles panel

Styling interactive map elements is now easier than ever using this new feature introduced in Mapplic 6.0. You can define reusable styles and assign them to locations, groups or set them as default style.

Styles are actually CSS rules generated dynamically by the plugin, so please respect the HTML class naming convetions: must begin with a letter and only letters(a-z), digits (0-9), hyphens("-") and underscores ("_") are supported.

There are three location states that can be styled:

• Base - default state of clickable elements

• Hover & Highlight - the element is hovered (mouse over) or highlighted by the search highlight feature.

• Active - the element is focused

Styles can be assinged to locations, groups or the whole map, cascading in this priority order.
Location style attribute will always be applied if set, otherwise the plugin will look for style attribute of groups assigned to the location. Global Default Style will be used as the last option.
Location Style > Group Style > Default Style

This is an optional feature, the old location fill attribute is still supported.

Groups (categories) panel

Each map can have unlimited number of categories, however this feature is optional. Categories can be reordered by drag&drop.

• Name - name/title of the category, displayed in the sidebar if enabled.

• ID (unique) - valid category ID that is required and cannot be changed later.

• About - short text displayed in sidebar.

• Style - style assigned to the group. It will be applied on locations of the group without style attribute set.

• Add to legend - use group in legend (map key).

• Hide from sidebar - exclude group from sidebar list.

• Enable toggle mode - enable toggle mode for the group.

• Switch off by default - toggle off by default, only if toggle enabled.

• Expand by default - check this to have the category expanded by default, leave it unchecked to have it collapsed.

• Color - background color of the category in sidebar.

Location panel

Each map can have unlimited number of locations. After clicking Add, new locations are added to the center of the map, positioning is done by simple drag&drop or lat/lng coordinates if the map is geocalibrated.

• Title - title of the location, visible in the hover tooltip, popups and sidebar.

• ID (unique) - valid, required location ID, used to link SVG shapes with locations. It is also used by the deeplinking feature in the URLs.

• Description - HTML enabled description of the location, displayed in the popup. It can contain links, images, videos or any HTML content.

• Geolocation - only visible if the map is geolocation compatible. You can set the Latitude and Longitude, further (drag&drop) positioning is not required (and ignored).

• Marker type and Color - type of the marker. The first in the list is the hidden pin, use it when a location is linked with an SVG shape. Use the picker to color interactive elements. Most pins (CSS pins) can also be colored using the color picker.

  If the selected pin type supports labels, and additional Label field appears.

• Label - label displayed on the marker. The supported length depends on the size of the pin. It can also be a URL for Image/Icon markers.

• Style - style assinged to the location element.

• Link - URL associated with the location. Popups' More button will link to this address, use the Action attribute to change the default behavior.

• Group - group (category) of the location. Use shift/ctrl/cmd + click to select multiple groups (categories).

• Image - location image, displayed in the tooltip or used with 'image' action.

• Thumbnail - location thumbnail, displayed in sidebar or used with 'pin-image' marker.

• Action - the action to perform when the location is focused, possible options:

  • Default - use the global default action defined on the Settings panel.
  • Tooltip - open the tooltip with More button redirecting Link.
  • Open link - opening Link in the same tab.
  • Open link in new tab - opening Link in new tab.
  • Lightbox - use the lightbox as popup.
  • Image - show 'image' in lightbox
  • External - show details in external div
  • Reveal - zoom and reveal children
  • None - do nothing but zoom to the location.
  • Disabled - no action
  • Select - select multiple locations (experimental)
  
  

• About - short text displayed in sidebar if enabled.

• Hide from sidebar - exclude location from sidebar list.

• Zoom Level - target zoom level when the location is focused.

• Reveal Zoom - reveal location when this zoom level is reached.

Settings panel

List of possible map settings:

• Map container Height - heght of the map container. Requires updating the shortcode.

• Map container Min Height - minimum height of the map container.

• Map container Max Height - maximum height of the map container.

• Map file dimensions - width and height of your map file in pixels. These fields are required!

• Portrait breakpoint - the breakpoint for portrait mode (window width in pixels). Setting it false completely disables portrait mode while true forces it on any screen size. The default value is 668.

• Default action - default action to perform when a location is focused. Locations' Action attribute can override this.

• Default style - default style of interactive elements. Group and Location style can override this.

• Default fill color - default fill color of elements/markers. Group and Location fill colors can override this.

• More button text - change text of the popup's More button.

• Enable fullscreen - enable/disable fullscreen feature.

• Hover tooltip - enable/disable on hover tooltip, showing the title of locations.

• Description in hover tooltip - show/hide location description in hover tooltip.

• Smart tooltip - enable/disable smart tooltip (always visible).

• Deeplinking - enable/disable deeplinking feature (custom URL for each location).

• Open links in new tab - popup links will be opened in new tab by default if checked.

• Enable minimap - enable/disable the minimap.

• Animations - enable/disable map animations.

• Enable zoom - enable/disable zoom and pan feature.

• Maximum zoom level - float value indicating the maximum zoom level. For example, the maximum zoomed map size will be 1200x800 for a file of 600x400 dimensions and level set to '2'.

• Zoom margin - map margin value in pixels when the map is zoomed in (not applied when zoomed all the way out). Set '0' to disable margin.

• Zoom buttons - enable/disable zoom (+/-) buttons.

• Clear button - enable/disable the clear button.

• Zoom out when closing popup - automatically zoom all the way out when a location popup is closed.

• Close popup when zoomed out - automatically close the tooltip when the map is zoomed all the way out.

• Mouse wheel - enable/disable mousewheel zoom support.

• Always fill the container - map fills the container if checked, otherwise the map will fit into the container, as the default behavior.

• Enable sidebar - enable/disable the sidebar.

• Search field - enable/disable sidebar search.

• Search description - make the location description field searchable.

• Minimum keyword length - minimum length of the keyword to trigger search. The default value is '1' so the search will trigger starting the first character.

• Alphabetically ordered list - order locations alphabetically by title.

• Thumbnail placeholder - enable/disable thumbnail placeholder.

• Hide locations when no filter - if checked, sidebar location will be hidden by default and only shown when filter is active (search field or selected group).

• Highlight map on filter - highlight map elements when filter is active (search field or selected group).

• Base color - base color of the UI.

• Primary background - background color of the UI.

• Secondary background - bsecondary background color of the UI.

• Headings color - color of headings.

• Text color - color of regular text.

• Accent color - UI accent color.

• CSV file - upload/link CSV file (CSV Support).

• Load Data - load CSV file content (CSV Support).

• Custom CSS - add custom CSS styles for your map.

Valid IDs

An ID of floor, category or location is valid if:

• unique, no duplicates please,

• starts with a letter (a-z),

• contains only letters (a-z), numbers (0-9), underscore (_) or hyphen (-).

Shortcode

The mapplic shortcode has one required and a few optional attributes. Below you can see an example with all the currently available attributes used:

[mapplic id="125" h="600" landmark="target-id" class="my-custom-map" shortcode="true" csv="true"]

• id

  It's the only required attribute, the map's custom post id, displayed on the map list page

• h

  The container height can be defined using the h attribute three different ways:

  • auto (default) - fixed height calculated automatically by the plugin based on the map file's width/height ratio

  • px - height in pixels, can be used with or without the px suffix, examples: 600, 450px

  • % - percentage of the browser window, examples: 100%, 75%

• landmark

  Landmark mode makes it possible to highligh any location by default. This is extremely useful on single location pages. The above example will be zoomed on the location with ID target-id on page load.

• class

  The class will be simply assigned as HTML class attribute, it can be used for styling and customizing a specific map instance.

• shortcode

  The shortcode attribute has to be true (as seen above) to be able to use shortcodes in popups (location description field).

• csv

  Set true to enable CSV support.

Groups (formerly Categories)

The ability to group locations is a fundamental Mapplic feature.
Groups can be used:

• to filter list items when Sidebar is enabled

• as Legend (map key) items

• to Toggle map a element and/or markers

• to style elements (children will inherit color from parent group if no location color is set)

Assigning multiple groups to a location is possible since Mapplic 5.0. For the full list of group options please visit the options section.

Legend and Toggle

Enabling colored Legend (map key) is possible since Mapplic 5.0. Groups can be used as legend items by simply checking Add to legend on backend. Legend box appears in the bottom left corner of the map container by default.

Toggle can be enabled for Groups by checking Enable toggle mode. A small circular checkbox will appear next to the group name (both sidebar and legend). Toggling this checkbox will result in showing/hiding the map element and/or markers assigned with the Group.

An SVG map element can be linked with a group through the ID field, similar to locations. Let's say you have a g map element named 'group-test' and you create a new Group with ID field set to 'group-test' (case sensitive), your group is assigned to the map element and toggle can be used.

The Switch off by default option can be used to toggle OFF a group by default. Read more about options.

Reveal

Map elements and markers can be revealed based on active parent location or zoom level:

• Active Parent

  When a location with 'Reveal' action attribute is focused, all of its children locations are shown. A location is child of another if the ID field starts with the parent ID followed by a '-' sign (case sensitive). The child locations are hidden again on zoom reset (zoomed all the way out).

  Australia is an interactive world map location with ID au and action set to 'Reveal'. Sydney and Melbourne are two children locations because the following IDs are used: au-sydney and au-melbourne.

• Zoom Level

  You can also reveal locations when zoom is performed. This is extremely useful if there's a large number of markers, to avoid overcrowded maps. Simply use 'Reveal Zoom' attribute to set reveal zoom level for any location.

  On a map, with maxscale set to '4' (4x map file zoom), secondary locations have 'Reveal Zoom' attribute set to '2'. These location markers are not visible by default, only when map zoom level reaches 2 (2x map file zoom).

Toggle and Reveal should not be used simultaneously for the same elements.

External

You can display location details (title, description) anywhere on your site using the external action (since Mapplic 6.0). Make sure the external site element (div) has class="mapplic-external" and set location action to External.

Initial zoom level and position

You can set initial zoom level and position by creating a new location with ID: init

If the location init exists, the plugin will always be focused on its position and zoom level on page load. Simply remove the location to disable the feature.

Geolocation

Feature introduced in Mapplic version 4.0, allows using real latitude and longitude coordinates for positioning locations. It only works with geocalibrated svg maps (like the netherlands example).

A map is geolocation compatible if:

• Borders of the map file (bottom latitude, left longitude, top latitude and right longitude) are defined in the Geoposition panel.

• The projection of the map is Web Mercator (EPSG:3857), also called Google Web Mercator or WGS 84/Pseudo-Mercator, which is the standard projection for maps on the web.

If the above requirements are met, you can use the Geolocation location attributes to poistion a location. You can easily get the lat/lng coordinates of a place using right-click, "What's here" on Google Maps.

Geocalibrating a map is an advanced task task, it requires GIS skills and it's beyond the scope of this documentation.

CSV Support

Spreadsheets are awesome, probably the most natural way of digital data storage and organization. CSVs (comma-separated values) are basic and powerful. A new feature introduced in version 5.0 allows linking location data spreadsheets to your Mapplic map.

Working with large datasets or bulk loading locations? Not a problem anymore!

Microsoft Excel, Google Sheets, Apple Numbers or any spreadsheed software can be used to create/edit the spreadsheet (.csv format), which is linked to your map, preprocessed and directly used by the plugin.

Usage

Create a simple .csv file using your favorite spreadsheet program.
The first row (header row) must contain the location attribute names, like id, title, description, x, y etc. (order doesn't matter). If the map has multiple floors, create an additional level column with the floor IDs.

See the full list of location attributes (for header row).

Upload and linking this spreadsheet file to the map using the csv setting.

Loading data

You can also load the data of the linked CSV file (version 6.1), converting it to standard, editable Mapplic locations.

Click the Load Data button to fetch CSV data (overwriting existing locations) and clear the Link CSV file field.

CSV Support only only works if csv="true" shortcode attribute is applied to your map instance.

Custom pins

Mapplic comes with a few built-in pins, however you can easily add your own pin types, as many as you want.

1. Open wp-content/plugins/mapplic/core/mapplic.css file and find the selector .mapplic-pin.my-new-pin. Duplicate it and replace 'my-new-pin' with the name of your pin, customize the attributes (background-image, width, height, margin-top, margin-left).

   /* CUSTOM PINS */
   .mapplic-pin.my-new-pin {
   	background-image: url(../images/my-new-pin.png);
   	background-size: 20px 30px;
   	width: 20px;
   	height: 30px;
   	margin-top: -15px;
   	margin-left: -10px;
   }

   Negative margins are used for defining the pin's origin.

   
   

2. Now you have to register the new custom pin types to appear on Mapplic backend. The following code has to be called somewhere in the project, preferably in your theme's functions.php to make the changes future proof.

   /* Mapplic Custom Pins */
   function mapplic_extend_pins($pins) {
   	// New pin types
   	$custom = array('my-new-pin', 'my-new-pin2');
   	
   	// Merging arrays
   	$pins = array_merge($pins, $custom);
   
   	return $pins;
   }
   add_filter('mapplic_pins', 'mapplic_extend_pins');
   

Right sidebar

The sidebar is on the left side by default. Simply add the .mapplic-sidebar-right class to your map div to move it to the right side.

<div id="mapplic" class="mapplic-sidebar-right"></div>

Resizing the Sidebar

By default, the sidebar takes up 30% of the available width. Make sure the sum of container and sidebar width is equal to 100%!

/* a narrower sidebar */
.mapplic-sidebar {
	width: 25%;
}

.mapplic-container {
	width: 75%;	
}

Resizing the Minimap

By default, the minimap has a width of 140 pixels. To resize it, we have to alter the width, the height will be adjusted automatically maintaining the aspect ratio. It can be resized using the following style:

.mapplic-minimap {
	width: 200px;	
}

Relocating Components

You might want to relocate the UI elements over the map (minimap, level switcher, clear button, fullscreen button, zoom buttons). Use the top/right/bottom/left attributes to move them. For example, if we wanted to move the level switcher to the top-left corner:

.mapplic-levels {
	top: 0;
	left: 0;	
}

Events

Events can be bound to initialized Mapplic instances. List of public events currently available:

• mapstart - the map has started loading

• mapready - the maps is fully loaded

• svgloaded - an svg map file is loaded (triggered for each floor)

• locationopened - a location is focused

• locationclosed - a location is closed

• levelswitched - the active level is switched

• positionchanged - map movement performed (zoom or pan)

$(document).ready(function() {
	// #mapplic-id12 selector saved in map variable
	var map = $('#mapplic-id12');

	// EXAMPLES
	// Map ready
	map.on('mapready', function(e, self) {
		console.log('Map is ready!')
		// self grants direct access to the map object,
		// be focused on the washing machine by default
		self.moveTo(0.67, 0.62, 3, 0);
	});

	map.on('svgloaded', function(e, svg, id) {
		// svg element and floor id returned
	});

	// Location opened
	map.on('locationopened', function(e, location) {
		// location grants full access to the location
		console.log(location.title + ' opened.');
	});

	// Location closed
	map.on('locationclosed', function(e) {
		console.log('Location closed.');
	});

	// Level switched
	map.on('levelswitched', function(e, level) {
		console.log('Switched to ' + level + ' level.');
	});

	// Position changed
	map.on('positionchanged', function(e, self) {
		// self grants direct access to the map object
		console.log('Pan/zoom, current scale: ' + self.scale);
	});
});

Methods

Metods are public function performing basic tasks. You can call them using the map object which can be accessed by calling .data('mapplic') on the selector. The map object also grants access to components and other variables. Currently supported public methods are:

• switchLevel(target) - switch to level with ID target

• moveTo(x, y, s, d) - move to position x, y on scale s in d milliseconds

• getLocationData(id) - get the data object of location

• showLocation(id, d) - focus to location in d milliseconds

• hideLocation() - close currently active location

• updateLocation(id) - update location on the map

$(document).ready(function() {
	// #mapplic-id12 selector saved in map variable
	var map = $('#mapplic-id12');

	// Access to map object from selector
	var self = map.data('mapplic');

	// EXAMPLE 1
	// Showing visitor's geolocation
	map.on('mapready', function(e, self) {
		// Update location with geoposition
		if (navigator.geolocation) {
			navigator.geolocation.getCurrentPosition(function(pos) {
				var location = self.getLocationData('pos');
				location.lat = pos.coords.latitude;
				location.lng = pos.coords.longitude;
				self.updateLocation('pos');
			});
		}
		else console.log('Geolocation not enabled.');
	});

	// EXAMPLE 2
	// Switch level from external button
	$(document).on('click', '#goto-level1-button', function(e) {
		e.preventDefault();
		self.switchLevel('level1');
	});
});

Filters

The mapplic_location filter, presented in Mapplic 5.0, allows modifying location data before page load. It loops through all locations and allows syncronizing the map with external data, like WordPress posts or WooCommerce products.

Server side (PHP) programming skills are required. For future-proof customization, add the code to your (child) theme's functions.php file.

The shortcode="true" attribute is required to use filters.

The below code snippet looks for locations with ID of form p[PID], where PID is a WordPress post ID. For example, in case of location with ID p125 the title and description will be overwritten with title and content of post 125.

function mapplic_link_post($location) {
	if (strtolower(substr($location->id, 0, 1)) == 'p' &&
	    is_numeric(substr($location->id, 1))) {
		$post = get_post((int) substr($location->id, 1));
		if ($post) {
			$location->title = $post->post_title;
			$location->description = $post->post_content;
		}
	}
	return $location;
}
add_filter('mapplic_location', 'mapplic_link_post');

This example links Mapplic locations and WooCommerce products through location ID and product slug. If the product is in stock, the fill color will be green and link to product page will be added to the description. In case it's out of stock, the color will be red and the description set to 'Unavailable'.

function mapplic_link_product($location) {
	$product = get_page_by_path($location->id, OBJECT, 'product');
	if (!empty($product)) {
		$product = wc_get_product($product);
		$stock = $product->get_stock_quantity();
		if ($stock > 0) {
			$location->fill = '#A9E190';
			$location->description = $product->description . '<br><a class="mapplic-popup-link" href="' . get_permalink($product->id) . '">Book Now</a>';
		}
		else {
			$location->fill = '#F79F79';
			$location->description = 'Unavailable';
		}
	}
	return $location;
}
add_filter('mapplic_location', 'mapplic_link_product');

Used libraries

• jQuery Library

• jQuery Mouse Wheel Plugin - mousewheel

• Magnific Popup - lightbox

• Papa Parser - CSV parsing