Documentation

Variants

This chapter is an introduction to the different variant types in Bunchbox.

Original variant

The original variant is the most simple kind of variant. It does nothing on the page. This way you can define the baseline.

Redirect variant

The redirect variant will redirect the user to a different page. This is useful when a separate webpage has been built.

Code variant

The code variant will execute a given JavaScript code block on the page. The code variant is useful when only some elements of the existing page have to be changed.

The code in the variant has access to the following helper functions.

Wait for elements with bb.exists

The code variant is executed immediately when the users enters the page. That means certain elements that are to be manipulated may not exist yet. In order to make sure they can be manipulated as soon as they appear Bunchbox provides the bb.exists method.

Syntax: bb.exists(selector, callback, [options])

  • selector: A query selector string to define the elements. Must be compatible with document.querySelector.
  • callback: A function to be called once the element(s) have been found. The first argument of this function is an array with elements that matched the selector.
  • options (optional) : An object to change the default behaviour. The bb.exists function only runs until the ready state of the document is complete. To change this, one can add a {forever: true} option. This will cause the function to run until at least one matching element was found. By adding {elements: 3} as an option, bb.exists will wait until it found at least three matching elements.

Example:

bb.exists('h2', function (els) {
  els[0].innerHTML = 'Buy now';
});

bb.exists('ul > li', function (els) {
    els.forEach(function(li, i) {
        li.innerHTML = (i+1) + ". Item";
    });
}, { forever: true, elements: 3});
Wait until a certain condition is met with bb.waitUntil

Due to the fact, that Bunchbox is executed immediately, it is possible, that some important conditions are not met yet or that some required global objects are not defined yet. To explicitly wait for a specific event Bunchbox provides the bb.waitUntil method.

Syntax: bb.waitUntil(testFn, callback, [options])

  • testFn: A function to test a certain condition. The function is executed until it returns a truethy value
  • callback: A function to be called once the test function returned a truethy value.
  • options (optional) : An object to change the default behaviour. The bb.waitUntil function only runs until the ready state of the document is complete.Add {forever: true} to keep the function running even if the document ready state is complete.

Example:

bb.waitUntil(function() {
    return !!window.$;
}, function() {
    bb.exists('h2', function(headlines) {
        $(headlines).text('Sale %');
    }, {forever: true, elements: 2});
}, {forever: true});
Add stylesheets using bb.css

It is often the case that a new style definition should be applied as soon as the variant gets executed. To add a new <style> tag to the DOM, Bunchbox provides a helper function called bb.css.

Syntax: bb.css([element], styleString)

  • element (optional): An element to which the style tag gets appended. When omitting this argument, the tag will be added to the head of the document.
  • styleString: A string containing the style definitions.

Example:

bb.css('.container h2 { display: none; }');

bb.exists('body', function(body) {
    bb.css(body[0], '.container h2 { display: none; }');
});
Append HTML content with bb.append

To append new HTML content to an element Bunchbox provides the bb.append function.

Syntax: bb.append(element, htmlString)

  • element: A DOM element the HTML string is appended to
  • htmlString: An HTML string

Example:

bb.exists('.wrapper', function(wrapper) {
    bb.append(wrapper[0], '<p>New category</p>');
});
Prepend HTML content with bb.prepend

To prepend new HTML content to an element Bunchbox provides the bb.prepend function.

Syntax: bb.prepend(element, htmlString)

  • element: A DOM element the HTML string is prepended to
  • htmlString: An HTML string

Example:

bb.prepend(document.getElementById("wrapper"), '<p>New category</p>');
Insert HTML content after an element with bb.insertAfter

To insert HTML content after a certain element Bunchbox provides the bb.insertAfter function.

Syntax: bb.insertAfter(element, htmlString)

  • element: A DOM element the HTML string is inserted after
  • htmlString: An HTML string

Example:

bb.prepend(document.querySelector("#container"), '<p>New category</p>');
Replace an element with bb.replaceWith

To replace a specific element with new HTML content Bunchbox provides the bb.replaceWith function.

Syntax: bb.replaceWith(element, htmlString)

  • element: A DOM element the HTML string is replaced with
  • htmlString: An HTML string

Example:

bb.replaceWith(document.getElementsByClassName("h2")[0], '<h4>Buy one, get one free!</h4>');

Add and remove event listeners

Bunchbox provides bb.on and bb.off to attach or detach event handlers.

Syntax: bb.on(event, [elements, selector], callback)

  • event : An event string to define the event.
  • elements (optional) : One or multiple DOM elements to attach the event to. Event handlers will be attached to the document by default.
  • selector (optional) : A query selector string to filter descendants of the elements that trigger the event.
  • callback: A function to execute when the event is fired.

Example:

bb.on('mouseover', function(event) {
    event.target.innerHTML += "<button>Submit</button>";
});

bb.on('mouseout', 'h2', function(event) {
    event.target.innerHTML = "Category";
});

bb.exists('h2', function(h2) {
    bb.on('mouseover', h2, function(event) {
        event.target.style.color = "red";
    });
});

bb.exists('body', function(body) {
    bb.on('click', body[0], "h2", function(event) {
        event.target.style.color = "blue";
    });
});

Syntax: bb.off(id)

  • id : An ID or a list of ID's returned by bb.on

Example:

var id = bb.on('click', function(event) {
    bb.off(id);
    event.target.style.display = "block";
});
Redirect with bb.redirect

The bb.redirect method acts as a helper to make sure the participation is tracked when the user gets redirected. If the user would be redirected using the regular window.location = http://… method it may cause the participation to not be tracked.

Syntax: bb.redirect(location)

Example:

bb.redirect('/variant.html');
Read experiment and variant details

To read current experiment details, such as experiment or variant names, Bunchbox provides the bb.info object. In addition, the object contains experiment, variant and step ID's. It will also hold the variant event, if web tracking is enabled.

Controlling mouse tracking with bb.mousetracking

The bb.mousetracking namespace is used to control the mouse tracking. It provides bb.mousetracking.pause and bb.mousetracking.resume to either pause or resume the mouse tracking for a variant.

Syntax: bb.mousetracking.pause() and bb.mousetracking.resume()

Example:

bb.mousetracking.pause();

bb.on('click', 'h2', function(event) {
    bb.mousetracking.resume();
});