Merge branch 'fs-3.1.0'

README.md

@@ -2,23 +2,23 @@
 
 ## 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 outside the viewport.
+The general purpose of the plugin is to provide some lengthy containers on the page with a separate horizontal (or vertical) scrollbar, 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 scrollbar is outside the viewport.
 
 :bulb: **Tips:**
 
-* floating-scroll is a jQuery plugin. If you are rather looking for a standalone dependency-free module with the same functionality, please check out the sibling project [handy-scroll](https://github.com/Amphiluke/handy-scroll) instead.
+* floating-scroll is a jQuery plugin. If you are rather looking for a standalone dependency-free module with the similar functionality, please check out the sibling project [handy-scroll](https://github.com/Amphiluke/handy-scroll) instead.
 * Developing a Vue-based app? Consider using the [vue-handy-scroll](https://github.com/Amphiluke/vue-handy-scroll) component.
 
 
 ## Details & API
 
-There is the only public method used to instantiate and control a floating scroll bar — `.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()`. 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 scroll bar widget;
-* [`update`](#updating-scroll-bar) — used to force update of the floating scroll bar parameters (size and position);
-* [`destroy`](#destroying-floating-scroll-bar) — removes a scroll bar and all related event handlers.
+* [`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.
 
-You may also [trigger](https://api.jquery.com/trigger/) events `update.fscroll` and `destroy.fscroll` on containers with attached floating scroll bar: this does the same as invoking the corresponding methods.
+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.
 
 ## Usage
 
@@ -38,6 +38,16 @@ $(document).ready(function () {
 });
 ```
 
+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"
+    });
+});
+```
+
 ### Auto-initialisation
 
 There is another way of initialising the floatingScroll widget without writing a single line of JavaScript code. Just add an attribute `data-fl-scrolls` to the desired container. As the DOM is ready the plugin will detect all such elements and will do initialisation automatically.
@@ -46,13 +56,15 @@ There is another way of initialising the floatingScroll widget without writing a
 <div class="spacious-container" data-fl-scrolls>
     <!-- Horizontally wide contents -->
 </div>
-```
 
-_The auto-initialisation feature is available starting with v3.0.0._
+<div class="spacious-container" data-fl-scrolls='{"orientation": "vertical"}'>
+    <!-- Horizontally wide contents -->
+</div>
+```
 
-### Updating scroll bar
+### Updating scrollbar
 
-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’s sizes change. This can be done by invoking the method `update` as in the example below.
+If you attach a floating scrollbar to a container whose size and/or content may dynamically change, then you need a way to update the scrollbar each time the container’s sizes change. This can be done by invoking the method `update` as in the example below.
 
 ```javascript
 $(".spacious-container").floatingScroll("init");
@@ -62,17 +74,17 @@ $("#refresh-button").click(function () {
 });
 ```
 
-### Destroying floating scroll bar
+### Destroying floating scrollbar
 
-To detach a scroll bar and remove all related event handlers, use the method `destroy` as follows:
+To detach a scrollbar and remove all related event handlers, use the method `destroy` as follows:
 
 ```javascript
 $(".spacious-container").floatingScroll("destroy");
 ```
 
 ### 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.
+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.
 
 ```html
 <div class="fl-scrolls-viewport"><!-- (1) -->
@@ -84,7 +96,7 @@ If you want to attach a floating scroll bar to a container living in a positione
 </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:
+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 scrollbar. 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();
@@ -94,7 +106,7 @@ The plugin’s CSS file provides some basic styles for elements with classes `.f
 
 ### “Unobtrusive” mode
 
-You can make a floating scroll bar more “unobtrusive” so that it will appear only when the mouse pointer hovers over the scrollable container. To do so just apply the class `fl-scrolls-hoverable` to the desired scrollable container owning the floating scroll bar.
+You can make a floating scrollbar more “unobtrusive” so that it will appear only when the mouse pointer hovers over the scrollable container. To do so just apply the class `fl-scrolls-hoverable` to the desired scrollable container owning the floating scrollbar.
 
 ## Live demos