API

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.

Example 1: HTML API

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

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

    
<div data-imp-trigger-object-on-mouseover="my-object-1">
  Button
</div>
  

With the data-imp-trigger-object-on-mouseover HTML attribute we are telling the plugin to highlight my-object-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 interactive image on the same page, you will need to add the data-imp-image-map-name attribute to specify on which image you want to make a change:

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

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

Example 2: JavaScript API Hooks

The API provides you with several different functions, which you can use to trigger events on the interactive image 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 object. In this scenario we want to subscribe to the script's objectHighlight event:

    
ImageMapPro.subscribe((action) => {
  if (action.type === 'objectHighlight') {
    // Do something
  }
})
  

With this snippet of code, every time a user highlights an object we receive an action object, containing the received action type and other useful information. The format of the action object is as follows:

    
{
  type: 'objectHighlight',
  payload: {
    object: 'my-object-1',
    map: 'My Image',

    // Only for the 'artboardChange' event
    artboard: 'artboard-1'
  }
}
  

In this example we want to replace the image's src attribute, whenever the user highlights the object my-object-1:

    
ImageMapPro.subscribe((action) => {
  if (action.type === 'objectHighlight' && action.payload.object === 'my-object-1') {
    document.querySelector('#our-image-container .imp-image').src = 'path-to/image.jpg'
  }
})
  

We also want to go back to the original image when the user moves the mouse away from my-object-1. For this purpose we will listen to the objectUnhighlight action:

    
ImageMapPro.subscribe((action) => {
  if (action.type === 'objectHighlight' && action.payload.object === 'my-object-1') {
    document.querySelector('#our-image-container .imp-image').src = 'path-to-new-image/image.jpg'
  }
  
  if (action.type === 'objectUnhighlight' && action.payload.object === 'my-object-1') {
    document.querySelector('#our-image-container .imp-image').src = 'path-to-original-image/image.jpg'
  }
})
  

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 located in the Settings. Moreover, you can paste it at the bottom of image-map-pro.js, or just place it in a <script> tag on the page itself (this way is recommended if you use the Standalone version).

Example 3: JavaScript API Functions

In the previous example we used Hooks. Meaning that we were waiting for something to happen, and the script 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 Functions.

Let's say that we want to have a couple of buttons next to our image and clicking a button should change the currently active artboard of the interactive image.

    
<div id="floor-1">Go to floor 1</div>
<div id="floor-2">Go to floor 2</div>
  

    
document.querySelector('#floor-1').addEventListener('click', () => {
  ImageMapPro.changeArtboard('My Floor Plan', 'artboard-1')
})

document.querySelector('#floor-2').addEventListener('click', () => {
  ImageMapPro.changeArtboard('My Floor Plan', 'artboard-2')
})
  

In the example code above, the name of our image is My Floor Plan, which is specified from the Settings in the Editor. The artboards are called artboard-1 and artboard-2, which is specified by selecting an artboard in the Editor and changing the title on the right.