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:

OptionDescriptionDefaultType
exit_timerThe time in milliseconds after that the trigger will fire.2000Integer
firing_frequencyThe fire frequency of the trigger. Values: 1 (Once Per Page), 2 (Unlimited)1Integer

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:

OptionDescriptionDefaultType
trigger_selectorThe query selector representing the DOM element(s) that fires the trigger.String
thresholdSpecify how much of the selected element must be visible on screen before the trigger fires. Values: 0 - 10.5Float
close_out_viewportAutomatically close the box when it is outside of the viewport. It respects threshold. Values: true, falsefalseBool
firing_frequencyThe firing frequency of the trigger. Values: 1 (Once per Page), 2 (Unlimited)1Integer

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:

OptionDescriptionDefaultType
scroll_depthThe scroll depth type. Values: percentage, pixelpercentageString
scroll_depth_valueThe 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.80Integer
reverse_scroll_closeAutomatically close the box when the user scrolls in the opposite direction. Values: true, falsefalseBool
firing_frequencyThe firing frequency of the trigger. Values: 1 (Once per Page), 2 (Unlimited)1Integer

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:

OptionDescriptionDefaultType
trigger_selectorThe query selector representing the DOM element(s) that fires the trigger.String

Example:

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

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:

OptionDescriptionDefaultType
trigger_selectorThe 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:

OptionDescriptionDefaultType
trigger_selectorThe 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:

OptionDescriptionDefaultType
idle_timeThe time in milliseconds to check if a user is idle for.10000Integer
firing_frequencyThe fire frequency of the trigger. Values: 1 (Once Per Page), 2 (Unlimited)1Integer

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.

Was this helpful?