Scroll Utilities

The X5 Engine API provides you a set of scroll-related utilities.

x5engine.utils.scroll
x5engine.utils.scrollHelper(element)

x5engine.utils.scroll

Provides a set of static methods that may help in managing the scroll-related changes.

.observe(resizeCallback, updateCallback, id) ⇒ `void`

Adds a new observer. The observer will be updated thru the updateCallback.
The resizeCallback will be called immediately to get the observation rules.
The rules define how to filter updates and call updateCallback only when needed.

Kind: static method of x5engine.utils.scroll

Param	Type	Description
resizeCallback	`function`	Called when the viewport is resized, it must return a bool or a function, il will be used to filter `updateCallback` calls
updateCallback	`function`	Called to send the updated scroll position
id	`string`	Optional identifier of the observer. Since: 2022.1.7.0

Since: 2022.1.5.1

Example

function resizeCallback(width, height) {
    // updateCallback will be called starting from when
    // the scroll position reaches the 50% of the page height
    return (scrollPosition) => scrollPosition > height / 2;
}
function updateCallback(scrollPosition) {
    // Update the page elements by using the scroll position...
}
// Add the observer with the id 'example'
x5engine.utils.scroll.observe(resizeCallback, updateCallback, 'example');

.unobserve(id) ⇒ `void`

Removes an observer. The observer with the specified id will be removed.

Kind: static method of x5engine.utils.scroll

Param	Type	Description
id	`string`	Identifier of the observer

Since: 2022.1.7.0

Example

// Remove the observer with the id 'example'
x5engine.utils.scroll.unobserve('example');

resizeCallback

Called when the viewport is resized, it must return a bool or a function, il will be used to filter updateCallback calls.

Kind: callback function for observe method.

Param	Type	Description
width	`number`	Current width of the viewport
height	`number`	Current height of the viewport

Since: 2022.1.5.1

Returns: function | boolean - the filter function, will be called with the current scroll position to filter updateCallback calls; when bool is returned, it defines if the updateCallback must be called or not.

updateCallback

Called when the page is scrolled.

Kind: callback function for observe method.

Param	Type	Description
scrollPosition	`number`	Current scroll position of the page

Since: 2022.1.5.1

x5engine.utils.scrollHelper(element) ⇒ `object`

Provides a set of helper methods that may be used in conjunction with the observe method to handle common behaviors.

Kind: static method

Param	Type	Description
element	`Element`	Optional DOM Element to observe the scroll for

Since: 2022.1.5.1

Returns: object - An object containig different scroll helper methods

Example

// We are going to observe scroll from the 'scroll-observer' element
var element = document.getElementById('scroll-observer');
var helper = x5engine.utils.scrollHelper(element);
// Updates will be triggered when the element
// will be into viewport with a tolerance of 50px
var resizeCallback = helper.inViewport(50);
var updateCallback = helper.objectPercentiageScrolled((perc) => {
    // Element opacity will increase while the element gets scrolled into view
    element.style.opacity = perc / 100;
});
x5engine.utils.scroll.observe(resizeCallback, updateCallback);

.always() ⇒ `function`

This function can be called to obtain a resizeCallback that always filter the observing element.

Kind: resizeCallback provider
Since: 2022.1.5.1
Returns: function

.inViewport(overflowTop, overflowBottom) ⇒ `function`

This function can be called to obtain a resizeCallback that filter the observing element when it is into the viewport.

Kind: resizeCallback provider

Param	Type	Description
overflowTop	`number`	Optional tolerance on top of the element
overflowBottom	`number`	Optional tolerance on bottom of the element

If overflowBottom is not specified, the value of overflowTop will be used instead.