FireBox Javascript API
The FireBox JavaScript Events API is extremely powerful, providing a set of events on which you can bind your custom Javascript functionality to further extend FireBox to suit your specific needs
The FireBox Instance
In this section, you will learn how to retrieve a FireBox instance and what are the available methods to use so you can manipulate it.
Retrieving the FireBox instance
Here are some examples of how you can retrieve a FireBox instance.
If you know the box's ID, use the getInstance() built-in method:
const box = FireBox.getInstance(ID);You can get an instance using DOM querySelector() method.
const box = document.querySelector('.myBoxClass').firebox;You can also find an instance in the instances collection using the getInstances() built-in method.
const boxes = FireBox.getInstances()[0];In case you are unable to access a box instance, it's very likely the instance is not loaded yet. In that case, you should make sure FireBox has finished loading all instances first.
FireBox.onReady(function() {
const box = FireBox.getInstance(ID);
// the rest of your code here
});To access the DOM element representing the box, use the el instance property.
const boxEl = FireBox.getInstance(ID).el;Properties
Once you've got the instance in say box, you can access the following properties.
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 its 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 FireBox instance by removing event listeners and DOM elements.
box.destroy();Static Methods
FireBox exposes the following methods which don’t require an instance to work.
getInstance(ID)
Get a box instance by ID.
const box = FireBox.getInstance(2);getInstances()
Get all box instances. This is rather useful when you want to loop through all initialized boxes.
const boxes = FireBox.getInstances();closeAll()
Closes all opened boxes.
FireBox.closeAll();getTotalOpened()
Returns the number of opened boxes.
const total = FireBox.getTotalOpened();Events
FireBox 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 fired 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
There are cases when 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 you can find a list of the available Triggers a box can be bind 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 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 specified element(s) enters the viewport after scroll 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 representing 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 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 occurring.
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 needs 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 representing the DOM element(s) that fires the trigger. | String |
Example:
box.bindTrigger('onClick', {
trigger_selector: '.myDiv'
});onExternalLink
Fires when the visitor clicks on specified element(s) or any element that redirect to external sites.
Options object
Use the options below to customize the trigger behavior:
| Option | Description | Default | Type |
|---|---|---|---|
| trigger_selector | The query selector representing the DOM element(s) that fires the trigger or leave empty to trigger on any external links. | String |
Example:
box.bindTrigger('onExternalLink', {
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 representing 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
});Use Cases & Examples
In this section you can find some real-life examples and common use-cases you may need.
Open box after another box has closed
This example shows you how you can open a box after another box has closed.
let boxA = FireBox.getInstance(1);
let boxB = FireBox.getInstance(2);
boxA.on('afterClose', function() {
boxB.open();
})Prevent box from opening if another box is opened
This example shows you how prevent a box from opening if another box is already opened.
// Define boxes
const boxA = FireBox.getInstance(1);
const boxB = FireBox.getInstance(2);
boxB.on('beforeOpen', function() {
if (boxA.opened) {
return false;
}
})Prevent any box from opening if there are boxes 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 cancelled by returning false on the beforeOpen event.
// Get all boxes
const boxes = FireBox.getInstances();
// Loop through each box and attach a check to the beforeOpen event
boxes.forEach(function(box) {
box.on("beforeOpen", function() {
if (FireBox.getTotalOpened() > 0) {
return false;
}
})
})
Stop video when the box 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, attemps to stop the video the time you click to close the popup.
// Get box instance
const box = FireBox.getInstance(1);
box.on('close', function() {
if (video = box.el.querySelector('video')) {
video.pause();
}
})Do not show box if has no content
This is rather useful when your popup relies on a shortcode (Content Plugin) to display its content but for some reasons the shortcode doesn't always return content (data). In this case, you'd like to prevent the popup from showing up.
// Get box instance
const box = FireBox.getInstance(1);
box.on('beforeOpen', function() {
const content = box.el.querySelector('.rstbox-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 to be triggered also onExit and onScrollDepth events but only after it has been closed by the visitor. The example below shows you how you make that happen by attaching extra triggers to the box and become more intrusive.
// Get box instance
const box = FireBox.getInstance(5);
box.on('afterClose', function() {
box.bindTrigger('onScrollDepth');
box.bindTrigger('onExit');
});
Notes
In case you are unable to access a box instance, use the onReady method to wait for FireBox to load first.
FireBox.onReady(function() {
// your code goes here
});Notice that the examples are using ES6's const declaration, dropping support for IE10 and some aging browsers. If you prefer, switch the const to var declarations.
