Skip to content

Commit

Permalink
Merge branch 'v2.3.0'. Fixes #8
Browse files Browse the repository at this point in the history
  • Loading branch information
@Amphiluke
Amphiluke committed Jan 2, 2017
2 parents 956a2f2 + 9bdb5f5 commit a9ac126
Show file tree
Hide file tree
Showing 6 changed files with 92 additions and 51 deletions.
42 changes: 37 additions & 5 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# floating-scroll

### The Crux of the Matter
## The Crux of the Matter

The general purpose of the plugin is to provide some lengthy containers on the page with a separate horizontal scroll bar, which does not vanish from sight when the entire page is scrolled. So, the user will always be able to scroll the container even if its own scroll bar is hidden from view.

Moreover, the plugin displays such an additional floating scroll bar only in case of actual need, i.e. the floatingScroll does not result in unnecessary scroll bar duplication. So, one uses the floating scroll bar only if the “native” one is out of sight.

### Details & API
## Details & API

There is the only public method used to instantiate and control a floating scroll — `.floatingScroll()` (note that the old method alias `attachScroll` is kept for backward compatibility, but it will be removed in future versions). The plugin method `.floatingScroll()` should be called in context of a scrollable container. It takes an optional argument `method`. The currently supported methods are

Expand All @@ -16,7 +16,13 @@ There is the only public method used to instantiate and control a floating scrol

You may also trigger events `update.fscroll` and `destroy.fscroll` for containers with attached floating scroll bar: this does the same as invoking the corresponding methods.

### Examples
## Usage

### Inclusion of plugin files

The plugin requires the CSS file [jquery.floatingscroll.css](src/jquery.floatingscroll.css) to be included on the page (you may also import it in your CSS/LESS files). The plugin's script file [jquery.floatingscroll.min.js](src/jquery.floatingscroll.min.js) may be added on the web page either via a separate `<script>` element or it may be loaded by any AMD/CommonJS compatible module loader. This is a jQuery plugin so be sure that this library is added and accessible.

### Initialisation

The only thing required to apply the floatingScroll to a static container (whose sizes will never change during the session) is a single call of the `.floatingScroll()` method on the DOM ready event:

Expand All @@ -26,6 +32,8 @@ $(document).ready(function () {
});
```

### Updating scroll bar

If you attach a floating scroll bar to a container whose size and/or content may dynamically change, then you need a way to update the scroll bar each time the container changes. This can be done by invoking the method `update` as in example below.

```javascript
Expand All @@ -36,16 +44,40 @@ $("#refresh-button").click(function () {
});
```

### Destroying floating scroll bar

To detach a scroll bar and remove all related event handlers, use the method `destroy` as follows:

```javascript
$(".spacious-container").floatingScroll("destroy");
```

### Live demos
### Special cases

If you want to attach a floating scroll bar to a container living in a positioned box (e.g. a modal popup with `position: fixed`) then you need to apply two special indicating class names in the markup. The plugin detects these indicating class names (they are prefixed with `fl-scrolls-`) and switches to a special functioning mode.

```html
<div class="fl-scrolls-viewport"><!-- (1) -->
<div class="fl-scrolls-body"><!-- (2) -->
<div class="spacious-container">
<!-- Horizontally wide contents -->
</div>
</div>
</div>
```

The `.fl-scrolls-viewport` element (1) is a positioned block (with any type of positioning except `static`) which serves for correct positioning of the floating scroll bar. Note that this element itself should _not_ be scrollable. The `.fl-scrolls-body` element (2) is a vertically scrollable block (with `overflow: auto`) which encloses the target block the plugin is applied to. After applying these special class names, you may initialise the plugin as usual:

```javascript
$(".spacious-container").floatingScroll();
```

The plugin's CSS provides some basic styles for elements with classes `.fl-scrolls-viewport` and `.fl-scrolls-body`. Feel free to adjust their styles in your stylesheets as needed.

## Live demos

You may find some demos of use the floatingScroll plugin [here](http://amphiluke.github.io/floating-scroll/).

### Previous versions
## Previous versions

Prior to v2.2.0, the plugin was the part of the [jquery-plugins](https://github.com/Amphiluke/jquery-plugins) repo. If for some purpose you want to get commit history for older plugin versions, you can [extract](https://github.com/Amphiluke/jquery-plugins/commits/master/src/floatingscroll) it from that “old” repo.
2 changes: 1 addition & 1 deletion floating-scroll.jquery.json
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "floating-scroll",
"title": "floatingScroll",
"version": "2.2.5",
"version": "2.3.0",
"description": "A lightweight jQuery plugin providing floating scrollbar functionality",
"keywords": [
"scrollbar",
Expand Down
8 changes: 4 additions & 4 deletions package.json
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
{
"name": "floating-scroll",
"version": "2.2.5",
"version": "2.3.0",
"description": "A lightweight jQuery plugin providing floating scrollbar functionality",
"main": "src/jquery.floatingscroll.js",
"style": "src/jquery.floatingscroll.css",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1",
"minify": "uglifyjs src/jquery.floatingscroll.js -c -m --comments -o src/jquery.floatingscroll.min.js"
"minify": "uglifyjs src/jquery.floatingscroll.js -c -m -o src/jquery.floatingscroll.min.js"
},
"repository": {
"type": "git",
Expand All @@ -27,7 +27,7 @@
"jquery": ">=1.4.3"
},
"devDependencies": {
"eslint": "^3.7.0",
"uglify-js": "^2.6.2"
"eslint": "^3.12.2",
"uglify-js": "^2.7.5"
}
}
12 changes: 12 additions & 0 deletions src/jquery.floatingscroll.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,4 +19,16 @@
}
.fl-scrolls-hidden {
bottom:9999px;
}

.fl-scrolls-viewport {
/* It can be any type of positioning except static. Redefine in your CSS as needed */
position:relative;
}
.fl-scrolls-body {
overflow:auto;
}
.fl-scrolls-viewport .fl-scrolls {
left:0;
position:absolute;
}
77 changes: 37 additions & 40 deletions src/jquery.floatingscroll.js
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
/*!
* jQuery floatingScroll Plugin v2.2.5
* jQuery floatingScroll Plugin v2.3.0
* supported by jQuery v1.4.3+
*
* https://github.com/Amphiluke/floating-scroll
* http://amphiluke.github.io/floating-scroll/
*
* Copyright (c) 2011-2016 Amphiluke
* Copyright (c) 2011-2017 Amphiluke
*/
(function (global, factory) {
"use strict";
Expand All @@ -17,37 +17,36 @@
factory(global.jQuery);
}
}(this, function ($) {

"use strict";

var wnd = window,
getMaxVisibleY = /*@cc_on (@_jscript_version<9)?function(){var e=document.documentElement;return e.scrollTop+e.clientHeight;}:@*/function () {return wnd.pageYOffset + wnd.innerHeight;};


function FScroll(cont) {
var inst = this;
inst.cont = {block: cont[0], left: 0, top: 0, bottom: 0, height: 0, width: 0};
var inst = this,
scrollBody = cont.closest(".fl-scrolls-body");
inst.cont = cont[0];
if (scrollBody.length) {
inst.scrollBody = scrollBody;
}
inst.sbar = inst.initScroll();
inst.visible = true;
inst.updateAPI(); // recalculate floating scrolls and hide those of them whose containers are out of sight
inst.syncSbar(cont[0]);
inst.syncSbar(inst.cont);
inst.addEventHandlers();
}

$.extend(FScroll.prototype, {

initScroll: function () {
var flscroll = $("<div class='fl-scrolls'></div>");
$("<div></div>").appendTo(flscroll).css({width: this.cont.block.scrollWidth + "px"});
return flscroll.appendTo(this.cont.block);
$("<div></div>").appendTo(flscroll).css({width: this.cont.scrollWidth + "px"});
return flscroll.appendTo(this.cont);
},

addEventHandlers: function () {
var inst = this,
handlers,
i, len;
handlers = inst.eventHandlers = [
{
$el: $(wnd),
$el: inst.scrollBody || $(window),
handlers: {
// Don't use `$.proxy()` since it makes impossible event unbinding individually per instance
// (see the warning at http://api.jquery.com/unbind/)
Expand All @@ -62,12 +61,12 @@
}
},
{
$el: $(inst.cont.block),
$el: $(inst.cont),
handlers: {
scroll: function () {inst.syncSbar(this, true);},
focusin: function () {
setTimeout(function () {
inst.syncSbar(inst.cont.block);
inst.syncSbar(inst.cont);
}, 0);
},
// The `adjustScroll` event type is kept for backward compatibility only.
Expand All @@ -89,33 +88,36 @@
handlers[i].$el.bind(handlers[i].handlers);
}
},

checkVisibility: function () {
var inst = this,
cont = inst.cont,
mustHide = (inst.sbar[0].scrollWidth <= inst.sbar[0].offsetWidth),
contRect,
maxVisibleY;
if (!mustHide) {
maxVisibleY = getMaxVisibleY();
mustHide = ((cont.bottom <= maxVisibleY) || (cont.top > maxVisibleY));
contRect = inst.cont.getBoundingClientRect();
maxVisibleY = inst.scrollBody
? inst.scrollBody[0].getBoundingClientRect().bottom
: window.innerHeight || document.documentElement.clientHeight;
mustHide = ((contRect.bottom <= maxVisibleY) || (contRect.top > maxVisibleY));
}
if (inst.visible === mustHide) {
inst.visible = !inst.visible;
inst.visible = !mustHide;
// we cannot simply hide a floating scroll bar since its scrollLeft property will not update in that case
inst.sbar.toggleClass("fl-scrolls-hidden");
}
},

syncCont: function (sender, preventSyncSbar) {
// Prevents next syncSbar function from changing scroll position
if (this.preventSyncCont === true) {
this.preventSyncCont = false;
return;
}
this.preventSyncSbar = !!preventSyncSbar;
this.cont.block.scrollLeft = sender.scrollLeft;
this.cont.scrollLeft = sender.scrollLeft;
},

syncSbar: function (sender, preventSyncCont) {
// Prevents next syncCont function from changing scroll position
if (this.preventSyncSbar === true) {
Expand All @@ -125,23 +127,20 @@
this.preventSyncCont = !!preventSyncCont;
this.sbar[0].scrollLeft = sender.scrollLeft;
},

// Recalculate scroll width and container boundaries
updateAPI: function () {
var inst = this,
cont = inst.cont,
block = $(cont.block),
pos = block.offset();
cont.height = block.outerHeight();
cont.width = block.outerWidth();
cont.left = pos.left;
cont.top = pos.top;
cont.bottom = pos.top + cont.height;
inst.sbar.width(cont.width).css("left", pos.left + "px");
$("div", inst.sbar).width(block[0].scrollWidth);
pos = cont.getBoundingClientRect();
inst.sbar.width($(cont).outerWidth());
if (!inst.scrollBody) {
inst.sbar.css("left", pos.left + "px");
}
$("div", inst.sbar).width(cont.scrollWidth);
inst.checkVisibility(); // fixes issue #2
},

// Remove a scrollbar and all related event handlers
destroyAPI: function () {
var handlers = this.eventHandlers,
Expand All @@ -151,9 +150,8 @@
}
this.sbar.remove();
}

});

// `attachScroll` is the old alias used in v1.X. Temporally kept for backward compatibility.
$.fn.attachScroll = $.fn.floatingScroll = function (method) {
if (!arguments.length || method === "init") {
Expand All @@ -165,5 +163,4 @@
}
return this;
};

}));
2 changes: 1 addition & 1 deletion src/jquery.floatingscroll.min.js
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

0 comments on commit a9ac126

Please sign in to comment.