From 245e2199c6e9baafb3491ad7d57448c3103bb21b Mon Sep 17 00:00:00 2001 From: Andy Joslin Date: Wed, 19 Mar 2014 12:21:18 -0600 Subject: [PATCH] docs(ionicScrollController): write docs --- .../src/controller/ionicScrollController.js | 136 +++++++++++++++--- js/ext/angular/src/directive/ionicContent.js | 26 ++-- js/ext/angular/src/directive/ionicScroll.js | 1 + .../controller/ionicScrollController.unit.js | 37 +++-- js/ext/angular/test/rememberScroll.html | 33 +++++ 5 files changed, 186 insertions(+), 47 deletions(-) create mode 100644 js/ext/angular/test/rememberScroll.html diff --git a/js/ext/angular/src/controller/ionicScrollController.js b/js/ext/angular/src/controller/ionicScrollController.js index 6f81d322e9..94a5466926 100644 --- a/js/ext/angular/src/controller/ionicScrollController.js +++ b/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 + * + * + *
+ * + * {{i}} + * + *
+ * + * ``` + * ```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 diff --git a/js/ext/angular/src/directive/ionicContent.js b/js/ext/angular/src/directive/ionicContent.js index 795ed73f9d..d617dd04ee 100644 --- a/js/ext/angular/src/directive/ionicContent.js +++ b/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 * * + + + List + + + + + + + + + +
+ + {{i}} + +
+ + + + +