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
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:
Option | Description | Default | Type |
---|---|---|---|
exit_timer | The time in milliseconds after that the trigger will fire. | 2000 | Integer |
firing_frequency | The fire frequency of the trigger. Values: 1 (Once Per Page), 2 (Unlimited) | 1 | Integer |
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:
Option | Description | Default | Type |
---|---|---|---|
trigger_selector | The query selector represents the DOM element(s) that fires the trigger. | String | |
threshold | Specify how much of the selected element must be visible on screen before the trigger fires. Values: 0 - 1 | 0.5 | Float |
close_out_viewport | Automatically close the box when it is outside of the viewport. It respects the threshold. Values: true, false | false | Bool |
firing_frequency | The firing frequency of the trigger. Values: 1 (Once per Page), 2 (Unlimited) | 1 | Integer |
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:
Option | Description | Default | Type |
---|---|---|---|
scroll_depth | The scroll depth type. Values: percentage, pixel | percentage | String |
scroll_depth_value | The value of the scroll depth the visitors need to reach to fire the trigger. Values in case of percentage scroll depth type: 0 - 100. Value in case of pixel scroll depth type: Any positive integer. | 80 | Integer |
reverse_scroll_close | Automatically close the box when the user scrolls in the opposite direction. Values: true, false | false | Bool |
firing_frequency | The firing frequency of the trigger. Values: 1 (Once per Page), 2 (Unlimited) | 1 | Integer |
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:
Option | Description | Default | Type |
---|---|---|---|
trigger_selector | The query selector represents the DOM element(s) that fires the trigger. | String |
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:
Option | Description | Default | Type |
---|---|---|---|
trigger_selector | The query selector represents the DOM element(s) that fires the trigger. | String |
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:
Option | Description | Default | Type |
---|---|---|---|
idle_time | The time in milliseconds to check if a user is idle for. | 10000 | Integer |
firing_frequency | The fire frequency of the trigger. Values: 1 (Once Per Page), 2 (Unlimited) | 1 | Integer |
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:
Option | Description | Default | Type |
---|---|---|---|
selector | The query selector represents the DOM element(s) that fires the trigger. | String |
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.