docs(ionicScrollController): write docs

js/ext/angular/src/controller/ionicScrollController.js

@@ -10,6 +10,14 @@ angular.module('ionic.ui.scroll')
   return {};
 })
 
+/**
+ * @ngdoc controller
+ * @name ionicScroll
+ * @module ionic
+ * @description
+ * Controller for the {@link ionic.directive:ionContent} and 
+ * {@link ionic.directive:ionScroll} directives.
+ */
 .controller('$ionicScroll', [
   '$scope',
   'scrollViewOptions',
@@ -90,42 +98,62 @@ function($scope, scrollViewOptions, $timeout, $window, $$scrollValueCache, $loca
   });
 
   this._rememberScrollId = null;
-  this.rememberScrollPosition = function(id) {
-    if (!id) {
-      throw new Error("Must supply an id to remember the scroll by!");
-    }
-    this._rememberScrollId = id;
-  };
-  this.forgetScrollPosition = function() {
-    delete $$scrollValueCache[this._rememberScrollId];
-    this._rememberScrollId = null;
-  };
-  this.scrollToRememberedPosition = function(shouldAnimate) {
-    var values = $$scrollValueCache[this._rememberScrollId];
-    if (values) {
-      scrollView.scrollTo(+values.left, +values.top, shouldAnimate);
-    }
-  };
 
+  /**
+   * @ngdoc method
+   * @name ionicScroll#resize
+   * @description Tell the scrollView to recalculate the size of its container.
+   */
   this.resize = function() {
     return $timeout(resize);
   };
+
+  /**
+   * @ngdoc method
+   * @name ionicScroll#scrollTop
+   * @param {boolean=} shouldAnimate Whether the scroll should animate.
+   */
   this.scrollTop = function(shouldAnimate) {
     this.resize().then(function() {
       scrollView.scrollTo(0, 0, !!shouldAnimate);
     });
   };
+
+  /**
+   * @ngdoc method
+   * @name ionicScroll#scrollBottom
+   * @param {boolean=} shouldAnimate Whether the scroll should animate.
+   */
   this.scrollBottom = function(shouldAnimate) {
     this.resize().then(function() {
       var max = scrollView.getScrollMax();
       scrollView.scrollTo(max.left, max.top, !!shouldAnimate);
     });
   };
+
+  /**
+   * @ngdoc method
+   * @name ionicScroll#scroll
+   * @param {number} left The x-value to scroll to.
+   * @param {number} top The y-value to scroll to.
+   * @param {boolean=} shouldAnimate Whether the scroll should animate.
+   */
   this.scrollTo = function(left, top, shouldAnimate) {
     this.resize().then(function() {
       scrollView.scrollTo(left, top, !!shouldAnimate);
     });
   };
+
+  /**
+   * @ngdoc method
+   * @name ionicScroll#anchorScroll
+   * @description Tell the scrollView to scroll to the element with an id
+   * matching window.location.hash.
+   *
+   * If no matching element is found, it will scroll to top.
+   *
+   * @param {boolean=} shouldAnimate Whether the scroll should animate.
+   */
   this.anchorScroll = function(shouldAnimate) {
     this.resize().then(function() {
       var hash = $location.hash();
@@ -139,6 +167,82 @@ function($scope, scrollViewOptions, $timeout, $window, $$scrollValueCache, $loca
     });
   };
 
+  /**
+   * @ngdoc method
+   * @name ionicScroll#rememberScrollPosition
+   * @description 
+   * Will make it so, when this scrollView is destroyed (user leaves the page),
+   * the last scroll position the page was on will be saved, indexed by the 
+   * given id.
+   *
+   * Note: for pages associated with a view under an ion-nav-view, 
+   * rememberScrollPosition automatically saves their scroll.
+   *
+   * Related methods: scrollToRememberedPosition, forgetScrollPosition (below).
+   *
+   * In the following example, the scroll position of the ion-scroll element
+   * will persist, even when the user changes the toggle switch.
+   *
+   * ```html
+   * <ion-toggle ng-model="shouldShowScrollView"></ion-toggle>
+   * <ion-scroll ng-if="shouldShowScrollView">
+   *   <div ng-controller="ScrollCtrl">
+   *     <ion-list>
+   *       <ion-item ng-repeat="i in items">{{i}}</ion-item>
+   *     </ion-list>
+   *   </div>
+   * </ion-scroll>
+   * ```
+   * ```js
+   * function ScrollCtrl($scope) {
+   *   $scope.$ionicScrollController.rememberScrollPosition('my-scroll-id');
+   *   $scope.$ionicScrollController.scrollToRememberedPosition();
+
+   *   $scope.items = [];
+   *   for (var i=0; i<100; i++) {
+   *     $scope.items.push(i);
+   *   }
+   * }
+   * ```
+   *
+   * @param {string} id The id to remember the scroll position of this 
+   * scrollView by.
+   */
+  this.rememberScrollPosition = function(id) {
+    if (!id) {
+      throw new Error("Must supply an id to remember the scroll by!");
+    }
+    this._rememberScrollId = id;
+  };
+  /**
+   * @ngdoc method
+   * @name ionicScroll#forgetScrollPosition
+   * @description
+   * Stop remembering the scroll position for this scrollView.
+   */
+  this.forgetScrollPosition = function() {
+    delete $$scrollValueCache[this._rememberScrollId];
+    this._rememberScrollId = null;
+  };
+  /**
+   * @ngdoc method
+   * @name ionicScroll#scrollToRememberedPosition
+   * @description
+   * If this scrollView has an id associated with its scroll position,
+   * (through calling rememberScrollPosition), and that position is remembered,
+   * load the position and scroll to it.
+   * @param {boolean=} shouldAnimate Whether to animate the scroll.
+   */
+  this.scrollToRememberedPosition = function(shouldAnimate) {
+    var values = $$scrollValueCache[this._rememberScrollId];
+    if (values) {
+      this.resize().then(function() {
+        scrollView.scrollTo(+values.left, +values.top, shouldAnimate);
+      });
+    }
+  };
+
+
 
   /**
    * @private

js/ext/angular/src/directive/ionicContent.js

@@ -167,19 +167,8 @@ function($parse, $timeout, $controller, $ionicBind) {
  * When refreshing is complete, $broadcast the 'scroll.refreshComplete' event
  * from your controller.
  *
- * @param {expression=} on-refresh Called when the user pulls down enough and lets go
- * of the refresher.
- * @param {expression=} on-pulling Called when the user starts to pull down
- * on the refresher.
- * @param {string=} pulling-icon The icon to display while the user is pulling down.
- * Default: 'ion-arrow-down-c'.
- * @param {string=} pulling-text The text to display while the user is pulling down.
- * @param {string=} refreshing-icon The icon to display after user lets go of the
- * refresher.
- * @param {string=} refreshing-text The text to display after the user lets go of
- * the refresher.
- *
  * @usage
+ *
  * ```html
  * <ion-content ng-controller="MyController">
  *   <ion-refresher
@@ -204,6 +193,19 @@ function($parse, $timeout, $controller, $ionicBind) {
  *   };
  * });
  * ```
+ *
+ * @param {expression=} on-refresh Called when the user pulls down enough and lets go
+ * of the refresher.
+ * @param {expression=} on-pulling Called when the user starts to pull down
+ * on the refresher.
+ * @param {string=} pulling-icon The icon to display while the user is pulling down.
+ * Default: 'ion-arrow-down-c'.
+ * @param {string=} pulling-text The text to display while the user is pulling down.
+ * @param {string=} refreshing-icon The icon to display after user lets go of the
+ * refresher.
+ * @param {string=} refreshing-text The text to display after the user lets go of
+ * the refresher.
+ *
  */
 .directive('ionRefresher', ['$ionicBind', function($ionicBind) {
   return {

js/ext/angular/src/directive/ionicScroll.js

@@ -38,6 +38,7 @@ angular.module('ionic.ui.scroll', [])
       scrollbarX: '@',
       scrollbarY: '@',
     },
+    priority: 501,
 
     controller: function() {},
 

js/ext/angular/test/controller/ionicScrollController.unit.js

@@ -138,16 +138,16 @@ describe('$ionicScroll Controller', function() {
     }).toThrow();
   });
 
-  it('should unbind window event listener on scope destroy', function() {
-    spyOn(window, 'removeEventListener');
-    spyOn(window, 'addEventListener');
+  it('should unbind window event listener on scope destroy', inject(function($window) {
+    spyOn($window, 'removeEventListener');
+    spyOn($window, 'addEventListener');
     setup();
-    expect(window.addEventListener).toHaveBeenCalled();
-    expect(window.addEventListener.mostRecentCall.args[0]).toBe('resize');
+    expect($window.addEventListener).toHaveBeenCalled();
+    expect($window.addEventListener.mostRecentCall.args[0]).toBe('resize');
     scope.$destroy();
-    expect(window.removeEventListener).toHaveBeenCalled();
-    expect(window.removeEventListener.mostRecentCall.args[0]).toBe('resize');
-  });
+    expect($window.removeEventListener).toHaveBeenCalled();
+    expect($window.removeEventListener.mostRecentCall.args[0]).toBe('resize');
+  }));
 
   it('rememberScrollPosition should set id', function() {
     setup();
@@ -195,17 +195,7 @@ describe('$ionicScroll Controller', function() {
   [false, true].forEach(function(shouldAnimate) {
     describe('with animate='+shouldAnimate, function() {
 
-      it('scrollToRememberedPosition should work', inject(function($$scrollValueCache) {
-        setup();
-        spyOn(ctrl.scrollView, 'scrollTo');
-        $$scrollValueCache.foo = { left: 3, top: 4 };
-        ctrl._rememberScrollId = 'foo';
-        expect(ctrl.scrollView.scrollTo).not.toHaveBeenCalled();
-        ctrl.scrollToRememberedPosition(shouldAnimate);
-        expect(ctrl.scrollView.scrollTo).toHaveBeenCalledWith(3, 4, shouldAnimate);
-      }));
-
-      describe('scroll action', function() {
+      ddescribe('scroll action', function() {
         beforeEach(function() {
           setup();
           //Mock resize to insta-call through for easier tests
@@ -213,6 +203,15 @@ describe('$ionicScroll Controller', function() {
             return { then: function(cb) { cb(); } };
           };
         });
+
+        it('scrollToRememberedPosition should work', inject(function($$scrollValueCache) {
+          spyOn(ctrl.scrollView, 'scrollTo');
+          $$scrollValueCache.foo = { left: 3, top: 4 };
+          ctrl._rememberScrollId = 'foo';
+          expect(ctrl.scrollView.scrollTo).not.toHaveBeenCalled();
+          ctrl.scrollToRememberedPosition(shouldAnimate);
+          expect(ctrl.scrollView.scrollTo).toHaveBeenCalledWith(3, 4, shouldAnimate);
+        }));
         it('.scrollTop', function() {
           spyOn(ctrl.scrollView, 'scrollTo');
           ctrl.scrollTop(shouldAnimate);

js/ext/angular/test/rememberScroll.html

@@ -0,0 +1,33 @@
+<html ng-app="ionic">
+  <head>
+    <meta charset="utf-8">
+    <title>List</title>
+
+    <!-- Sets initial viewport load and disables zooming  -->
+    <meta name="viewport" content="initial-scale=1, maximum-scale=1, user-scalable=no">
+    <link rel="stylesheet" href="../../../../dist/css/ionic.css">
+    <script src="../../../../dist/js/ionic.bundle.js"></script>
+  </head>
+  <body>
+   <ion-toggle ng-model="shouldShowScrollView"></ion-toggle>
+   <ion-scroll ng-if="shouldShowScrollView">
+     <div ng-controller="ScrollCtrl">
+       <ion-list>
+         <ion-item ng-repeat="i in items">{{i}}</ion-item>
+       </ion-list>
+     </div>
+   </ion-scroll>
+   <script>
+   function ScrollCtrl($scope) {
+     $scope.$ionicScrollController.rememberScrollPosition('my-scroll-id');
+     $scope.$ionicScrollController.scrollToRememberedPosition();
+
+     $scope.items = [];
+     for (var i=0; i<100; i++) {
+       $scope.items.push(i);
+     }
+   }
+   </script>
+  </body>
+</html>
+