# FireBox Javascript API Original URL: https://www.fireplugins.com/docs/developers/firebox-javascript-api/ Last updated: 2025-03-14T10:56:02+02:00 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](https://www.fireplugins.com/docs/firebox/extending/firebox-javascript-api/#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 }); ``` ### conversion This event fires when a Button/Image block that has “Track conversion” is enabled and the block is clicked. ``` box.on("conversion", function(event, conversionData) { // do something }); ``` - conversionData provides access to the following details - campaignID: The campaign ID - type: ‘click’ - box_log_id: The view log open ID - source: The element that was used to create the conversion - label: The element label that was used to create the conversion ### 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.