A MooTools class to control the docking of items at a certain window.scroll
threshold.
var dockOptions = {
undockAt: '.feature:last-child'
}
var docker = new DockSimple('#menu', dockOptions);
This creates a new object docker
which will dock the #menu
element to the top of the screen and undock it once the user scrolls to the last .feature
div element.
There are many different ways to use DockSimple for both singular and multiple elements. Please explore the examples folder for some ideas and inspiration.
scrollElement
: (type: String, default: 'window')
What DockSimple attaches thescroll
event to. The passed in string should be an element id with which to look up indocument.id()
undockElement
: (type: Element)
The element in which DockSimple will undock it'selement
atundockAt
: (type: String, default: 'bottom')
Undocks at the 'top' or 'bottom' of it'sundockElement
dockedClass
: (type: String, default: 'docked')
The class applied to theelement
when dockedforcedClass
: (type: String, default: 'force-dock')
No docking will occur on theelement
if it has this class applied to it.dockCoordinate
: (type: Number)
If preferred, theelement
will dock when thewindow.scroll
value meets this option.dockOffset
: (type: Number, default: 0)
An amount to deduct from thetop
coordinate of the `element``undockOffset
: (type: Number, default: 0)
An amount to deduct from theundockAt
coordinate of theundockElement
replaceElement
: (type: Boolean, default: false)
A boolean to determine whether a dummy element with the same height as the givenelement
should be replaced when applyed thedockedClass
. This is really useful for preventing a 'jump' in the page when docking/undocking theelement
.dummyHide
: (type: Boolean, default: false)
Determines whether or not to hide the replacement element when undocking theelement
while scrolling down the page. Prevents the 'jump' when undocking the element.multiReplace
: (type: Boolean, default: false)
Adds a dummy replacement element for each docked element when usingDockSimple.multiDock
. This (obviously) setsreplaceElement
to true. Defaults to hiding the dummy when docking the next item to be docked, but this can be overridden by settingdummyHide
to false.active
: (type: Boolean, default: true)
A boolean of whether or not the newly initialized DockSimple object does anything. In order to activate later, call theDockSimple.activate
method.onDocked
: (type: Function, args: element [Element], elementY [Number])
Fires when docking the givenelement
.onUndocked
: (type: Function, args: element [Element], undockY [Number], dir [String])
Fires when undocking the givenelement
. Arguments passed represent theelement
, the current scroll amount of being undocked (whether from the start or end), and the direction in which the element was undocked (values will be eitherstart
orend
).
DockSimple fires two events, docked
and undocked
, both of which receive two
arguments. It's recommended to pass in whichever functions you want to fire on
those events as options onDocked
and onUndocked
. Please see above for which
arguments to expect in the given function.
The following can be invoked directly from the instantiated object returned from new DockSimple()
:
attachUndocker
: (args: undocker [String], returns: Element)
Calculates the Y coordinate value in which to undock theelement
. Returns the element instance of the passed in selector.toDock
: (returns: Boolean)
A function that calculates the docking or undocking of theelement
. Returns thedocked
state.dockElement
: (returns: this)
Applies thedockedClass
to theelement
and set the currentdocked
state astrue
undockElement
: (args: dir [String], returns: this)
Removes thedockedClass
from theelement
and set the currentdocked
state as false.dir
should be a stringstart
orend
in coordination with the direction of scrolling down the page.activate
: (args: attach [Boolean], returns: this)
Re-attaches thescrollEvent
from thewindow
if not already attached and sets theactive
state to true. Given a single argumenttrue
, will calldockElement
for immediate docking.deactivate
: (args: detach [Boolean], returns: this)
Detaches thescrollEvent
from thewindow
if already attached and sets theactive
state to false. Given a single argumenttrue
, will callundockElement
for immediate undocking.
Methods to be invoked directly on the DockSimple
class without having to
create an instance of it:
-
multiDock
: (args: selector [Element], options [Object])
Creates multiple instances ofDockSimple
for handling the docking of many elements on the page. Returns an array of the created instances of DockSimple.This will create as many
scroll
events as elements found, so be wary of doing heavy calculation in anydocked
orundocked
event triggered. You may find it useful to use the providedthrottle
anddebounce
methods when using this.The passed in selector should not have an index provided in it's string. For example: use
.menu
and not.menu[0]
as you would with maybe only one instance of DockSimple.Given the
replaceElement
option value of true but nomultiReplace
, this will not hide the dummy replacement until the first docked element is undocked from the top. That is - when scrolling down the page, the dummy will not be hidden to prevent a 'jump'. When scrolling up the page, the dummy will be hidden when the first found element in the passed inselector
is undocked.If
multiReplace
is passed in as true, dummy elements will be hidden when their docked element is undocked.
String
Added to the String
type is findElementIndex
, a easy way to pass a string
selector and index the found elements.
-
findElementIndex
: (args: selector [String], returns: Element)
Given a selector string.foo[2]
, this will find the third instance of an element with thefoo
class on the page. If nothing with the given index is found, returnsundefined
. If passed in a selector with no index provided, (example:'.foo'.findElementIndex()
), returns the first instance of the element found.example:
var docker = new DockSimple('.menu[2]', { undockAt: '.menu[3]' });
Function
Two added methods on the Function
type, throttle
and debounce
, are
available for modifying amplitude of the scrollEvent
if needed.
throttle
: (args: interval [Number], returns: Function)
Provides a throttle method to limit the amount that a function is called repetitively. Useful for minifying the amount that thescrollEvent
is called while scrolling the page.debounce
: (args: delay [Number], returns: Function)
Allows a function to prevent from being called until completed after a given delay. Great when a lot of math needs to happen on the currentscrollY
but not until after scrolling has finished.