-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.html
145 lines (111 loc) · 14.1 KB
/
README.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8"/>
</head>
<body>
<h1 id="advscrollevent">advscrollevent</h1>
<p>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.</p>
<p><a href="http://www.isg-software.de/advscrollevent/indexe.html">Project home page</a></p>
<h2 id="whatisthis">What is this?</h2>
<p>This software module contains a <a href="https://jquery.com">jQuery</a> plug-in building on jQuery’s native <code>scroll</code> event: By applying jQuery’s <a href="http://api.jquery.com/scroll/">.scroll()</a> method to selected scrollable content (typically, but not limited to, <code>$(window)</code>), you may register an event handler wich gets called whenever the content is scrolled. With jQuery’s methods <a href="http://api.jquery.com/scrollTop/">scrollTop</a> resp. <a href="http://api.jquery.com/scrollLeft/">scrollLeft</a> the event handler may then determine the acutal position of the viewport.</p>
<p>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).</p>
<h2 id="examples">Examples</h2>
<p>This project contains one demo page named <code>demo.html</code>, 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.</p>
<p>Open the demo page in a browser to try out the example configuration, see the html source (including embedded javascript) to see how the configuration was done.</p>
<p>Feel encouraged to make copies of the demo file play around with the options to see what happens.</p>
<h2 id="javascripts">JavaScripts</h2>
<ul>
<li><code>js/jquery-advscrollevent.js</code> is the original, uncompressed script file. It also contains comments to document its usage.</li>
<li><code>js/min/jquery-advscrollevent-min.js</code> is a minified (compressed) version of the previous script for production use.</li>
</ul>
<h2 id="usage">Usage</h2>
<h3 id="basics">Basics</h3>
<ul>
<li><p>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.)</p></li>
<li><p>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 <code>advScroll()</code> to the jQuery resultset in order to register one or more event handlers. Usually, the scrollable element is the whole web page, selected by <code>$(window)</code>, but you may select any scrollable node where the original <a href="http://api.jquery.com/scroll/">scroll()</a> function is applicable.</p></li>
<li><p>The <code>advScroll</code> 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:</p>
<pre><code><script type="text/javascript">
$(function() {
$(window).advScroll({
onUp: function(evt, px, top) {...},
onDown: function(evt, px, top) {...}
oncePerDirection: true
});
});
</script>
</code></pre></li>
<li><p>For each selected element (a jQuery resultset can contains more than one) the plug-in registers a <a href="http://api.jquery.com/scroll/">scroll</a> event handler which guards any scroll movement in order to trigger its own event(s) whenever the conditions are met.</p></li>
</ul>
<h3 id="options">Options</h3>
<p>As already established above, the <code>advScroll()</code> function takes exactly one argument, which has to be a JavaScript object defining options via its properties. The following option properties are defined:</p>
<h4 id="optionsforeventhandlerfunction">Options for event handler function</h4>
<ul>
<li><code>onUp(event, diff, scrollTop)</code>: function (default: <code>null</code>)<br/>
Event handler function called when user has scrolled up for at least <code>upBy</code> pixels (see option <code>upBy</code> in the next section). (In <em>horizontal mode</em>—see <code>horizontal</code>—this event is triggered upon scrolling to the left instead of upwards.)<br/>
Arguments:
<ul>
<li><code>event</code> is the original scroll event,</li>
<li><code>diff</code> is the amount of pixels scrolled up since last scrolling down,</li>
<li><code>scrollTop</code> is the element’s new absolute scrollTop value.</li>
<li><code>this</code> is bound to the sender object, e.g. <code>window</code>.</li>
</ul></li>
<li><code>onDown(event, diff, scrollTop)</code>: function (default: <code>null</code>)<br/>
Event handler function called when user has scrolled down (or to the right in <em>horizontal mode</em>) for at least <code>downBy</code> pixels, see <code>onUp</code>.</li>
<li><code>onTop</code>: boolean or function (default: <code>false</code>)<br/>
If <code>true</code>, the <code>onUp</code>-function gets called upon reaching the top (resp. left end) of the page.<br/>
If a <code>function</code>, this very function gets called upon reaching the top of the page. (The function’s arguments are the same as those of <code>onUp</code>.)</li>
<li><code>onBottom</code>: boolean or function (default: <code>false</code>)<br/>
See <code>onTop</code>, just referring to the bottom (resp. right end) of the page. If <code>true</code>, the <code>onDown</code> handler is re-used, if a function is assigned, that will be used as event handler.<br/>
<strong>Important</strong>: The <code>onBottom</code> event 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 <em>not</em> applied to <code>$(window)</code>, but to some other scrollable content like a DIV with CSS <code>overflow:scroll</code>, the content of that container has to be specified in the <code>scrollableContent</code> property in order for the <code>onBottom</code> event to work properly!<br/>
<strong>Note:</strong> This event is not guaranteed to work precisely in every browser, at least not in the current state of the plug-in!</li>
</ul>
<h4 id="otheroptions">Other options</h4>
<ul>
<li><code>upBy</code>: number (default: 20)<br/>
Amount of pixels to at least scroll up since last scrolling down before the <code>onUp</code>-Event is fired.</li>
<li><code>downBy</code>: number (default: 20)<br/>
Amound of pixels to at least scroll down since loading doc or scrolling up before the <code>onDown</code>-Event is fired.</li>
<li><code>scrollableContent</code>: jQuery resultset or (selector-)string (default: <code>$(document)</code>)<br/>
Currently only needed if the <code>onBottom</code> event is used and ony when applied to something other than <code>$(window)</code>.<br/>
If the plug-in function is called on <code>$(window)</code>, the default (<code>$(document)</code>) is correct, but if you call the plug-in e.g. on some DIV elements with CSS <code>overflow: scroll</code> or <code>overflow: auto</code>, the content of those DIVs have to be wrapped in another element which is then to be selected as <code>scrollableContent</code>. If this is exactly one element, you may “preselect” it and assign the jQuery resultset to this property (as is the default <code>$(document)</code>). Otherwise you may simply assign a jQuery selector <em>string</em> which will then be executed locally inside the container element. See demo.</li>
<li><code>oncePerDirection</code>: boolean (default: false)<br/>
If <code>false</code>, the events <code>onUp</code> resp. <code>onDown</code> fire continuously once the <code>upBy</code> resp. <code>downBy</code> threshold has been crossed.<br/>
If true, an <code>onUp</code> or <code>onDown</code> event is fired at most once until changing the direction.</li>
<li><code>directionChangeDelayMillis</code>: number (default: 50)<br/>
If zero (0), any change of scroll direction will immediately be treated as a “direction change”, meaning the corresponding <code>onUp</code> or <code>onDown</code> event will fire after scrolling <code>upBy</code> resp. <code>downBy</code> pixels into the new direction.<br/>
If greater than zero, this defines a delay in milli seconds which the page needs to stand still before a direction change.<br/>
Example: You are scrolling downwards, then suddenly you scroll upwards for a bit without waiting for at least <code>directionChangeDelayMillis</code> milli seconds: This will not trigger a <code>onUp</code>-event, in <em>‘continuous mode’</em> (i.e. <code>oncePerDirection==false</code>) it will still trigger the <code>onDown</code> event 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 <code>directionChangeThreshold</code> pixels (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 <code>directionChangeDelayMillis</code>!</li>
<li><code>directionChangeThreshold</code>: number (default: 500)<br/>
If <code>directionChangeDelayMillis</code> is > 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 <code>directionChangeDelayMillis</code> timeout 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.<br/>
If zero (0), this setting will be ignored.</li>
<li><code>horizontal</code>: boolean (default: false)<br/>
If set to true, the plugin works for horizontal instead of vertical scrolling. All properties keep their names, <code>onUp</code> refers to scrolling to the left, <code>onDown</code> to scrolling to the right etc.</li>
</ul>
<p>If you want to configure the <code>oncePerDirection</code> or <code>directionChangeDelayMillis</code> settings separately for both scrolling directions, you may use the following options:</p>
<ul>
<li><code>oncePerUp</code>: boolean (default: <code>undefined</code>)<br/>
If defined, this setting overrides the <code>oncePerDirection</code> setting for scrolling upwards.</li>
<li><code>oncePerDown</code>: boolean (default: <code>undefined</code>)<br/>
If defined, this setting overrides the <code>oncePerDirection</code> setting for scrolling downwards.</li>
<li><code>downUpDelayMillis</code>: number (default: <code>undefined</code>)<br/>
If defined, this setting overrides the <code>directionChangeDelayMillis</code> setting for the transition from scrolling downwards to scrolling upwards.</li>
<li><code>upDownDelayMillis</code>: number (default: <code>undefined</code>)<br/>
If defined, this setting overrides the <code>directionChangeDelayMillis</code> setting for the transition from scrolling upwards to scrolling downwards.</li>
</ul>
<h3 id="overwritingdefaultoptions">Overwriting default options</h3>
<p>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.</p>
<p>Any defaults (except the <code>undefined</code> ones) are taken from the object <code>$.fn.advScroll.defaults</code>.</p>
<p>It is possible for you to override these defaults by simply modifying said object before first calling the plug-in function.</p>
<h2 id="license:bsd2-clause">License: BSD 2-clause</h2>
<p>Copyright (c) 2016, Immo Schulz-Gerlach, www.isg-software.de<br/>
All rights reserved.</p>
<p>Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:</p>
<ol>
<li><p>Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.</p></li>
<li><p>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.</p></li>
</ol>
<p>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.</p>
</body>
</html>