Scrollable acts on a single element. It calculates a scroll depth for the element (the top edge by default), and the window has tha scrollTop value which is greater than this, the element is determined to be scrolled. A scrolled element then has a class added to it ("scrolled" by default).
Certain can change the default behaviour of Scrollable to make it highly customisable. Elements can have target elements, which also receive the same class when the initial element's scroll depth is reached. The scroll depth can be altered by adding a fixed value to it, or instead of using the top of the element as the base for the depth, it can be changed to use the bottom of the element, or the very top of the page.
In essence, Scrollable detects when the top of an element enters the bottom of the page. Another useful feature is that Scrollable can create an opposing version of itself, to detect when the same element exits the page. The default behaviour of this is that it will receive all the same settings, but add a different class ("unscrolled" by default) when the bottom of the element exits the top of the page.
Scrollable also has directional detection. Turned on by default, it will add a class to each scrollable element to show if the page is moving upwards or downwards.
Initialisation has been intentionally left manual for scrollable. Because it binds to a scroll event, it is advisable to use a throttle to handle the trigger. Scrollable doesn't force you to, nor does it force you to use a specifc throttle, although one is available as part of the AbleJS library (see ThrottlableJS). To avoid this forced behaviour, however, means binding is a manual process. This is simply achieved in the following way.
Script binding
HTML elements should have a data-plugin attribute set to "scrollable".
<elem data-plugin="scrollable"></elem>
This will allow for detection when the following script is fired. Note that the scrollEventType can be either a scroll, or a throttled scroll event. Element will also depend on where the throttled scroll event is triggered, however, without a throttle, this element should be window.
$([element]).on([scrollEventType], function () {
$('[data-plugin=scrollable]').trigger('scrollable');
//OR
$('[data-plugin=scrollable]').scrollable();
});
$(elem).scrollable([object settings | string method, object event])
.scrollable() is attached to the jQuery library, so you can call this on any element. If nothing is passed in, it will initialise Scrollable, and trigger a check of the current scroll position. Note that without directly calling this on a scroll event, Scrollable will not fire again until it is called directly like this again. It is therefore advisable that this method only be used inside an event handler, as shown above.
$('[data-plugin=scrollable]').scrollable({
target: "body, .side-nav",
classname: "scrolled",
directional: true
});
<elem data-[setting]="[value]"></elem>
The data- attribute can be used to affect the settings of the Scrollable instance as well. Any settings to be passed in can be added directly to the initializing element by prefixing them with data- and setting them to a valid value for that property.
Example:
<section data-plugin="scrollable" data-target="body, .side-nav" data-offclassname="unscrolled" data-directional="true" data-classname="scrolled">Content...<section>
string classname
Default: "scrolled"
Specify a custom css class to run your CSS from. This class will be applied once the window has been scrolled to the specified depth.
selector target
Default: false
Specify any targets as a css selector. Upon click, they will also receive the classname value and can be styled accordingly. To include multiples, use a comma separator as you would in standard css selectors.
bool absolute
Default: false
changes the way scroll depth is calculated. If absolute is false, it will calculate from the the top edge of the element. If true, it will calculate from the top of the page (this will be 0 unless a depth is set as well).
number depth
Default: 0
By default, the scroll depth will be a calculated figure that determines the top edge of the element in question. If a depth is set, this will be added to this calculated figure at the point of initialisation.
number ambiguity
Default: 0
Similar to depth, but this number is deducted from the depth at the point of checking whether the element is within the scroll position or not. It can be positive or negative to adjust either side.
string edge
Default: "top"
"bottom" will change the default depth calculation so it determines the bottom edge of the element instead of the top edge.
bool oppose
Default: false
When set to true, a second instance of Scrollable will be initialized to handle an "off" class. This by default is the depth of the first instance plus the instanciating element's height. Any CSS targeting the window of time when an element is within depth of both instances of Scrollable (i.e. when it enter the page but before it exits again) should target elements with both the classname and the offclassname.
string offclassname
Default: "unscrolled"
Specify a custom css class to run your CSS from. This class will be applied by the opposing scrollable instance once the window has been scrolled to its specified depth.
number ambiguityafter
Default: 0
Adjusts the default depth of the opposing instance of Scrollable. This number gets deducted from the offset of the bottom of the instanciating element's height. It can be positive or negative to adjust either way.
number minwidth
Default: 0
Represents the minimum width at which Scrollable is allowed to operate. To turn Scrollable off on mobiles for instance, minwidth should be set to 520.
bool add
Default: true
If true, when Scrollable recognizes the scroll depth has been reach it will add the classname to the element. If false, it will remove it. The value of this is reversed for any opposing instance of Scrollable.
bool directional
Default: true
If true, this adds a class to all Scrollable elements and targets to identify if the user is scrolling up or down.
string classup
Default: "up"
The class to be added if the user scroll direction is determined to be up the page.
string classdown
Default: "down"
The class to be added if the user scroll direction is determined to be down the page.
number directionalambiguity
Default: 50
The number of pixels to allow a user to scroll in either direction without Scrollable updating the directional determination. Having this set at 0 can cause unintentional direction changes, and cause interactions to be jumpy.