iamvijaydev/ng-augment-native-scroll

Augmenting native scroll for higher functionalities. Example:

ng Augment Native scroll

This module aims to augment native scroll to provide few neat features. The features available as directives, are applied intelligently, based on the user device. Touch or non-touch. This is a angular (v1.x) port of the original experiments with augment native scroll.

###Connect Scrolls It can connect two or more scrollable areas so that they all scroll as one. Wrap each scrollable area with scrollArea directive, then wrap them all with connectScrolls directive. connectScrolls connects scrollable areas within scrollArea. For non-touch devices it can also apply kinetic scrolling.

Demo | Usage

###Kinetic Scroll It will apply touch-device-like smooth and kinetic scroll to native scroll. You can (mouse) click-hold to drag the scroll and release-flick to auto-scroll just like a kinetic scroll on touch devices. Just wrap the scrollable area with kineticScroll directive.

Demo | Usage

NOTE: Kinetic scroll with mouse events will be applied to non-touch devices only. It will NOT be applied on touch devices.

Installation and usage

###Via yarn or npm:

# yarn (recommended)
$ yarn add ng-augment-native-scroll

#npm
$ npm install ng-augment-native-scroll --save

Then use it as:

var angular = require('angular');
angular.module('mainApp', [ require('ng-augment-native-scroll') ]);

###Via bower:

$ bower install ng-augment-native-scroll --save

Then use it as:

var angular = require('angular');
var ngAugmentNativeScroll = require('./bower_components/ng-augment-native-scroll/src');

angular.module('mainApp', ['ng-augment-native-scroll']);

You can also include it in the old fashion way as:

<script src="/bower_components/ng-augment-native-scroll/dist/ngAugmentNativeScroll.js"></script>
<!-- or -->
<script src="/bower_components/ng-augment-native-scroll/dist/ngAugmentNativeScroll.min.js"></script>

###Direct use: Download the files as zip or tar.gz. Include it in your HTML file and use it in your script file as shown below:

<!-- template.html -->
<script src="<path-to-folder>/dist/ngAugmentNativeScroll.js" charset="utf-8"></script>

// main.js
angular.module('mainApp', ['ng-augment-native-scroll']);

connectScroll and scrollArea directive usage

These directives can be used like the example below:

<connect-scrolls options="options">
    <scroll-area>
        <ul id="list">
            <li ng-repeat="item in data.list">{{ item }}</li>
        </ul>
    </scroll-area>
    <scroll-area>
        <table id="table">
            <tbody>
                <tr ng-repeat="row in data.table track by $index">
                    <td ng-repeat="cell in row track by $index">{{ cell }}</td>
                </tr>
            </tbody>
        </table>
    </scroll-area>
</connect-scrolls>

scrollArea requires connectScroll and connectScroll expects scrollArea to define the scrollable areas to be connected. Neither can be used alone. You can use multiple connect-scrolls within the same scope. You can even nest one within other. But do not overlap one another, it's not supported yet.

kineticScroll directive usage

This directive can be used like the example below:

<kinetic-scroll options="options">
    <table id="table">
        <tbody>
            <tr ng-repeat="row in data.table track by $index">
                <td ng-repeat="cell in row track by $index">{{ cell }}</td>
            </tr>
        </tbody>
    </table>
</kinetic-scroll>

kineticScroll expects its first child to be a scrollable area. It's better to wrap just the scrollable item with kineticScroll. You can use multiple connect-scrolls within the same scope. You can even nest one within other.

Configurable options

Option	Description	Type	Default
name	Give it a name, a unique name. The directives will be exposing the helper methods to the $parent scope on this namespace. Provide a unique name when using multiple or nested instances.	String	NA
enableKinetics	On touch devices kinetics won't be applied. Apply touch-device-like smooth and kinetic scroll to native scroll. You can (mouse) click-hold to drag the scroll and release-flick to auto-scroll just like a kinetic scroll on touch devices.	Boolean	true
movingAverage	The moving average filter protects the kinetic scroll going to a frenzy state. A lower value will have a slow and smooth kinetic scroll	Number	0.1
preventDefaultException	Mouse events for kinetic scrolling is prevented from executing default action, i:ee.preventDefault() is called internally. This can make elements non-responsive. For e.g: select wont open. You can provide tagName, class or id that when matched wont call preventDefault. By default input, textarea, button and select are exempted.	Object	Look here

Exposed methods to $parent

Both directive connectScrolls and kineticScroll will expose couple of methods to it's parent scope. With the exposed methods we can control the scroll from $parent scope; for e.g. scroll to start or end. The exposed methods will be available on the namespace augNs as provided in in the options. For e.g. let's assume the option is { name: 'myAugNs' } then the exposed methods will be available on $scope.myAugNs Here are the list of exposed methods:

Name	Description
scrollToStart	Scrolls all scroll to start, i:e scrollLeft and scrollTop are set to 0
scrollToStartLeft	Scrolls all scrollLeft to start
scrollToStartTop	Scrolls all scrollTop to start
scrollToEnd	Scrolls all scroll to end or max scroll, i:e scrollLeft and scrollTop are set to possible max scroll value
scrollToEndLeft	Scrolls all scrollLeft to end or max scroll left value
scrollToEndTop	Scrolls all scrollTop to end or max scroll top value
scrollToPosition	Scrolls to the positions provided as arguments. $scope.augNs.scrollToPosition({Number} left, {Number} top)
scrollByValue	Scroll to new positions by adding the arguments provided to current positions. $scope.augNs.scrollByValue({Number} left, {Number} top)

Here is an example of how it can be used on the $parent scope:

// connect-scroll options
$scope.options = {
    name: 'myAugNs'
}

// reset scroll after fetching new data
DataService.fetchUserList()
    .then(function (data) {
        $scope.userList = data;
        $scope.myAugNs.scrollToStart();
    })

TODO

Testing and code-coverage.

#Future

• Implement pull-down-to functionality - refresh or load previous page to name a few
• Implement pull-up-to functionality - load next page may be