VisSense.js Class: VisSense

new VisSense(element, config)

Creates a VisSense object which wraps the given element to enable visibility operations.

Parameters:

Name	Type	Argument	Default	Description
`element`	DOMElement			A DOM element.
`config`	VisSense~VisSenseConfig	<optional>	{fullyvisible: 1, hidden: 0}	A configuration object.

Throws:

Will throw an error if the first argument is not a DOM Element.
Type Error

Example

var element = document.getElementById('myElement');
var vis = VisSense(element); // or new VisSense(element)

vis.isVisible();
// => true

vis.percentage();
// => 0.93

Classes

PubSub
VisMon

Namespaces

Utils

Methods

<static> of() → {VisSense}

Constructs and returns a VisSense object. This is syntactic sugar for new VisSense(..).

Returns:

An initialized VisSense object.

Type: VisSense

Example

var myElement = document.getElementById('myElement');
var visElement = VisSense.of(myElement);

element() → {DOMElement}

Returns the element this instance is bound to

Returns:

The element

Type: DOMElement

Example

var visElement = VisSense(element);

element === visElement.element();
// => true

isFullyVisible() → {boolean}

Checks if the element is currently fully visible.

Returns:

true if the element is fully visible, otherwise false.

Type: boolean

Example

var visElement = VisSense(element);
visElement.isFullyVisible();
// => true

isHidden() → {boolean}

Checks if the element is currently hidden.

Returns:

true if the element is hidden, otherwise false.

Type: boolean

Example

var visElement = VisSense(element);
visElement.isHidden();
// => false

isVisible() → {boolean}

Checks if the element is currently visible.

Returns:

true if the element is visible, otherwise false.

Type: boolean

Example

var visElement = VisSense(element);
visElement.isVisible();
// => true

monitor(config) → {VisSense.VisMon}

Parameters:

Name	Type	Description
`config`	VisSense.VisMon#VisMonConfig	A config object

Returns:

A VisMon object observing the element.

Type: VisSense.VisMon

Example

var visMon = VisSense(...).monitor({
  strategy: [new VisSense.VisMon.Strategy.EventStrategy(...)]
  update: function() {
    console.log('updated.');
  }
});

percentage() → {number}

Returns the currently visible area of the element in percent (0..1)

Returns:

The currently visible area of the element.

Type: number

Example

var visElement = VisSense(element);

visElement.precentage();
// => 0.33

state() → {VisSense~VisState}

Returns an object representing the current state. This function always invokes the full visibility scan and therefore produces a new object everytime.

Returns:

A state object.

Type: VisSense~VisState

Example

var visElement = VisSense(element);
visElement.state();
// => {
   code: 1,
   state: 'visible',
   percentage: 0.33,
   fullyvisible: false,
   visible: true,
   hidden: false,
   previous: {}
 }

Type Definitions

PercentageHook(element) → {number}

This callback function that will be called to determine the visible area of the element.

Parameters:

Name	Type	Description
`element`	DOMElement	The element to get the visible percentage of.

Returns:

The visible percentage of the element (between 0 and 1).

Type: number

VisibilityHook(element) → {boolean}

This callback function that will be called to intercept the default visibility process.

Parameters:

Name	Type	Description
`element`	DOMElement	The target element.

Returns:

false if the element is hidden, true otherwise.

Type: boolean

VisSenseConfig

A configuration object to configure a VisSense instance.

Type:

Object

Properties:

Name	Type	Argument	Default	Description
`fullyvisible`	number	<optional>	1	The percentage limit an element is considered fully visible.
`hidden`	number	<optional>	0	The percentage an element limit is considered hidden.
`percentageHook`	VisSense~PercentageHook	<optional>	VisSense.Utils.percentage	A callback function to determine the visible percentage of the element. If not provided it will fallback to VisSense.Utils.percentage.
`percentageHooks`	VisSense~VisibilityHook[]	<optional>	[]	An array of callback functions to intercept the visibility procedure. By default a visibility hook using the VisibilityAPI will be registered.

VisState

An object representing the visibility state of an element.

Type:

Object

Properties:

Name	Type	Description
`code`	number	A number representation of an visibility state. This is either 0, 1 or 2.
`state`	string	An string representation of an visibility state. This is either 'hidden', 'visible' or 'fullyvisible'.
`percentage`	number	The visible percentage of the element.
`previous`	VisSense~VisState \| Object	The previous state if any, otherwise `{}` will be returned. This value's `previous` property will always be deleted.
`fullyvisible`	boolean	`true` if the element is fully visible, otherwise `false`.
`visible`	boolean	`true` if the element is visible, otherwise `false`.
`hidden`	boolean	`true` if the element is hidden, otherwise `false`.