ScrollMagic

Class: ScrollMagic

ScrollMagic

new ScrollMagic(options)

The main class that is needed once per scroll container.

Parameters:
Name Type Argument Description
options object <optional>

An object containing one or more options for the controller.

Properties
Name Type Argument Default Description
container string | object <optional>
 window

A selector, DOM Object or a jQuery object that references the main container for scrolling.
vertical boolean <optional>
 true

Sets the scroll mode to vertical (true) or horizontal (false) scrolling.
globalSceneOptions object <optional>
 {}

These options will be passed to every Scene that is added to the controller using the addScene method. For more information on Scene options see ScrollScene.
loglevel number <optional>
 2

Loglevel for debugging:

  • 0 => silent
  • 1 => errors
  • 2 => errors, warnings
  • 3 => errors, warnings, debuginfo
Source:
Example
// basic initializationvar controller = new ScrollMagic();// passing optionsvar controller = new ScrollMagic({container: "#myContainer", loglevel: 3});

Methods

addScene(ScrollScene) → {ScrollMagic}

Add one ore more scene(s) to the controller.
This is the equivalent to ScrollScene.addTo(controller).

Parameters:
Name Type Description
ScrollScene ScrollScene | array

ScrollScene or Array of ScrollScenes to be added to the controller.
Source:
Returns:

Parent object for chaining.

{ ScrollMagic }
Example
// with a previously defined scenecontroller.addScene(scene);// with a newly created scene.controller.addScene(new ScrollScene({duration : 0}));// adding multiple scenescontroller.addScene([scene, scene2, new ScrollScene({duration : 0})]);

destroy(resetScenes) → {null}

Destroy the Controller, all Scenes and everything.

Parameters:
Name Type Argument Default Description
resetScenes boolean <optional>
 false

If true the pins and tweens (if existent) of all scenes will be reset.
Source:
Returns:

Null to unset handler variables.

{ null }
Example
// without resetting the scenescontroller = controller.destroy();// with scene resetcontroller = controller.destroy(true);

enabled(newState) → {boolean|ScrollMagic}

Get or Set the current enabled state of the controller.
This can be used to disable all Scenes connected to the controller without destroying or removing them.

Parameters:
Name Type Argument Description
newState boolean <optional>

The new enabled state of the controller true or false.
Source:
Returns:

Current enabled state or parent object for chaining.

{ boolean | ScrollMagic }
Example
// get the current valuevar enabled = controller.enabled();// disable the controllercontroller.enabled(false);

info(about) → {mixed|object}

Get all infos or one in particular about the controller.

Parameters:
Name Type Argument Description
about string <optional>

If passed only this info will be returned instead of an object containing all.
Valid options are:

  • "size" => the current viewport size of the container
  • "vertical" => true if vertical scrolling, otherwise false
  • "scrollPos" => the current scroll position
  • "scrollDirection" => the last known direction of the scroll
  • "container" => the container element
  • "isDocument" => true if container element is the document.
Source:
Returns:

The requested info(s).

{ mixed | object }
Example
// returns the current scroll position (number)var scrollPos = controller.info("scrollPos");// returns all infos as an objectvar infos = controller.info();

loglevel(newLoglevel) → {number|ScrollMagic}

Get or Set the current loglevel option value.

Parameters:
Name Type Argument Description
newLoglevel number <optional>

The new loglevel setting of the ScrollMagic controller. [0-3]
Source:
Returns:

Current loglevel or parent object for chaining.

{ number | ScrollMagic }
Example
// get the current valuevar loglevel = controller.loglevel();// set a new valuecontroller.loglevel(3);

removeScene(ScrollScene) → {ScrollMagic}

Remove one ore more scene(s) from the controller.
This is the equivalent to ScrollScene.remove().

Parameters:
Name Type Description
ScrollScene ScrollScene | array

ScrollScene or Array of ScrollScenes to be removed from the controller.
Source:
Returns:

Parent object for chaining.

{ ScrollMagic }
Example
// remove a scene from the controllercontroller.removeScene(scene);// remove multiple scenes from the controllercontroller.removeScene([scene, scene2, scene3]);

scrollPos(scrollPosMethod) → {number|ScrollMagic}

Get the current scrollPosition or Set a new method to calculate it.
-> GET: When used as a getter this function will return the current scroll position.
To get a cached value use ScrollMagic.info("scrollPos"), which will be updated on tick to save on performance.
For vertical controllers it will return the top scroll offset and for horizontal applications it will return the left offset.

-> SET: When used as a setter this method prodes a way to permanently overwrite the controller's scroll position calculation.
A typical usecase is when the scroll position is not reflected by the containers scrollTop or scrollLeft values, but for example by the inner offset of a child container.
Moving a child container inside a parent is a commonly used method for several scrolling frameworks, including iScroll.
By providing an alternate calculation function you can make sure ScrollMagic receives the correct scroll position.
Please also bear in mind that your function should return y values for vertical scrolls an x for horizontals.

To change the current scroll position please use ScrollMagic.scrollTo().

Parameters:
Name Type Argument Description
scrollPosMethod function <optional>

The function to be used for the scroll position calculation of the container.
Source:
Returns:

Current scroll position or parent object for chaining.

{ number | ScrollMagic }
Example
// get the current scroll Positionvar scrollPos = controller.scrollPos();// set a new scroll position calculation methodcontroller.scrollPos(function () {	return this.info("vertical") ? -$mychildcontainer.y : -$mychildcontainer.x});

scrollTo(newScrollPos) → {ScrollMagic}

Scroll to a new scroll offset, the start of a scene or provide an alternate method for scrolling.
For vertical controllers it will change the top scroll offset and for horizontal applications it will change the left offset.

  1. If a number is supplied the container will scroll to the new scroll offset.
  2. If a ScrollScene is supplied the container will scroll to the start of this scene.
  3. If a function is supplied this function will be used as a callback for future scroll position modifications.
    This provides a way for you to change the behaviour of scrolling and adding new behaviour like animation.
    The callback receives the new scroll position as a parameter and a reference to the container element using this.
Parameters:
Name Type Argument Description
newScrollPos number | ScrollScene | function <optional>

A new scroll position or a scene to scroll to. Alternative: A function to be used for future scroll position modification.
Source:
Returns:

Parent object for chaining.

{ ScrollMagic }
Example
// scroll to an offset of 100var scrollPos = controller.scrollTo(100);// scroll to the beginning of a scenevar scene = new ScrollScene({offset: 200});var scrollPos = controller.scrollTo(scene);// define a new scroll position modification function (animate instead of jump)controller.scrollTo(function (newScrollPos) {	$("body").animate({scrollTop: newScrollPos});});

update(immediately) → {ScrollMagic}

Updates the controller params and calls updateScene on every scene, that is attached to the controller.
See ScrollMagic.updateScene() for more information about what this means.
In most cases you will not need this function, as it is called constantly, whenever ScrollMagic detects a state change event, like resize or scroll.
The only application for this method is when ScrollMagic fails to detect these events.
One application is with some external scroll libraries (like iScroll) that move an internal container to a negative offset instead of actually scrolling. In this case the update on the controller needs to be called whenever the child container's position changes. For this case there will also be the need to provide a custom function to calculate the correct scroll position. See ScrollMagic.scrollPos() for details.

Parameters:
Name Type Argument Default Description
immediately boolean <optional>
 false

If true the update will be instant, if false it will wait until next tweenmax tick (better performance)
Source:
Returns:

Parent object for chaining.

{ ScrollMagic }
Example
// update the controller on next tick (saves performance)controller.update();// update the controller immediatelycontroller.update(true);

updateScene(ScrollScene, immediately) → {ScrollMagic}

Update one ore more scene(s) according to the scroll position of the container.
This is the equivalent to ScrollScene.update().
The update method calculates the scene's start and end position (based on the trigger element, trigger hook, duration and offset) and checks it against the current scroll position of the container.
It then updates the current scene state accordingly (or does nothing, if the state is already correct) – Pins will be set to their correct position and tweens will be updated to their correct progress.
Note: This method gets called constantly whenever ScrollMagic detects a change. The only application for you is if you change something outside of the realm of ScrollMagic, like moving the trigger or changing tween parameters.

Parameters:
Name Type Argument Default Description
ScrollScene ScrollScene

ScrollScene or Array of ScrollScenes that is/are supposed to be updated.
immediately boolean <optional>
 false

If true the update will be instant, if false it will wait until next tweenmax tick.
This is useful when changing multiple properties of the scene - this way it will only be updated once all new properties are set (onTick).
Source:
Returns:

Parent object for chaining.

{ ScrollMagic }
Example
// update a specific scene on next tickcontroller.updateScene(scene);// update a specific scene immediatelycontroller.updateScene(scene, true);// update multiple scenes scene on next tickcontroller.updateScene([scene1, scene2, scene3]);