jQuery plug-in providing advanced scroll events. These might, for example, trigger an event, whenever a window or frame content has been scrolled up or down by at least a certain amount of pixels, optionally only after a change of the scroll direction.
This software module contains a jQuery plug-in building on jQuery's native
scroll event: By applying jQuery's .scroll() method to selected scrollable content (typically, but not limited to,
$(window)), you may register an event handler wich gets called whenever the content is scrolled. With jQuery's methods scrollTop resp. scrollLeft the event handler may then determine the acutal position of the viewport.
For many purposes, those native functions are ‘a bit low-level’, and this plug-in builds upon them in order to define ‘higher-level’ events such as: User has scrolled upwards for at least 20px for the first time after scrolling downwards. The plug-in provides a couple of options (like the 20px threshold in the previous example) which, among others, help prevent accidentally triggering events only due un impreciseness (such as minimal scrolling movements caused by a user just laying his finger onto a touch screen with a little, unintended movement).
This project contains one demo page named
demo.html, which contains some demonstrations. As one possible use-case, it shows how tool bars or panels may be hidden (e.g. on a mobile site layout) when the user scrolls down, probably reading the text of the page, whereas the panels are shown again, whenever the user scrolls upwards or reaches the bottom of the page, assuming that in both cases he doesn't read the main content any more and should be provided with more means of interaction.
Feel encouraged to make copies of the demo file play around with the options to see what happens.
js/jquery-advscrollevent.jsis the original, uncompressed script file. It also contains comments to document its usage.
js/min/jquery-advscrollevent-min.jsis a minified (compressed) version of the previous script for production use.
Include jQuery (tested with jQuery 2.1.14, but should work with newer versions, too, as well as with current jQuery 1 versions) and one of the two script files of this package into the head of your HTML file. (For production on a web server, the minified version is recommended, while the source version might be better for development, since it's easier to debug and contains a short usage reference.)
Write and include some script code that gets executed after rendering the HTML (generating the DOM). This code is to select a scrollable element and apply the plug-in function
advScroll() to the jQuery resultset in order to register one or more event handlers. Usually, the scrollable element is the whole web page, selected by
$(window), but you may select any scrollable node where the original scroll() function is applicable.
advScroll function takes one object as an argument, which should at least contain one event handler function for at least one of the advanced events this plug-in provides. Example:
For each selected element (a jQuery resultset can contains more than one) the plug-in registers a scroll event handler which guards any scroll movement in order to trigger its own event(s) whenever the conditions are met.
As already established above, the
onUp(event, diff, scrollTop): function (default:
upBypixels (see option
upByin the next section). (In horizontal mode—see
horizontal—this event is triggered upon scrolling to the left instead of upwards.)
eventis the original scroll event,
diffis the amount of pixels scrolled up since last scrolling down,
scrollTopis the element's new absolute scrollTop value.
thisis bound to the sender object, e.g.
onDown(event, diff, scrollTop): function (default:
onTop: boolean or function (default:
onUp-function gets called upon reaching the top (resp. left end) of the page.
function, this very function gets called upon reaching the top of the page. (The function's arguments are the same as those of
onBottom: boolean or function (default:
onTop, just referring to the bottom (resp. right end) of the page. If
onDownhandler is re-used, if a function is assigned, that will be used as event handler.
onBottomevent needs to find the element containing the scrollable content in order to calculate its height (or width in horizontal mode). If the jQuery plug-in is not applied to
$(window), but to some other scrollable content like a DIV with CSS
overflow:scroll, the content of that container has to be specified in the
scrollableContentproperty in order for the
onBottomevent to work properly!
upBy: number (default: 20)
onUp-Event is fired.
downBy: number (default: 20)
onDown-Event is fired.
scrollableContent: jQuery resultset or (selector-)string (default:
onBottomevent is used and ony when applied to something other than
$(window), the default (
$(document)) is correct, but if you call the plug-in e.g. on some DIV elements with CSS
overflow: auto, the content of those DIVs have to be wrapped in another element which is then to be selected as
scrollableContent. If this is exactly one element, you may "preselect" it and assign the jQuery resultset to this property (as is the default
$(document)). Otherwise you may simply assign a jQuery selector string which will then be executed locally inside the container element. See demo.
oncePerDirection: boolean (default: false)
false, the events
onDownfire continuously once the
downBythreshold has been crossed.
onDownevent is fired at most once until changing the direction.
directionChangeDelayMillis: number (default: 50)
onDownevent will fire after scrolling
downBypixels into the new direction.
directionChangeDelayMillismilli seconds: This will not trigger a
onUp-event, in ‘continuous mode’ (i.e.
oncePerDirection==false) it will still trigger the
onDownevent even though you're scrolling upwards, as this is still regarded as part of the same scrolling movement, a small irregularity, so to speek. However, if you keep scrolling up further and reach the point again, where you started to scroll down or you scroll up for at least
directionChangeThresholdpixels (see below), this upwards movement is no longer regarded as probably unintended irregularity, but as an intended direction change despite the page not having stood still for
directionChangeThreshold: number (default: 500)
directionChangeDelayMillisis > 0, this threshold describes the maximum number of pixels a scrolling movement into the opposite direction without waiting for the specified timeout will not be regarded as direction change. In other words: When suddenly changing the scrolling direction and scrolling back for more pixels than specified here, a direction change will be recognised even if the
directionChangeDelayMillistimeout has not yet been exceeded and even if the initial scrolling motion had begun in a greater distance, i.e you didn't scroll back to where the motion started.
horizontal: boolean (default: false)
onUprefers to scrolling to the left,
onDownto scrolling to the right etc.
If you want to configure the
directionChangeDelayMillis settings separately for both scrolling directions, you may use the following options:
oncePerUp: boolean (default:
oncePerDirectionsetting for scrolling upwards.
oncePerDown: boolean (default:
oncePerDirectionsetting for scrolling downwards.
downUpDelayMillis: number (default:
directionChangeDelayMillissetting for the transition from scrolling downwards to scrolling upwards.
upDownDelayMillis: number (default:
directionChangeDelayMillissetting for the transition from scrolling upwards to scrolling downwards.
The descriptions for the options above contain default values wich apply, if you don't add that option key to the argument object you pass to the plug-in function.
Any defaults (except the
undefined ones) are taken from the object
It is possible for you to override these defaults by simply modifying said object before first calling the plug-in function.
Copyright (c) 2016, Immo Schulz-Gerlach, www.isg-software.de
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.