212_infinite_scroll.ngdoc

@ngdoc overview
@name Tutorial: 212 Infinite scroll
@description

<div class="alert alert-warning" role="alert"><strong>Beta</strong> This feature is ready for testing, but it either hasn't seen a lot of use or has some known bugs.</div>

The infinite scroll feature allows the user to lazy load their data to gridOptions.data.

Documentation for the infiniteScroll feature is provided in the api documentation, in particular:

- {@link api/ui.grid.infiniteScroll.api:GridOptions gridOptions}
- {@link api/ui.grid.infiniteScroll.api:PublicAPI publicApi}

Once you reach the top (or bottom) of your real data set, you can notify that no more pages exist
up (or down), and infinite scroll will stop triggering events in that direction.  You can also
optionally tell us up-front that there are no more pages up through `infiniteScrollUp = true` or down through
`infiniteScrollDown = true`, and we will never trigger
pages in that direction.  By default we assume you have pages down but not up.

You can specify the number of rows from the end of the dataset at which the infinite scroll will trigger a request for
more data `infiniteScrollRowsFromEnd = 20`. By default we trigger when you are 20 rows away from the end of
the grid (in either direction).

We will raise a `needMoreData` or `needMoreDataTop` event, which you must listen to and respond to if
you have told us that you have more data available.  Once you have retrieved the data and added it to your
data array (at the top if the event was `needMoreDataTop`), you need to call `dataLoaded` to tell us
that you have loaded your data.  Optionally, you can tell us that there is no more data, and we won't trigger
further requests for more data in that direction.

When you have loaded your data we will attempt to adjust the grid scroll to give the appearance of continuous
scrolling.  We basically assume that your user will have reached the end of the scroll (upwards or downwards)
by the time the data comes back, and scroll the user to the beginning of the newly added data to reflect that.
In some circumstances this can give "jumpy" scrolling, particularly if you have set your rowsFromEnd to quite a high
value so that you're prefetching the data - if the user is scrolling slowly they might be 50 rows from the end, and
when we process the dataLoaded we suddenly move them to what used to be the end.  To avoid this, you can explicitly
save the scroll position before you add data to your data array, through calling `saveScrollPercentage`, and the
`dataLoaded` call will then take that position into account, and attempt to adjust the scroll so that the same
rows are showing once the grid has ingested the data you have added.

We suppress the normal grid behaviour of propagating the scroll to the parent container when you reach the end
if infinite scroll is enabled and if there is still data in that direction - so if there are pages upwards then
scrolling to the top will get those pages rather than hitting the top and then scrolling your whole page upwards.

If you are using {@link 307_external_sorting external sorting} or {@link 308_external_filtering external filtering} you may
reload your data whenever scroll or filter events occur.  In this situation you'll want to call `resetScroll` to tell the
grid not to try to preserve the previous scroll position.  You may also use this call when you've otherwise reset the data
in the grid.  You must also tell us whether you allow scrollUp or scrollDown from this position as part of the call.

You may sometimes remove data, for example if you're keeping 10 pages of data in memory, and you start discarding data
from the top as you add data to the bottom.  You can use the `dataRemovedTop` and `dataRemovedBottom` to tell
us that you've discarded data, and we'll aim to set the scroll back to where it was before you removed that data.

For better performance with the following example, you can choose to load the ui-grid.core.js and specific feature files instead:
<pre>
  <script src="/release/ui-grid.core.min.js"></script>
  <script src="/release/ui-grid.infinite-scroll.min.js"></script>
</pre>

@example
In this example we have a data set that starts at page 2 of a 5 page data set.  Each page is 100 records, so we start at
record 200, and we can scroll up 2 pages, and scroll down 2 pages.  You should see smooth scrolling as you move up, when
you hit record zero a touchpad scroll should propagate to the parent page.  You should also see smooth scrolling as you
move down, and when you hit record 499 a touchpad scroll should propagate to the parent page.

We also remove data from the data set in memory, we've decided that we only ever want to hold 4 pages in memory, so we
will discard pages and reset the scrollUp and scrollDown appropriately.  Again, when this happens the grid should still
hold the scroll position.

Finally, we can reset the data, which gets us back to the middle page and sets the scroll to the top.

<example module="app">
  <file name="app.js">
    var app = angular.module('app', ['ngTouch', 'ui.grid', 'ui.grid.infiniteScroll']);

    app.controller('MainCtrl', function ($scope, $http, $timeout) {
      var vm = this;

      vm.gridOptions = {
        infiniteScrollRowsFromEnd: 40,
        infiniteScrollUp: true,
        infiniteScrollDown: true,
        columnDefs: [
          { name:'id'},
          { name:'name' },
          { name:'age' }
        ],
        data: 'data',
        onRegisterApi: function(gridApi){
          gridApi.infiniteScroll.on.needLoadMoreData($scope, getDataDown);
          gridApi.infiniteScroll.on.needLoadMoreDataTop($scope, getDataUp);
          vm.gridApi = gridApi;
        }
      };

      $scope.data = [];

      vm.firstPage = 2;
      vm.lastPage = 2;

      function getFirstData() {
        return $http.get('https://cdn.rawgit.com/angular-ui/ui-grid.info/gh-pages/data/10000_complex.json')
        .then(function(response) {
          var newData = getPage(response.data, vm.lastPage);

          $scope.data = $scope.data.concat(newData);
        });
      }

      function getDataDown() {
        return $http.get('https://cdn.rawgit.com/angular-ui/ui-grid.info/gh-pages/data/10000_complex.json')
        .then(function(response) {
          vm.lastPage++;
          var newData = getPage(response.data, vm.lastPage);
          vm.gridApi.infiniteScroll.saveScrollPercentage();
          $scope.data = $scope.data.concat(newData);
          return vm.gridApi.infiniteScroll.dataLoaded(vm.firstPage > 0, vm.lastPage < 4).then(function() {checkDataLength('up');});
        })
        .catch(function(error) {
          return vm.gridApi.infiniteScroll.dataLoaded();
        });
      }

      function getDataUp() {
        return $http.get('https://cdn.rawgit.com/angular-ui/ui-grid.info/gh-pages/data/10000_complex.json')
        .then(function(response) {
          vm.firstPage--;
          var newData = getPage(response.data, vm.firstPage);
          vm.gridApi.infiniteScroll.saveScrollPercentage();
          $scope.data = newData.concat($scope.data);
          return vm.gridApi.infiniteScroll.dataLoaded(vm.firstPage > 0, vm.lastPage < 4).then(function() {checkDataLength('down');});
        })
        .catch(function(error) {
          return vm.gridApi.infiniteScroll.dataLoaded();
        });
      }

      function getPage(data, page) {
        var res = [];
        for (var i = (page * 100); i < (page + 1) * 100 && i < data.length; ++i) {
          res.push(data[i]);
        }
        return res;
      }

      function checkDataLength( discardDirection) {
        // work out whether we need to discard a page, if so discard from the direction passed in
        if( vm.lastPage - vm.firstPage > 3 ){
          // we want to remove a page
          vm.gridApi.infiniteScroll.saveScrollPercentage();

          if( discardDirection === 'up' ){
            $scope.data = $scope.data.slice(100);
            vm.firstPage++;
            $timeout(function() {
              // wait for grid to ingest data changes
              vm.gridApi.infiniteScroll.dataRemovedTop(vm.firstPage > 0, vm.lastPage < 4);
            });
          } else {
            $scope.data = $scope.data.slice(0, 400);
            vm.lastPage--;
            $timeout(function() {
              // wait for grid to ingest data changes
              vm.gridApi.infiniteScroll.dataRemovedBottom(vm.firstPage > 0, vm.lastPage < 4);
            });
          }
        }
      }

      vm.reset = function() {
        vm.firstPage = 2;
        vm.lastPage = 2;

        // turn off the infinite scroll handling up and down - hopefully this won't be needed after @swalters scrolling changes
        vm.gridApi.infiniteScroll.setScrollDirections( false, false );
        $scope.data = [];

        getFirstData().then(function(){
          $timeout(function() {
            // timeout needed to allow digest cycle to complete,and grid to finish ingesting the data
            vm.gridApi.infiniteScroll.resetScroll( vm.firstPage > 0, vm.lastPage < 4 );
          });
        });
      };

      getFirstData().then(function(){
        $timeout(function() {
          // timeout needed to allow digest cycle to complete,and grid to finish ingesting the data
          // you need to call resetData once you've loaded your data if you want to enable scroll up,
          // it adjusts the scroll position down one pixel so that we can generate scroll up events
          vm.gridApi.infiniteScroll.resetScroll( vm.firstPage > 0, vm.lastPage < 4 );
        });
      });
    });
  </file>
  <file name="index.html">
    <div ng-controller="MainCtrl as $ctrl">
      <button id="reset" class="button" ng-click="$ctrl.reset()">Reset</button>
      <span> &nbsp; &nbsp; First page: {{ $ctrl.firstPage }} &nbsp; &nbsp; Last page: {{ $ctrl.lastPage }}  &nbsp; &nbsp; data.length: {{ data.length }} </span>
      <div ui-grid="$ctrl.gridOptions" class="grid" ui-grid-infinite-scroll></div>
    </div>
  </file>
  <file name="main.css">
    .grid {
      width: 500px;
      height: 400px;
    }
  </file>
</example>