Merge branch 'v3.2.0'

CONTRIBUTING.md

@@ -2,20 +2,20 @@
 
 ## Reporting an issue
 
-If you have found a bug please feel free to report an issue after ensuring that there is no such bug yet (check [existing issues](https://github.com/Amphiluke/floating-scroll/issues) first). Be sure to write a clear description of the problem. It will be great if you also provide a minimum example revealing the bug. You may use such services as [JSFiddle](https://jsfiddle.net/) and [RawGit](https://rawgit.com/) to assemble a live demo for the issue you found.
+If you have found a bug, please feel free to report an issue after ensuring that there is no such bug yet (check [existing issues](https://github.com/Amphiluke/floating-scroll/issues) first). Be sure to write a clear description of the problem. It will be great if you also provide a minimum example revealing the bug. You may use such services as [CodePen](https://codepen.io/) or [JSFiddle](https://jsfiddle.net/) and [unpkg](https://unpkg.com/) to assemble a live demo for the issue you’ve found.
 
 ## Making changes in code and opening a pull request
 
-If you know the way to fix some bug or just to make the plugin better then you are welcome to open a pull request. Please provide a clear and detailed description of what do your changes fix or improve, or refer an existing issue containing such an explanation.
+If you know the way to fix some bug or just to make the plugin better, you are welcome to open a pull request. Please provide a clear and detailed description of what do your changes fix or improve, or refer an existing issue containing such an explanation.
 
 Before submitting a new pull request be sure to do the following things.
 
 * Ensure that your changes do not break existing features.
-* Test your changes in different browsers: Chrome, Firefox, Safari, Opera, Internet Explorer, and Edge.
+* Test your changes in different browsers: Chrome, Firefox, Safari, Opera, and Edge.
 * Note that the plugin is currently compatible with ancient versions of jQuery (1.4.3+). If your changes break this compatibility please think if you can rewrite your code to keep compatibility unaffected. However if your changes are so important and cool that they outweigh all benefits of supporting ancient versions of jQuery then it is possible to soften this requirement within reasonable limits.
 * Before committing your changes please make sure that the plugin sources pass ESLint checks. Just use the command `npm run lint` in the project directory (of course, you need to install the project first by executing `npm install`). Fix any problems reported by ESLint before submitting a pull request.
 * Do not forget to update the minified version of the plugin sources. Use the command `npm run build` for that.
 
-Thanks for contribution! :tea:
+Thanks for your contribution! :tea:
 
 Amphiluke

README.md

@@ -12,11 +12,12 @@ The general purpose of the plugin is to provide some lengthy containers on the p
 
 ## Details & API
 
-There is the only public method used to instantiate and control a floating scrollbar — `.floatingScroll()`. The plugin method `.floatingScroll()` should be called in context of a scrollable container. It takes an optional argument `method`. The currently supported methods are
+There is the only public method used to instantiate and control a floating scrollbar — `.floatingScroll()`. Unless otherwise indicated, the plugin method `.floatingScroll()` should be called in context of a scrollable container. It takes an optional argument `method`. The currently supported methods are
 
 * [`init`](#initialisation) (default value) — used to initialize a floating scrollbar widget;
 * [`update`](#updating-scrollbar) — used t force update of the floating scrollbar parameters (size and position);
-* [`destroy`](#destroying-floating-scrollbar) — removes a scrollbar and all related event handlers.
+* [`destroy`](#destroying-floating-scrollbar) — removes a scrollbar and all related event handlers;
+* [`destroyDetached`](#destroying-detached-widgets) — destroys floating scrollbar instances whose containers were removed from the document (requires a different context, see below).
 
 You may also [trigger](https://api.jquery.com/trigger/) events `update.fscroll` and `destroy.fscroll` on containers with attached floating scrollbar: this does the same as invoking the corresponding methods.
 
@@ -33,15 +34,15 @@ The plugin requires the CSS file [jquery.floatingscroll.css](dist/jquery.floatin
 The only thing required to apply 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:
 
 ```javascript
-$(document).ready(function () {
+$(() => {
     $(".spacious-container").floatingScroll();
 });
 ```
 
 Starting with v3.1.0, the method `init` supports passing options. Currently, the only supported parameter is `orientation`. Default scrollbar orientation is `"horizontal"` but you can also make a vertical floating scrollbar using options:
 
 ```javascript
-$(document).ready(function () {
+$(() => {
     $(".spacious-container").floatingScroll("init", {
         orientation: "vertical"
     });
@@ -68,7 +69,7 @@ If you attach a floating scrollbar to a container whose size and/or content may
 
 ```javascript
 $(".spacious-container").floatingScroll("init");
-$("#refresh-button").click(function () {
+$("#refresh-button").click(() => {
     // ... some actions which change the total scroll width of the container ...
     $(".spacious-container").floatingScroll("update");
 });
@@ -82,6 +83,18 @@ To detach a scrollbar and remove all related event handlers, use the method `des
 $(".spacious-container").floatingScroll("destroy");
 ```
 
+### Destroying detached widgets
+
+If your app completely re-renders a large portion of DOM where floating scrollbar widgets were mounted, actual container references are lost, and therefore you cannot destroy the widgets and perform related cleanup using the `destroy` method. In this case, you may just call the `destroyDetached` method, and the pluign will find all “zombie” instances and will destroy them for you. Unlike the other methods, this one needs to be called in context of `$(window)`:
+
+```javascript
+$(".main-view .spacious-container").floatingScroll("init");
+// ... the app re-renders the main view ...
+$(".main-view").html("...");
+// destroy floating scrollbar widgets whose containers are not in the document anymore
+$(window).floatingScroll("destroyDetached");
+```
+
 ### Special cases
 
 If you want to attach a floating scrollbar 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.