ScrollerJS

API Docs for: 1.0.0
Show:

Scroller Class

Defined in: src/scroller.js:186

Scroller class that provides the core logic for scrolling.

Constructor

Scroller

(
  • el
  • config
)

Defined in src/scroller.js:186

Parameters:

  • el HTMLElement

    DOM element to attach the Scroller.

  • config Object

    Object literal with initial attribute values.

Methods

_animate

(
  • x
  • y
  • duration
  • easingFn
)
private

Performs a custom animation given a function and using requestAnimationFrame as a way to interpolate points in time. The provided function must be continuous between [0,1] and images f(x) should also be within [0, 1]. By default the scroller uses CubicBezier function curves with the parameters defined in the EASING static variables.

Parameters:

  • x Float

    The x-position to scroll to

  • y Float

    The y-position to scroll to

  • duration Float

    The duration of the animation

  • easingFn Function

    A function that images x values within [0,1] range

_appendData

(
  • items
)
protected

Append an Array of elements into the scroller. This function is overriden by SurfaceManager to allow a custom DOM manipulation.

Parameters:

  • items HTMLElement

    Array of items to insert in the scroller

_computeMomentum

(
  • velocity
  • current
)
Object protected

Calculates the momentum {destination, time} based on the velocity of the gesture and on the acceleration.

Parameters:

  • velocity Float

    Velocity of the gesture

  • current Float

    Current scroller position

Returns:

Object:

An object with the destination and time where the scroller should go.

_computeSnap

(
  • start
  • end
  • velocity
  • current
)
Object protected

Calculates the snap momentum. If the original momentum calculation indicates that the destination of the scroller is way beyond the scrollable area, it needs to calculate a momentum that is closer to the boundaries to create the snap effect. The mathematical function to get the destination is a simple ponderation of how much px to snap based on the current position and velocity.

Parameters:

  • start Float

    Minimum or maximum scrollable position

  • end Float

    Wrapper size (how big the scroller wrapper is)

  • velocity Float

    Current gesture velocity

  • current Float

    Current scroller position

Returns:

Object:

An object with the destination and time where the scroller should snap to.

_customResetPosition

() protected

Checks whether or not a custom reset position is needed. Used to decouple pullToRefresh and pullToLoadMore functionality as much as possible.

_destroy

() private

Defined in src/scroller.js:405

Private destroy function that is responsible for the destruction of the instance itself. The plugins destroy themselves, as triggered by the public destroy method.

_end

(
  • e
)
private

Defined in src/scroller.js:860

Handles end gesture event.

Parameters:

  • e Event

    The gesturemove event provided by the browser

_endMoveRAF

() private

Defined in src/scroller.js:698

Fires and broadcasts a private _update event. This function is critical for notifying the plugins that the scroller is moving.

_endMoveRAF

() private

Defined in src/scroller.js:689

Stops the requestAnimationFrame debounce loop when gestureEnd is triggered.

_fire

(
  • eventType
  • arguments
)
private

Defined in src/scroller.js:481

Fire a custom event by name. The callback functions are executed with the scroller instance as context, and with the parameters listed here. The first argument is the event type and any additional arguments are passed to the listeners as parameters. This is used to notify the plugins of events that occur on the scroller.

Parameters:

  • eventType String

    Type of event to be dispatched

  • arguments Object

    An arbitrary set of parameters to pass to the listeners

_getScrollDirection

(
  • absX
  • absY
)
protected

Defined in src/scroller.js:736

Get the scroll direction once the gesture is bigger than a given threshold (via the minDirectionThrehold option).

Parameters:

  • absX Integer

    Absolute value of the x coordinate

  • absY Integer

    Absolute value of the y coordinate

_getVelocity

(
  • current
  • start
  • time
)
Float protected

Defined in src/scroller.js:993

Gets the velocity of the gesture. If debounce:true, the velocity has been already calculated through _trackVelocity. Otherwise, the value is determined from the current state of the scroller.

Parameters:

  • current Float

    Current position of the scroller

  • start Float

    Start position of the scroller when the gesture started

  • time Object

    {integer Duration of the gesture

Returns:

Float:

Velocity of the gesture

_handleEvents

(
  • action
)
private

Defined in src/scroller.js:424

Add or remove all of the neccesary event listeners, based on the provided configuration.

Parameters:

  • action String

    Action to bind or unbind events

_hook

(
  • when
  • method
  • method
)
private

Defined in src/scroller.js:506

Hook mechanism that allows plugins to run functions before or after the execution of a particular scroller function.

Parameters:

  • when String

    When to execute the hooked function (before|after)

  • method String

    Where to perform the hook

  • method Function

    Hook function to execute

_initialize

() private

Defined in src/scroller.js:234

Called in the constructor. Fires an event to nofify plugins that they can initialize themselves.

_initializePlugins

(
  • cfg
  • toMerge
)
Object private

Defined in src/scroller.js:279

Helper method to merge two object configurations. Relies on the Helpers utility module.

Parameters:

  • cfg Object

    Configuration base

  • toMerge Object

    Configuration to merge

Returns:

Object:

An object that merges both configuration properties.

_initializePlugins

(
  • cfg
)
private

Defined in src/scroller.js:245

Initializes the plugins provided in the configuration object. By default the scroller tries to initialize core plugins, such as SurfaceManager, PullToRefresh, and PullToLoadMore.

Parameters:

  • cfg Object

    Scroller configuration object

_initializeScroller

() private

Defined in src/scroller.js:222

Called in the constructor. Initializes the internal state of the instance.

_isOutOfScroll

(
  • absX
  • absY
)
private

Defined in src/scroller.js:755

Checks the current position.

Parameters:

  • absX Integer

    Current x coordinate

  • absY Integer

    Current y coordinate

_lockScroller

() private

Defined in src/scroller.js:725

Deactivates the scroller for a given gesture and fires the private lock event.

_momentum

(
  • current
  • start
  • duration
  • lowerMargin
  • wrapperSize
)
Object protected

Calculates the momentum for the current gesture. If the destination of the momentum falls outside of the scrollable region, it calculate the snapping point and the new momentum related to it.

Parameters:

  • current Float

    Current scroller position

  • start Float

    Start scroller position

  • duration Float

    Time of the gesture

  • lowerMargin Integer

    Maximum/minimum scrollable position

  • wrapperSize Integer

    Size of the scroller wrapper

Returns:

Object:

An object with the destination and time where the scroller should scroll to.

_move

(
  • e
)
private

Defined in src/scroller.js:785

Handles move gesture event.

Parameters:

  • e Event

    The gesturemove event provided by the browser

_needsLocking

() private

Defined in src/scroller.js:709

Checks if the scroller needs locking (will become inactive). By default, the scroller is locked if lockOnDirection is defined and it matches the current scrollDirection of the gesture. This can be useful when dealing with multiple nested scrollers which operate in different directions.

_onStopScrolling

(
  • e
)
protected

Defined in src/scroller.js:632

Invoked if a gestureStart event occurs while scrolling. By default, it will preventDefault() the start event so if a link is clicked, it won't trigger browser navigation.

Parameters:

  • e Event

    The gesturemove event provided by the browser

_prependData

(
  • items
)
protected

Prepend an Array of elements into the scroller. This function is overriden by SurfaceManager to allow a custom DOM manipulation.

Parameters:

  • items HTMLElement

    Array of items to insert in the scroller

_resetPosition

(
  • time
)
protected

Checks whether or not a custom reset position is needed if the scroller is outside the boundaries. Used to decouple pullToRefresh and pullToLoadMore functionality as much as possible.

Parameters:

  • time Integer

    Default time for the scroll in case a snap is needed

_scrollTo

(
  • x
  • y
  • time
  • easingFn
)
private

Scroll to a {x,y} position, given a specific time and easing function. If useCSSTransition: true, the CSS changes are applied to the scroller. Otherwise, an animation that interpolates positions using requestAnimationFrame is triggered.

Parameters:

  • x Float

    The x-position to scroll to

  • y Float

    The x-position to scroll to

  • time Float

    Duration of the animation

  • easingFn Function

    An easing function (if not provided, regular CubicBezier is used)

_setConfig

(
  • cfg
)
private

Defined in src/scroller.js:292

Merges the default configuration with the configuraton provided by the user and attaches the options to the instances. Also copies some options directly to the instance for easy access to them.

Parameters:

  • cfg Object

    Configuration base

_setElement

(
  • el
)
private

Defined in src/scroller.js:330

Finds the DOM element where the scroller will be hosted. The provided element will be the scroller-wrapper and the first child is the one that performs the scroll. This method also sets the proper class to the wrapper, depending on scrollDirection set in the configuration.

Parameters:

  • el String | HTMLElement

    Element to which the scroller is attached

_setNormalizedXY

(
  • absX
  • absY
)
private

Defined in src/scroller.js:767

Normalizes and sets the coordinate that is not being scrolled to 0 so it moves in one direction only.

Parameters:

  • absX Integer

    Current x coordinate

  • absY Integer

    Current y coordinate

_setPullToShowMore

() private

Defined in src/scroller.js:394

To be overriden by the PullToShowMore plugin. Calculates the height of PullToShowMore so it can be taken into account when calculating the total scrollable size.

_setWrapperSize

() private

Defined in src/scroller.js:349

Queries the wrapper element to get the updated size, in width and height. The element must be in the DOM to get the right measurement. The scroller won't work correctly if this attribute is set incorrectly.

_setWrapperSize

() private

Defined in src/scroller.js:362

Sets the overall sizes of the scroller. Calculates the actual scrollable area and sets the proper internal state. Note that this has a small dependency on the PullToLoadMore plugin.

_startMoveRAF

() private

Defined in src/scroller.js:669

Starts a requestAnimationFrame loop when a gestureMove is triggered to debounce the event from the animation. For each frame, it updates the position and velocity, and fires a private _update event to any plugin listening to it.

_stopMomentum

() private

Stops the scroller inertia while scrolling and establishes the current scroller position.

_trackVelocity

(
  • e
)
protected

Defined in src/scroller.js:644

Tracks and calculates the velocity of the gesture between two points in time. Executed when scroller option debounce: true in the context of a requestAnimationFrame (every ~17ms). It uses the delta for both position and time between the current and previous frames to get the current velocity value, then it applies an exponential moving average filter to weight and smooth out the final velocity.

Parameters:

  • e Event

    The gesturemove event provided by the browser

_transitionEasing

(
  • easing
)
private

Sets the transition easing function property into the scroller node.

Parameters:

  • easing Integer

    String representation of the CSS easing function

_transitionEnd

(
  • e
)
protected

Handler invoked by the transitionEnd event when the scroller reached an end (this is used when cssTransition:true).

Parameters:

  • e Event

    The transitionEnd event provided by the browser

_transitionTime

(
  • time
)
private

Sets the transition time property into the scroller node.

Parameters:

  • time Integer

    Time or duration of the transition

_translate

(
  • x
  • y
)
protected

Sets the current position in the CSS matrix3d transform. We use matrix3d to force GPU acceleration and to allow plugins to easily manipulate the matrix later on.

Parameters:

  • x Integer

    Position for x coordinate

  • y Integer

    Position for y coordinate

_wheel

(
  • e
)
private

Defined in src/scroller.js:900

Handles the wheel event for scrolling.

Parameters:

  • e Event

    The wheel event provided by the browser

_wheelRAF

(
  • e
)
private

Defined in src/scroller.js:972

Handles the debounce of the wheel event to decouple the event and the actual DOM update.

Parameters:

  • e Event

    The wheel event provided by the browser

appendItems

(
  • data
)
public

Append items to the scroller.

It's recommended to use this method to add content to the scroller instead of manually adding it to the DOM directly, because the scroller will be able to optimize the rendering lifecycle depending on the configuration.

Parameters:

  • data HTMLElement | HTMLElement | String

    Elements to append into the scroller

destroy

() public

Destroy lifecycle method. Fires the _destroy event prior to invoking the destructor on itself.

handleEvent

(
  • e
)
private

Defined in src/scroller.js:588

Handles the start gesture event.

Parameters:

  • e Event

    The gesturestart event provided by the browser

handleEvent

(
  • e
)
private

Defined in src/scroller.js:534

Handler to dispatch all of the events that the scroller listens to. The browser calls this function if any of the events registered in _handleEvents are triggered.

Parameters:

  • e Event

    The event provided by the browser

on

(
  • eventType
  • fn
  • [context]
)
public

Prepend an Array of elements into the scroller. This function is overriden by SurfaceManager to allow a custom DOM manipulation.

Parameters:

  • eventType String

    Event name

  • fn Function

    The callback to execute in response to the event

  • [context] Object optional

    Override this object in callback

plug

(
  • plugin
)
public

Adds a plugin to the scroller.

A plugin can be a constructor function with its prototype or just a regular object. The scroller merges these methods with its own (with the exception of a method called init).

If an init method is provided, the scroller automatically calls it to let the plugin initialize, attach custom events, and set the right state.

Parameters:

  • plugin Function | Object

    Plugin to inject into the scroller

Example:

       var scroller = new Scroller('#wrapper', {myCustomOption: 'yay!'});

       scroller.plug({
           init: function () {
               this.on('_update', this._myPluginUpdate);
           },
           _myPluginUpdate: function () {
               console.log(this.opts.myCustomOption + this.y);
           }
       });

prependItems

(
  • data
)
public

Prepend items to the scroller.

It's recommended to use this method to add content to the scroller instead of manually adding it to the DOM directly, because the scroller will be able to optimize the rendering lifecycle depending on the configuration.

Parameters:

  • data HTMLElement | HTMLElement | String

    Elements to prepend into the scroller

refresh

() public

Refreshes the scroller size and fires a private _refresh event so plugins can update themselves. This method is meant to be called when something in the DOM has changed to notify the scroller that it needs to recalculate its size and to set the correct internal state.

resize

() public

Update the scroller size. Called automatically when the browser fires a resize or an orientationChange event.

scrollTo

(
  • x
  • y
  • [time]
  • [easingFn]
)
public

Scroll to a {x,y} position given a specific time and easing function.

Parameters:

  • x Float

    The x-position to scroll to

  • y Float

    The y-position to scroll to

  • [time] Float optional

    ms of the scroll animation

  • [easingFn] Function optional

    An easing equation if time is set (default is the easing attribute)

scrollToBottom

(
  • [time]
  • [easingFn]
)
public

Scroll to the bottom of the scroller.

Parameters:

  • [time] Float optional

    ms of the scroll animation

  • [easingFn] Function optional

    An easing equation if time is set (default is the easing attribute)

scrollToTop

(
  • [time]
  • [easingFn]
)
public

Scroll to the top of the scroller.

Parameters:

  • [time] Float optional

    ms of the scroll animation

  • [easingFn] Function optional

    An easing equation if time is set (default is the easing attribute)

Properties

ACCELERATION_CONSTANT

Float static

Defined in src/scroller.js:156

Specifies the acceleration constant px/msĀ².

Default: "0.0005"

DEFAULTS

String static

Defined in src/scroller.js:76

Default configuration for the scroller. This option can be modified at the static level or on a per instance basis.

EASING

Object final static

Defined in src/scroller.js:125

Wraps EASING_REGULAR and EASING_BOUNCE with the corresponding string representation.

Default: "{regular: {}, bounce: {}}"

EASING_BOUNCE

Function static

Defined in src/scroller.js:115

Default parametrized CubicBezier function curve that is used when the scroller goes out of limits.

Default: "CubicBezier(0.33, 0.33, 0.66, 0.81)"

EASING_REGULAR

Function static

Defined in src/scroller.js:105

Default parametrized CubicBezier function curve that is used on regular scrolling.

Default: "CubicBezier(0.33, 0.66, 0.66, 1)"

MIN_VELOCITY

Float static

Defined in src/scroller.js:146

Specifies the minimum velocity required to scroll.

Default: "0.1"

MOUSE_WHEEL_INVERTED

Boolean static

Defined in src/scroller.js:176

Specifies whether or not mouse wheel movements should be inverted.

Default: "false"

MOUSE_WHEEL_SPEED

Integer static

Defined in src/scroller.js:166

Specifies the mouse wheel speed.

Default: "20"

SCROLL_HORIZONTAL

String final static

Defined in src/scroller.js:66

Identifies horizontal scrolling.

SCROLL_VERTICAL

String final static

Defined in src/scroller.js:56

Identifies vertical scrolling.