element-monitor

JS object for monitoring and reacting to elements' properties - size, position, visibility, existence.

Documentation

Table of Contents

• createTicker
• add
  • Parameters
• remove
• destroy
• ElementMonitor
  • Parameters
  • setOptions
    • Parameters
  • setCallback
    • Parameters
  • start
  • stop

createTicker

Creates ticker object that groups periodic function calls by their interval.

Returns {add: (function (number, Function)), destroy: (function ()), _inspect: (function (): any), _tick: (function ())}

add

Adds function to the ticker.

Parameters

• interval number
• fn Function

Returns {remove: (function ())}

remove

Removes function from ticker. If this was last function in ticker, stops the ticker.

destroy

Stops all tickers, removes all data.

ElementMonitor

Class for monitoring of changes in element's existence, visibility, size or position.

Parameters

• elements (string | Array<Element> | HTMLCollection | Function)
• callbacks Object (optional, default {})
• options Object

setOptions

Updates existing options with new ones.

Parameters

• options Object (optional, default {})

setCallback

Adds new callback.

Parameters

• id string
• callback Function

start

Starts monitoring of matching elements.

stop

Stops monitoring of matching elements.

How to use it

This will display a message in console, whenever any property of element with id myElement will change:

var my_element_monitor = new ElementMonitor('#myElement', {
  onResize: function () {console.log('Element size changed.');},
  onMove: function () {console.log('Element moved to.');},
  onShow: function () {console.log('Element was displayed.');},
  onHide: function () {console.log('Element was hidden.');}
});
my_element_monitor.start();

Constructor

new ElementMonitor(element, options);

element

It can be either CSS selector, reference to Node object, or a function returning an element

• CSS selector - If the query matches more than one element, it will use the first one. It's better to use unique CSS selectors to prevent confusion.
• reference - Note that if you will destroy the referenced element, you will lose it forever. If you will recreate the element later, you will need to associate it again using ElementMonitor.setElement method.
• function - You can use a function that returns reference to the element. This may come handy in situations, when you are trying to target an element that is often dynamicaly created and removed and can not be targeted by simple CSS selector.

All these examples are equivalent:

// CSS selector
new ElementMonitor('#myElement');
 
// reference
var my_element = document.getElementById('myElement');
new ElementMonitor(my_element);
 
// function
function getMyElement() {
  return document.getElementById('myElement');
}
new ElementMonitor(getMyElement);

options

Configuration object that can set some basic properties of ElementMonitor. But more importantly, this is where you set-up your callbacks.

• interval (default 100) - Time in microseconds. This is how often the check tick will happen. By default, it will be 10 times per second. If you want to lower the performance impact of this script, set a higher number
• onResize - Function fired when element changes size.
• onMove - Function fired when element changes position.
• onVisibilityChange - Function fired when element changes visibility.
• onShow - Function fired when element becomes visible.
• onHide - Function fired when element becomes invisible.
• onExistenceChange - Function fired when element is created or destroyed.
• onAppear - Function fired when element appears in the document.
• onVanish - Function fired when is removed from the document.
• onChange - Function fired when any of the above changes happnes to the element.

Methods

addElement()

Used to add an element to the list of monitored elements in this instance.

my_element_monitor.addElement('#newElement');

setElement()

Used to set or change element of the existing instance:

my_element_monitor.setElement('#otherElement');

setOptions()

You can set options on the fly. Old options will remain unchanged if you do so:

my_element_monitor.setOptions({
  interval: 1000
});

start()

Starts the ticker:

my_element_monitor.start();

stop()

Starts the ticker:

my_element_monitor.stop();

Bug reports, feature requests and contact

If you found any bugs, if you have feature requests or any questions, please, either file an issue at GitHub or send me an e-mail at mailto:[e-mail].

License

Element Monitor is published under the MIT license.