/DockSimple

A MooTools class to dock elements while scrolling the page

Primary LanguageCoffeeScript

DockSimple

A MooTools class to control the docking of items at a certain window.scroll threshold.

How to use

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.

Options

  • scrollElement: (type: String, default: 'window')
    What DockSimple attaches the scroll event to. The passed in string should be an element id with which to look up in document.id()
  • undockElement: (type: Element)
    The element in which DockSimple will undock it's element at
  • undockAt: (type: String, default: 'bottom')
    Undocks at the 'top' or 'bottom' of it's undockElement
  • dockedClass: (type: String, default: 'docked')
    The class applied to the element when docked
  • forcedClass: (type: String, default: 'force-dock')
    No docking will occur on the element if it has this class applied to it.
  • dockCoordinate: (type: Number)
    If preferred, the element will dock when the window.scroll value meets this option.
  • dockOffset: (type: Number, default: 0)
    An amount to deduct from the top coordinate of the `element``
  • undockOffset: (type: Number, default: 0)
    An amount to deduct from the undockAt coordinate of the undockElement
  • replaceElement: (type: Boolean, default: false)
    A boolean to determine whether a dummy element with the same height as the given element should be replaced when applyed the dockedClass. This is really useful for preventing a 'jump' in the page when docking/undocking the element.
  • dummyHide: (type: Boolean, default: false)
    Determines whether or not to hide the replacement element when undocking the element 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 using DockSimple.multiDock. This (obviously) sets replaceElement to true. Defaults to hiding the dummy when docking the next item to be docked, but this can be overridden by setting dummyHide 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 the DockSimple.activate method.
  • onDocked: (type: Function, args: element [Element], elementY [Number])
    Fires when docking the given element.
  • onUndocked: (type: Function, args: element [Element], undockY [Number], dir [String])
    Fires when undocking the given element. Arguments passed represent the element, 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 either start or end).

Events

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.

Instance Methods

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 the element. Returns the element instance of the passed in selector.
  • toDock: (returns: Boolean)
    A function that calculates the docking or undocking of the element. Returns the docked state.
  • dockElement: (returns: this)
    Applies the dockedClass to the element and set the current docked state as true
  • undockElement: (args: dir [String], returns: this)
    Removes the dockedClass from the element and set the current docked state as false. dir should be a string start or end in coordination with the direction of scrolling down the page.
  • activate: (args: attach [Boolean], returns: this)
    Re-attaches the scrollEvent from the window if not already attached and sets the active state to true. Given a single argument true, will call dockElement for immediate docking.
  • deactivate: (args: detach [Boolean], returns: this)
    Detaches the scrollEvent from the window if already attached and sets the active state to false. Given a single argument true, will call undockElement for immediate undocking.

Class Methods

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 of DockSimple 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 any docked or undocked event triggered. You may find it useful to use the provided throttle and debounce 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 no multiReplace, 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 in selector is undocked.

    If multiReplace is passed in as true, dummy elements will be hidden when their docked element is undocked.

Provided

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 the foo class on the page. If nothing with the given index is found, returns undefined. 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 the scrollEvent 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 current scrollY but not until after scrolling has finished.