API

Ad-rotator.js provides a simple API to control Ad rotation. There are 6 methods exposed as seen below...

1. start

The start() method, as you might have guessed, is used to start Ad-rotation.

const instance = rotator( /* config options */ );

/* Starts ad rotation */
instance.start();

It is responsible to initialize ad-rotator.js by setting up the essential events and populating the DOM before the actual rotation begins.

2. pause

The pause() method pauses the Rotation. By default, when the user hovers over an Ad, rotation is paused. It resumes if the user clicks on the Ad or is not hovering over it anymore.

const instance = rotator( /* config options */ );

/* Pauses ad rotation */
instance.pause();

/* You can also use "pause" in the cb(callback) config option to
 * pause every advertisement after it has been clicked/hovered upon
 */
instance.conf.cb = instance.pause;

Any paused instance will resume rotation automatically if the user scrolls away from the Ad such that it is no longer visible (i.e. the Ad goes out of the viewport). Rotation cannot be paused permanently because that would beat the purpose of this library.

3. resume

The resume() method resumes Ad Rotation.

const instance = rotator( /* config options */ );

/* Resumes ad rotation */
instance.resume();

Ad rotation is paused when Ads are hovered upon and resumed automatically when they're no longer being hovered upon. Use the resume() method to resume a paused ad rotator instance.

4. add

The add() method can be used to inject a new Ad on the fly.

const instance = rotator( /* config options */ );

instance.start();
/* Adds a new Ad */
instance.add(
  {
    url: 'https://gospelmusic.io',
    img: './path-to-img.jpg',
    title: 'Free high quality music', // optional
    weight: '100',                    // optional
  }
);

The newly injected Ad is added at the end of the array of Ads and is displayed only in the next rotation cycle.

5. remove

The remove() method can be used to remove an item from the Advertisements array.

const instance = rotator( /* config options */ );

/* Remove Ads */
instance.remove(); // remove the last Ad/item
instance.remove(   // remove a specific Ad/item
  {
    url: 'https://digitalfortress.tech', // url is optional
    img: './path-to-img'
  }
);

By default, the remove() method deletes the last item in the advertisements array. To remove a particular advertisement, you can also pass the Ad as a parameter. The change in the Advertisements array is reflected in the next rotation cycle.

6. destroy

The destroy() API method destroys Ad Rotation. It cleans up the DOM and removes all associated events.

const instance = rotator( /* config options */ );

/* destroys the rotation, DOM and events */
instance.destroy();

To reactivate ad Rotator, simply call rotatorInstance.start().