Documentation

Installation

Installing the WordPress Version

  1. Download the plugin from CodeCanyon.

    Visit CodeCanyon, then go to your Downloads page. Find “Image Map Pro for WordPress”, press Download and then select “Installable WordPress file only”.

  2. Upload it to your WordPress website.

    Open your WordPress dashboard. From the menu on the left click Plugins -> Add New. Finally click the “Upload Plugin” button and choose the ZIP file that you downloaded in step 1.

  3. You are all done!

Installing the Standalone Version

  1. Download the plugin from CodeCanyon.

    Visit CodeCanyon, then go to your Downloads page. Find “Image Map Pro for jQuery”, press Download and then select “All Files & Documentation”.

  2. Extract the zip package that you downloaded and copy the editor folder to any location on your computer or a server. IMPORTANT: The editor can save your image maps in the browser using HTML5 Local Storage, which is URL dependant. This means that if you move the editor folder, your saves will be gone. If you move back the editor folder to its old location, the saves will still be there.
  3. Done! You can start using the Editor now by launching editor.html from the editor folder.

First Steps

Take the Guided Tour

When you first launch the Image Map Pro Editor you will see a Guided Tour that will take you through the basics of using the editor. It’s the easiest way to get started quickly with the plugin and we highly recommend you to check it out!

To see the Guided Tour again, click the “Help” button located at the top of the editor.

Activation (WordPress Only)

By choosing to activate the plugin you will gain access to automatic updates, and that is all. There is no restricted functionality, no annoying pop-ups if you choose not to activate!

To activate the plugin, first you will need your Purchase Code. Here is a step by step guide of where to find it. When you have your Purchase Code, launch the Image Map Pro Editor and click Activate in the top-left of the screen. Paste the code and enjoy lifetime automatic updates!

Working with the Editor

Creating a New Image Map

To create a new image map, click the New button in the top-left corner of the Editor, enter a name and click Create.

A white background image will be loaded by default. To change it, click the button Settings. It will be shown a left menu, in it choose section Image. Then simply enter the URL of the new image, or click Choose Image if you are using WordPress, to launch the WP Media Library and pick an image.

Responsive

The image map is responsive! If you enable the Responsive toggle, the image map will scale to 100% width of its parent element. Additionally, the Preserve Quality toggle (enabled by default) prevents the image from becoming larger than its original size (in pixels), preventing loss of quality.

Drawing Shapes, Icons and Text

To start drawing shapes, first, make sure that you are in Edit mode. (please, read below about Edit and Preview mode). Then, select a tool from the toolbar on the left and either click or click and drag the image, depending on the tool that you selected.

Keep in mind, that if you choose to draw a polygon shape to finish the drawing you have to click on the first point from where you started drawing (or press Enter). Then it will be possible to add, remove and move points from the shape. You can remove points using the right mouse button on a point, and add points using the left mouse button on one of the borders of the polygon.

To insert icons you can use the Icon tool. Then, you should click on the image where you want to insert the icon. Keep in mind, that you can change the type of the icon by using the Icons Library integrated into the editor or set a custom icon by setting a specific URL. It can be done from the section Icon in the right menu of the editor.

To insert text you should use the Text tool and click on the image where you want to insert the text. You can edit the text and choose its font from the section Text in the right menu.

Styles

To change the style of a shape, like color or opacity, first make sure that the shape is selected. You can select a shape by clicking it in the shapes list (on the right), or by clicking it in Edit Mode. Then, you can see the settings for Default Style and Mouseover Style in the right menu. Experiment with different settings and use what you like!

Preview Mode

At any point you can click the Preview button on the top-left side of the Editor to see how the image will look like in the end. You can still make changes to the settings and the preview will instantly update itself.

Save, Load

Don’t forget to save! You can create as many image maps as you wish, and you can switch between them by clicking Load and choosing the image map that you saved previously.

Import, Export

With the Import and Export buttons from the Editor you can migrate your image maps to another website, or make backups to your image maps. You know, just in case. Moreover, if you can work your way around the JSON code, you can make modifications to the image map.

Introduced in version 4.3 is the ability to import any SVG file to the image map. For example, you might already have an illustrator file with schematics, which you don’t want to rebuild from scratch. Now you can import those shapes in Image Map Pro as SVG. Just make sure that you select “SVG XML Code” in the Import options and follow the instructions.

Keep in mind, that using Import and Export buttons you can duplicate your image maps. Firstly, you have to create a new image map from the New button. After that, you can export and import (into the new project) the JSON code of the image map which you want to duplicate.

Connected Shapes

It is possible to have multiple shapes linked together. For example, when you mouseover one shape, several other shapes around it will highlight as well. The way this is done is by defining a “master” shape, and “slave” shapes, which are connected to it. Select each of the shapes that you wish to be “slaves”, and using the drop-down menu Parent (located the General settings of the right menu) select the shape which you wish to be their “master”. Do this for each shape and you are done!

Additionally, you can choose to have only one tooltip for each group of connected shapes. Select each of the “slave” shapes and enable “Use Connected Shape’s Tooltip”.

Glowing and Animation

You can set animation of visualizing and glowing effect so that the shapes to be stand out. It can be accomplished using the options in the section Shapes located in the left menu which can be shown clicking the button Settings. There you will see 2 main options:

  1. Page Load Animation – from that drop-down menu you can choose an animation of visualizing of the all shapes and icons when the image map is initialized.
  2. Glowing Shapes – by activating of that option you will set glowing effect for all shapes and icons in the image map. You can set specific Glow Color and Glow Opacity. If the Glowing on Mouseover is active the glowing effect will stop for all shapes and icons when you mouseover only one of them.

Shapes Menu

If you enable Shapes Menu (in the section Shapes located in the left menu which can be shown clicking the button Settings), a shape menu (list of the shapes) will be created. You can set where exactly that menu to be visualized – you can choose between Left and Right position according to your image map or it to be visualized separately from the image map, as Detached Menu. Moreover, you can set whether in the menu to have Search Box and whether the shapes to be grouped by existing Floors (please, read below about Multiple Floors). Additionally, if the option Hide Children of Connected Shapes is active and if in your image map there are connected shapes (please, read more above about Connected Shapes), these shapes which are defined as “slaves” will not be included in the menu.

Multiple Floors

To have an image map made of more than one layers (or floors), go to the Floors section of the image map settings and click Enable Floors. For each one of these floors/layers, you can set a different background image and annotate them using shapes, icons and tooltips. When that feature is activated, a menu for switching between floors will be inserted automatically in the top-right corner of the image map, both in Edit and in Preview modes.

Here's how to work with Floors in the Editor:

  1. Add a floor – by using the plus (+) button
  2. Remove a floor – by using the minus (–) button
  3. Duplicate existing floors – by selecting the floor which you want to duplicate and use the button Duplicate located below the list of existing floors
  4. Move Up and Move Down the floors – you can change the order of the existing floors
  5. By using the button Edit, you can rename a floor and change its background image.

Zooming

In version 4.3 we added zoom functionality to the plugin. Now you can have much more complex and precise image maps on your website and visitors with all kinds of screen sizes will be able to use them. The plugin also supports intuitive pinch zoom/pan on touchscreen devices!

To get started, from the editor open the Zooming tab, which is in the image map settings tab. From there you have several different options:

  1. Max Zoom - the maximum level of zoom allowed.
  2. Limit Max Zoom - if enabled, the zooming can only go up to the original image size.
  3. Enable Navigator - shows a mini image on the bottom left of the image map, giving you an idea of where you are on the image map while zooming and panning around.
  4. Enable Zoom Buttons - adds + / - buttons on the bottom right side of the image map, allowing you to click to zoom in/out. Useful if you want to make it more obvious that there is zooming.
  5. Zoom Button/Background Color - change the style of the zoom buttons to match the design of your website.
  6. Hold CTRL to Zoom – if it is active, it will be required to press the CTRL (or CMD on MacOS) button from the keyboard so that the image map can be zoomed without scrolling the page.

Fullscreen

You can choose to enable fullscreen mode for those extra large and detailed image maps. To get started, open the Fullscreen tab in the image map settings tab. From there you have several different options:

  1. Start in Fullscreen Mode - If enabled, the image map will go straight into fullscreen mode when the page loads. Be careful!
  2. Fullscreen Background - The color of the “empty” space around the image in fullscreen mode.
  3. Fullscreen Button Position - You can choose to move the fullscreen button to a different location on the image map, if you feel like it’s obstructing information.
  4. Button Type - Icon/Text/Icon and Text - Choose whatever you feel is appropriate! Functionality is the same.
  5. Button Colors - Change the style of the button to match the design of your website.
  6. Button Icon/Text Color - Change the style of the text in the button to match the design of your website.

Publishing Your Image Map

WordPress

There are a couple of ways to publish your image map:

  • Gutenberg - Image Map Pro integrates seamlessly with the new Gutenberg post editor. You can insert an "Image Map Pro" element and select your image map from the dropdown menu on the element itself.
  • Shortcode - You can insert the image map into a WordPress page or a post using a shortcode, which you can copy or change from the Editor: click the button Settings, go to the section General in the left menu and you will see the Shortcode field there. For example, if you enter my-image-map as a name of your image map or directly as a shortcode, you can insert the image map with [my-image-map] in plain text. IMPORTANT: Please keep in mind that the shortcode must be entered without brackets and must not contain any spaces or special characters.

Standalone

Inserting the finished image map on your site is straightforward. From the Editor, press the Code button:

A window will open, showing you a sample HTML page. On this page you can see which scripts need to be included and where exactly. Moreover, you could see the exemplary demo placed in the package which you have downloaded from CodeCanyon.

Here is a list of the files and scripts that you must include on your website:

  1. CSS File - included in the <head> tag, like this:
    <link rel="stylesheet" href="css/image-map-pro.min.css">
  2. Container Element - place it anywhere in your document, where you wish the image map to appear.
    <div id="image-map-pro-container"></div>
  3. jQuery - there are many ways to include jQuery on your page. The easiest would be to copy-paste this line, just before the closing </body> tag of your page:
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script>
  4. JS File - this is Image Map Pro’s own javascript file. Include it immediately after jQuery:
    <script src="js/image-map-pro.min.js"></script>
  5. Launch Code - the code which actually launches the image map. You have two options:
    • Option 1 - Insert the code at the bottom of the HTML page. Paste the code like this, after the included JS files:
      <script type="text/javascript">
          ;(function ($, window, document, undefined) {
              $(document).ready(function() {
                  // Code from the textarea goes here...
              });
          })(jQuery, window, document);
      </script>
      
    • Option 2 - Insert the code in an external JS file. In this case you paste the same code in your JS file, except for the <script> tag, like this:
      ;(function ($, window, document, undefined) {
          $(document).ready(function() {
              // Code from the textarea goes here...
          });
      })(jQuery, window, document);
      

API

Intro

Adding custom functionality is super easy, using the Image Map Pro’s API. However, you will need to know a bit of JavaScript/jQuery (or just HTML if you need only basic functionality) to put something together. This documentation will give you a solid start on the API, but you will need to write some code by yourself.

Simple HTML API Example

Let’s say that we want to have a list of buttons next to our image map, and we want to highlight different shapes when mousing over each button.

The simplest way to accomplish this would be to use the HTML API:

<div data-imp-trigger-shape-on-mouseover="my-shape-1">My Shape 1</div>

With the data-imp-trigger-shape-on-mouseover HTML attribute we are telling the plugin to highlight my-shape-1 and to open its tooltip. If you want only to highlight or only open the tooltip, there are different HTML attributes for that. Please check the API Reference section for a full list.

If you have more than one image map on the same page, you will need to add the data-imp-image-map-name attribute to specify on which image map you want to make a change:

<div data-imp-open-tooltip-on-click="my-shape-1" data-imp-image-map-name="My Image Map">My Shape 1</div>

In this example we are opening the tooltip for the my-shape-1 shape on click, in an image map named My Image Map.

Simple JavaScript API Example 1

The API provides you with several different functions, which you can use to trigger events on the image map and to listen for events.

Let’s say that we want to achieve some really awesome mouseover effects and we want to replace the entire image when a user points at a specific shape. Because why not.

$.imageMapProEventHighlightedShape = function(imageMapName, shapeName) {
    console.log(shapeName);
}

The hook function that we want to use in this case is $.imageMapProEventHighlightedShape. Whenever a mouseover event occurs on a shape, this function is called. It provides us with two variables - imageMapName and shapeName, which we can check to see which shape was highlighted and on which image map. In the example above we are simply logging the value of shapeName to the console.

$.imageMapProEventHighlightedShape = function(imageMapName, shapeName) {
    // Check which shape has been highlighted
    if (shapeName == 'shape') {
        // This piece of code will execute only when "shape" has been highlighted.
        // For the purposes of this example, we replace our image with a new one.
        $('#image-map-pro-1718 .imp-main-image').attr('src', 'img/image-2.png');

        // Regarding the selector “#image-map-pro-1718” you have to replace the “1718” with the ID of your image map. You can see the ID by clicking the “Export” button located at the top of the editor.
    }
}

Of course, we will want to go back to the original image when the user moves the mouse away from shape. In this case we need to use the $.imageMapProEventHighlightedShape hook function, which works exactly the same.

For the full list of functions, please see the API Reference section below.

Also, as a good practice we should “enclose” our code, using this boilerplate snippet:

(function($, window, document, undefined) {
    $(document).ready(function() {
        // Your code goes here...
    });
})(jQuery, window, document);

This is just a bonus tip and you should be doing it to all your scripts. It’s not specific to this plugin.

Finally, here is how the entire code would look like:

(function($, window, document, undefined) {
    $(document).ready(function() {
        // When the user triggers a mouseover event on a shape (or "highlights" a shape), we want to replace the main image with a new one
        $.imageMapProEventHighlightedShape = function(imageMapName, shapeName) {

            // Check which shape has been highlighted
            if (shapeName == 'shape') {

                // This piece of code will execute only when "shape" has been highlighted.
                // For the purposes of this example, we replace our image with a new one.
                $('#image-map-pro-1718 .imp-main-image').attr('src', 'img/image-2.png');

                // Regarding the selector “#image-map-pro-1718” you have to replace the “1718” with the ID of your image map. You can see the ID by clicking the “Export” button located at the top of the editor.
            }
        }

        // When the mouse moves away from the shape, revert back to the original image
        $.imageMapProEventUnhighlightedShape = function(imageMapName, shapeName) {

            // Check which shape has been unhighlighted
            if (shapeName == 'shape') {

                // Revert back to the original image
                $('#image-map-pro-1718 .imp-main-image').attr('src', 'img/image-1.jpg');
            }
        }
    });
})(jQuery, window, document);

You have many different options where to put this block of code. If you are using the WordPress version, you can insert it via the editor of the plugin by using the section Custom Code (using the field Custom JS) located in the image map settings. Moreover, you can paste it at the bottom of image-map-pro.js, or just slap it in a <script> tag on the page itself (this way is recommended if you use the Standalone version).

Simple JavaScript API Example 2

In the previous example we used Hooks. Meaning that we were waiting for something to happen, and the plugin called the hook functions for us when that thing happened. In this example we want to make something happen, and for that we need to use Actions.

Let’s say that we want to have a list of buttons next to our image map, and we want to highlight different shapes when mousing over each button.

$.imageMapProHighlightShape('My Image Map', 'my-shape-1');

In this example we are telling the plugin to highlight shape with name my-shape-1 on an image map with name My Image Map. Here is how we would use this in an example:

(function($, window, document, undefined) {
    $(document).ready(function() {
        // Add an event listener to all of our buttons
        $('.button-list .button').on('mouseover', function(e) {
            // When the event is triggered, find out the ID of the button, which triggered the event
            if ($(this).attr('id') == 'button-1') {

                // Highlight our shape corresponding to the button
                $.imageMapProHighlightShape('My Image Map', 'building-1');

                // Unhighlight the rest of the shapes
                $.imageMapProUnhighlightShape('My Image Map', 'building-2');
                $.imageMapProUnhighlightShape('My Image Map', 'building-3');
            }

            // Repeat 2 more times...
            if ($(this).attr('id') == 'button-2') {
                $.imageMapProHighlightShape('My Image Map', 'building-2');

                $.imageMapProUnhighlightShape('My Image Map', 'building-1');
                $.imageMapProUnhighlightShape('My Image Map', 'building-3');
            }
            if ($(this).attr('id') == 'button-3') {
                $.imageMapProHighlightShape('My Image Map', 'building-3');

                $.imageMapProUnhighlightShape('My Image Map', 'building-1');
                $.imageMapProUnhighlightShape('My Image Map', 'building-2');
            }
        });

        // Unhighlight all shapes if the mouse moves away from the buttons
        $('.button-list').on('mouseout', function(e) {
            $.imageMapProUnhighlightShape('My Image Map', 'building-1');
            $.imageMapProUnhighlightShape('My Image Map', 'building-2');
            $.imageMapProUnhighlightShape('My Image Map', 'building-3');
        });
    });
})(jQuery, window, document);

And here is the HTML snippet:

<div class="button-list">
    <div id="button-1" class="button">Day1</div>
    <div id="button-2" class="button">Day2</div>
    <div id="button-3" class="button">Day2</div>
</div>

API Reference

HTML

This is a list of all HTML attributes provided by the plugin. For an example of how can you use them, please see the Custom Functionality with the Image Map Pro API section. Note - when you highlight a shape with the API, you can unhighlight it only by using the API. The same applies for opening tooltips. An exception to this rule is when you use the “mouseover” triggers from the HTML API.

Attribute Description
data‑imp‑image‑map‑name Specifies on which image map you want to trigger the action. This is required if you have more than one image map on the same page. If you have just one, you don’t need to use it.
data‑imp‑highlight‑shape‑on‑mouseover When a user triggers a mouseover event on this element, the plugin will highlight a shape. The value of the attribute represents the name of the shape.
data‑imp‑highlight‑shape‑on‑click When a user clicks on this element, the plugin will highlight a shape. The value of the attribute represents the name of the shape.
data‑imp‑unhighlight‑shape‑on‑mouseover When a user triggers a mouseover event on this element, the plugin will remove the highlight effect from a shape. The value of the attribute represents the name of the shape.
data‑imp‑unhighlight‑shape‑on‑click When a user clicks on this element, the plugin will remove the highlight effect from a shape. The value of the attribute represents the name of the shape.
data‑imp‑open‑tooltip‑on‑mouseover When a user triggers a mouseover event on this element, the plugin will open the shape’s tooltip. The value of the attribute represents the name of the shape.
data‑imp‑open‑tooltip‑on‑click When a user clicks on this element, the plugin will open the shape’s tooltip. The value of the attribute represents the name of the shape.
data‑imp‑close‑tooltip‑on‑mouseover When a user triggers a mouseover event on this element, the plugin will close the shape’s tooltip. The value of the attribute represents the name of the shape.
data‑imp‑close‑tooltip‑on‑click When a user clicks on this element, the plugin will close the shape’s tooltip. The value of the attribute represents the name of the shape.
data‑imp‑trigger‑shape‑on‑mouseover When a user triggers a mouseover event on this element, the plugin will highlight a shape and show its tooltip. The value of the attribute represents the name of the shape.
data‑imp‑trigger‑shape‑on‑click When a user clicks on this element, the plugin will highlight a shape and show its tooltip. The value of the attribute represents the name of the shape.
data‑imp‑untrigger‑shape‑on‑mouseover When a user triggers a mouseover event on this element, the plugin will remove the highlight effect from a shape and hide its tooltip. The value of the attribute represents the name of the shape.
data‑imp‑untrigger‑shape‑on‑click When a user clicks on this element, the plugin will remove the highlight effect from a shape and hide its tooltip. The value of the attribute represents the name of the shape.
data‑imp‑focus‑shape‑on‑mouseover When a user triggers a mouseover event on this element and zooming is enabled, the plugin will zoom and pan to try to fit the shape in the window.
data‑imp‑focus‑shape‑on‑click When a user clicks on this element and zooming is enabled, the plugin will zoom and pan to try to fit the shape in the window.
data‑imp‑go‑to‑floor When a user clicks on this element, the currently active floor is changed. The value of the attribute represents the name of the floor, which will become active.

JavaScript Actions

Actions are when you call a function and something happens on the image map. For example if you want to open a tooltip or highlight a shape, you need to use an Action. Note - when you highlight a shape with the API, you can unhighlight it only by using the API. The same applies for opening tooltips.

Action Name Description
$.imageMapProHighlightShape(imageMapName, shapeTitle); Highlight a shape with a title of shapeTitle on an image map with a name imageMapName.
$.imageMapProUnhighlightShape(imageMapName, shapeTitle); Remove the highlight effect from a shape with a title of shapeTitle on an image map with a name imageMapName.
$.imageMapProFocusShape(imageMapName, shapeTitle); If zooming is enabled, try to zoom and pan on the shape with a title of shapeTitle on an image map with a name imageMapName.
$.imageMapProOpenTooltip(imageMapName, shapeTitle); Open the tooltip for a shape with a title of shapeTitle on an image map with a name imageMapName.
$.imageMapProHideTooltip(imageMapName, shapeTitle); Close the tooltip for a shape with a title of shapeTitle on an image map with a name imageMapName.
$.imageMapProReInitMap(imageMapName); Manually reinitialize an image map.
$.imageMapProIsMobile(); Returns true if the user is using a mobile browser, or false if he is not. This is the same check that the plugin does in order to determine it fullscreen tooltips are necessary. This action is useful if you want to make adjustments to the contents of the tooltips, or anything else when the user is on a mobile device.
$.imageMapProZoomIn(imageMapName, floorName); Zoom in on an image map with a name imageMapName.
$.imageMapProZoomOut(imageMapName, floorName); Zoom out on an image map with a name imageMapName.

JavaScript Hooks

Hooks are functions which get called when something specific happens on an image map. For example - you want to know when a user has highlighted a specific shape.

Hook Name Description
$.imageMapProInitialized = function(imageMapName) {} Called when an image map with a name imageMapName has finished initializing.
$.imageMapProEventHighlightedShape = function(imageMapName, shapeTitle) {} Called when a shape has been highlighted. Parameters include the name of the shape, and the name of the image map.
$.imageMapProEventUnhighlightedShape = function(imageMapName, shapeTitle) {} Called when a shape has been unhighlighted. Parameters include the name of the shape, and the name of the image map.
$.imageMapProEventClickedShape = function(imageMapName, shapeTitle) {} Called when a shape has been clicked. Parameters include the name of the shape, and the name of the image map.
$.imageMapProEventOpenedTooltip = function(imageMapName, shapeTitle) {} Called when a tooltip has been opened. Parameters include the name of the shape, and the name of the image map.
$.imageMapProEventClosedTooltip = function(imageMapName, shapeTitle) {} Called when a tooltip has been closed. Parameters include the name of the shape, and the name of the image map.
$.imageMapProEventSwitchedFloor = function(imageMapName, floorName) {} Called when the image map has changed the currently active floor.