Developers: EngageBox Javascript API 2.0

Learn more about the EngageBox Javascript API 2.0, which no longer depends on jQuery as it is re-written in vanilla Javascript. Available since EngageBox v4.0.

• The EngageBox Instance
• Properties
• Methods
• Static Methods
• Events
• Triggers
• User Cases & Examples

The EngageBox Instance

In this section, you will learn how to retrieve an EngageBox instance and what are the available methods to use so you can manipulate it.

Retrieving the EngageBox instance

Here are some examples of how you can retrieve an EngageBox instance.

If you know the box's ID, use the getInstance() built-in method:

const box = EngageBox.getInstance(ID);

You can get an instance using DOM querySelector() method.

const box = document.querySelector('.myBoxClass').engagebox;

You can also find an instance in the instances collection using the getInstances() built-in method.

const boxes = EngageBox.getInstances()[0];

If you cannot access a box instance, it's very likely the instance is not loaded yet. In that case, you should ensure EngageBox has finished loading all instances first.

EngageBox.onReady(function() {
    const box = EngageBox.getInstance(ID);
    // the rest of your code here
});

To access the DOM element representing the box, use the el instance property.

const boxEl = EngageBox.getInstance(ID).el;

Properties

You can access the following properties once you've got the instance in, say box.

options

The configuration object (defaults + user-specified options).

To get the value of an option, use the syntax below:

let foo = box.options.trigger;

You can also set the value of an option by using the following syntax. The example below modifies the delay option so the box will be displayed with a 2 seconds delay.

box.options.delay = 2000;

opened

Indicates whether the box is opened or not.

if (box.opened) {
	// do something
}

Methods

Once you've got the instance in, say box, you can use the following methods to manipulate the box.

open()

Opens the box

box.open();

close()

Closes the box

box.close();

toggle()

Shows/opens the box if it's closed, hides/closes it otherwise.

box.toggle();

bindTrigger(name, options)

Bind a Trigger after the box has been initialized. This is rather useful when you want to attach an extra Trigger beyond the one set in the initialization. To view the available Triggers and their options, visit the Triggers section.

box.bindTrigger("onExit", options);

destroy();

Destroys the EngageBox instance by removing event listeners and DOM elements.

box.destroy();

Static Methods

EngageBox exposes the following methods, which don’t require an instance to work.

getInstance(ID)

Get a box instance by ID.

const box = EngageBox.getInstance(2);

getInstances()

Get all box instances. This is rather useful when you want to loop through all initialized boxes.

const boxes = EngageBox.getInstances();

closeAll()

Closes all opened boxes.

EngageBox.closeAll();

getTotalOpened()

Returns the number of opened boxes.

const total = EngageBox.getTotalOpened();

Events

EngageBox fires events for the most common and useful actions. For each event, you may specify a single function. To hook into an event, you use the on() method. Below you can find the list with the events triggered in sequence order.

beforeOpen

This event gets fired before the box is opened. You can use this event to prevent the box from opening by returning false.

box.on("beforeOpen", function() {
    if (condition) {
       return false; // Prevent open
    }
});

open

This event fires when the box is about to open, and the animation starts.

box.on("open", function() {
	// do something
});

afterOpen

This event fires after the box has opened and the animation has ended.

box.on("afterOpen", function() {
	// do something
});

beforeClose

This event gets fired before the box is closed. You can use this event to prevent the box from closing by returning false.

box.on("beforeClose", function() {
    if (condition) {
       return false; // Prevent close
    }
});

close

This event fires when the box is about to close, and the animation starts.

box.on("close", function() {
	// do something
});

afterClose

This event fires after the box has closed and the animation has ended.

box.on("afterClose", function() {
	// do something
});

Chaining Events

Sometimes, you want to define multiple events, and repeating the box instance doesn't look nice. In that case, you can chain the on() method like in the example below.

box.on("beforeClose", function() {
	// do something
}).on("close", function() {
  // do something
}).on("afterClose", function() {
  // do something
});

Triggers

Below is a list of the available Triggers a box can be bound to.

onPageLoad

Fires when the whole page has loaded, including all dependent resources such as stylesheets and images. Equivalent to window.load event.

Example:

box.bindTrigger('onPageLoad');

onPageReady

Fires when the initial HTML document has been completely loaded and parsed without waiting for stylesheets, images, and subframes to finish loading. Equivalent to Document.DOMContentLoaded event.

Example:

box.bindTrigger('onPageReady');

onExit

Fires when the visitor intends to leave the page by tracking the mouse's movements.

Options object

Use the options below to customize the trigger behavior:

Example:

box.bindTrigger('onExit', {
    exit_timer: 5000
    firing_frequency: 2
});

onElementVisibility

Fires when a specified element(s) enters the viewport after scrolling down. If the specified scroll depth is visible in the viewport when the page loads, the trigger will fire without a scroll occurring.

Options object

Use the options below to customize the trigger behavior:

Example:

box.bindTrigger('onElementVisibility', {
    trigger_selector: '.myButton', 
    threshold: 0.8 // 80% percent,
    close_out_viewport: true
});

onScrollDepth

Fires when the visitor has reached the specified amount of scroll depth set in percentage or pixel. If the specified scroll depth is visible in the viewport when the page loads, the trigger will fire without a scroll occurs.

Options object

Use the options below to customize the trigger behavior:

Example:

box.bindTrigger('onScrollDepth', {
    scroll_depth: 'pixel',
    scroll_depth_value: 300
    reverse_scroll_close: true
});

onClick

Fires when the visitor clicks on specified element(s).

Options object

Use the options below to customize the trigger behavior:

Example:

box.bindTrigger('onClick', {
    trigger_selector: '.myDiv'
});

onHover

Fires when the visitor moves their mouse over specified element(s).

Options object

Use the options below to customize the trigger behavior:

Example:

box.bindTrigger('onHover', {
    trigger_selector: '.myDiv'
});

onAdBlockDetect

Fires during page load if the visitor has been detected using an AdBlocker. The AdBlockers that have been tested are AdBlock, Adblock Plus, uBlock Origin, and uBlocker.

Example:

box.bindTrigger('onAdBlockDetect');

onIdle

Fires when the visitor goes idle for a specific amount of time. It detects user activity based on mouse movement, click, keydown, touch events and window scroll events.

Options object

Use the options below to customize the trigger behavior:

Example:

box.bindTrigger('onIdle', {
    idle_time: 5000 // 5 seconds
    firing_frequency: 2 // Become aggressive
});

onExternalLink

Fires when the visitor clicks on external links.

Options object

Use the options below to customize the trigger behavior:

Example:

box.bindTrigger('onExternalLink', {
    selector: '.myDiv'
});

Use Cases & Examples

In this section, you can find some real-life examples and common use cases you may need.

Open popup after another popup has closed

This example shows you how to open a box after another one has closed.

let boxA = EngageBox.getInstance(1);
let boxB = EngageBox.getInstance(2);

boxA.on('afterClose', function() {
    boxB.open();
})

Prevent a popup from opening if another popup is opened

This example shows you how to prevent a box from opening if another box is already opened.

// Define boxes
const boxA = EngageBox.getInstance(1);
const boxB = EngageBox.getInstance(2);

boxB.on('beforeOpen', function() {
    if (boxA.opened) {
        return false;
    }
})

Prevent any popup from opening if there's at least 1 popup opened

This example makes use of the getTotalOpened() static method, which returns the total number of opened boxes every time a box is going to open. If opened boxes are found, the opening of the box is canceled by returning false on the beforeOpen event.

// Get all boxes
const boxes = EngageBox.getInstances();

// Loop through each box and attach a check to the beforeOpen event
boxes.forEach(function(box) {
    box.on("beforeOpen", function() {
        if (EngageBox.getTotalOpened() > 0) {
            return false;
        }
    })
})

Stop the video when the popup is about to close

If you're loading an HTML Video in a popup, it's very likely the video to continue to play even after you've closed the popup. The code below attempts to stop the video when you click to close the popup.

// Get box instance
const box = EngageBox.getInstance(1);

box.on('close', function() {
    if (video = box.el.querySelector('video')) {
        video.pause();
    }
})

Do not show a popup if it has no content

This is rather useful when your popup relies on a shortcode (Content Plugin) to display its content, but for some reason, the shortcode doesn't always return the content (data). In this case, you'd like to prevent the popup from showing up.

// Get box instance
const box = EngageBox.getInstance(1);

box.on('beforeOpen', function() {
	const content = box.el.querySelector('.eb-content').innerText.trim();
    if (content.length == 0) {
    	box.destroy();
    }
});

Attaching multiple triggers

Let's say you have a box configured to be triggered onPageLoad, and you'd like the same box also to be triggered onExit and onScrollDepth events but only after the visitor has closed it. The example below shows how you make that happen by attaching extra triggers to the box and becoming more intrusive.

// Get box instance
const box = EngageBox.getInstance(5);

box.on('afterClose', function() {
	box.bindTrigger('onScrollDepth');
	box.bindTrigger('onExit');
});

Notes

If you cannot access a box instance, use the onReady method to wait for EngageBox to load first.

EngageBox.onReady(function() {
    // your code goes here
});

The examples use ES6's const declaration, dropping support for IE10, and some aging browsers. If you prefer, switch the const to var declarations.