From 88194cb3c2bdba44086cbc9ec2b55abad3fbfcf9 Mon Sep 17 00:00:00 2001 From: Georgios Kalpakas Date: Wed, 1 Oct 2014 19:42:34 +0300 Subject: [PATCH 1/3] WIP - feat($anchorScroll): add support for configurable scroll offset Add support for a configurable scroll offset to $anchorScrollProvider. The offset is expressed in pixels and can be specified either as a fixed value or as a function that return the offset it pixels dynamically. (This is a POC and a WIP: no docs, no tests) Related to #9368 Closes #2070, #9360 --- docs/app/src/app.js | 2 +- docs/app/src/directives.js | 1 - docs/app/src/scroll-offset.js | 39 ++++++++ docs/config/templates/indexPage.template.html | 2 +- src/ng/anchorScroll.js | 96 ++++++++++++++++++- 5 files changed, 132 insertions(+), 8 deletions(-) create mode 100644 docs/app/src/scroll-offset.js diff --git a/docs/app/src/app.js b/docs/app/src/app.js index af94d44a2b8d..11ac6fda73de 100644 --- a/docs/app/src/app.js +++ b/docs/app/src/app.js @@ -13,11 +13,11 @@ angular.module('docsApp', [ 'search', 'tutorials', 'versions', + 'scrollOffset', 'bootstrap', 'ui.bootstrap.dropdown' ]) - .config(['$locationProvider', function($locationProvider) { $locationProvider.html5Mode(true).hashPrefix('!'); }]); diff --git a/docs/app/src/directives.js b/docs/app/src/directives.js index 30077e83ff94..6ad4f6a38f23 100644 --- a/docs/app/src/directives.js +++ b/docs/app/src/directives.js @@ -29,4 +29,3 @@ angular.module('directives', []) } }; }); - diff --git a/docs/app/src/scroll-offset.js b/docs/app/src/scroll-offset.js new file mode 100644 index 000000000000..342eacdb5d35 --- /dev/null +++ b/docs/app/src/scroll-offset.js @@ -0,0 +1,39 @@ +angular.module('scrollOffset', []) + +/** + * scrollOffsetElement Directive + * + * @description Store the element whose height should be used to determine the scroll offset and its + * computed style. + */ +.directive('scrollOffsetElement', ['$window', 'SCROLL_OFFSET_ELEMENT', + function scrollOffsetElementDirective($window, SCROLL_OFFSET_ELEMENT) { + return { + restrict: 'A', + link: function scrollOffsetElementPostLink(scope, elem) { + elem = elem[0]; + SCROLL_OFFSET_ELEMENT.element = elem; + SCROLL_OFFSET_ELEMENT.computedStyle = $window.getComputedStyle(elem); + // README: Using `getComputedStyle()` renders this approach incompatible with IE8. + } + }; + } +]) + +.constant('SCROLL_OFFSET_ELEMENT', { + element: null, // README: This is not used, but keeping it here just in case... + computedStyle: null +}) + +.config(['$anchorScrollProvider', 'SCROLL_OFFSET_ELEMENT', + function($anchorScrollProvider, SCROLL_OFFSET_ELEMENT) { + var extraTopSpace = 15; + $anchorScrollProvider.setScrollOffset(function () { + var computedStyle = SCROLL_OFFSET_ELEMENT.computedStyle; + + if (!computedStyle || (computedStyle.position !== 'fixed')) return 0; + + return parseInt(computedStyle.height, 10) + extraTopSpace; + }); + } +]); diff --git a/docs/config/templates/indexPage.template.html b/docs/config/templates/indexPage.template.html index 852468434054..6582e92436fc 100644 --- a/docs/config/templates/indexPage.template.html +++ b/docs/config/templates/indexPage.template.html @@ -70,7 +70,7 @@
-
+
diff --git a/src/ng/anchorScroll.js b/src/ng/anchorScroll.js index b2fd705aa7d7..4e87e5de77e7 100644 --- a/src/ng/anchorScroll.js +++ b/src/ng/anchorScroll.js @@ -16,6 +16,10 @@ * It also watches the `$location.hash()` and scrolls whenever it changes to match any anchor. * This can be disabled by calling `$anchorScrollProvider.disableAutoScrolling()`. * + * Additionally, you can specify a scroll offset (in pixels) during the configuration phase by + * calling `$anchorScrollProvider.setScrollOffset()`. The offset can be either a + * fixed value or a getter function that returns a value dynamically. + * * @example @@ -50,15 +54,85 @@ } + * + *
+ * The example below illustrates the use of scroll offset (specified as a fixed value). + * + * @example + + +
+ + Go to anchor {{x}} + +
+
+ Anchor {{x}} of 5 +
+ + + angular.module('anchorScrollOffsetExample', []) + .config(['$anchorScrollProvider', function($anchorScrollProvider) { + $anchorScrollProvider.setScrollOffset(50); // always scroll by 50 extra pixels + }]) + .controller('headerCtrl', ['$anchorScroll', '$location', '$scope', + function ($anchorScroll, $location, $scope) { + $scope.gotoAnchor = function(x) { + // Set the location.hash to the id of + // the element you wish to scroll to. + $location.hash('anchor' + x); + + // Call $anchorScroll() + $anchorScroll(); + }; + } + ]); + + + body { + padding-top: 50px; + } + + .anchor { + border: 2px dashed DarkOrchid; + padding: 10px 10px 200px 10px; + } + + .fixed-header { + background-color: rgba(0, 0, 0, 0.2); + height: 50px; + position: fixed; + top: 0; left: 0; right: 0; + } + + .fixed-header > a { + display: inline-block; + margin: 5px 15px; + } + + */ function $AnchorScrollProvider() { +// TODO(gkalpak): The $anchorScrollProvider should be documented as well +// (under the providers section). + + var DEFAULT_OFFSET = 0; var autoScrollingEnabled = true; + var scrollOffsetGetter = function() { return DEFAULT_OFFSET; }; this.disableAutoScrolling = function() { autoScrollingEnabled = false; }; + this.setScrollOffset = function(newScrollOffset) { + if (isFunction(newScrollOffset)) { + scrollOffsetGetter = function() { return newScrollOffset(); }; + } else if (isNumber(newScrollOffset)) { + scrollOffsetGetter = function() { return newScrollOffset; }; + } + }; + this.$get = ['$window', '$location', '$rootScope', function($window, $location, $rootScope) { var document = $window.document; @@ -76,20 +150,33 @@ function $AnchorScrollProvider() { return result; } + function scrollTo(elem) { + if (elem) { + elem.scrollIntoView(); + var offset = scrollOffsetGetter(); + var actualOffset = offset && (offset - (elem.offsetTop - document.body.scrollTop)); + if (actualOffset) { + $window.scrollBy(0, -1 * actualOffset); + } + } else { + $window.scrollTo(0, 0); + } + } + function scroll() { var hash = $location.hash(), elm; // empty hash, scroll to the top of the page - if (!hash) $window.scrollTo(0, 0); + if (!hash) scrollTo(null); // element with given id - else if ((elm = document.getElementById(hash))) elm.scrollIntoView(); + else if ((elm = document.getElementById(hash))) scrollTo(elm); // first anchor with given name :-D - else if ((elm = getFirstAnchor(document.getElementsByName(hash)))) elm.scrollIntoView(); + else if ((elm = getFirstAnchor(document.getElementsByName(hash)))) scrollTo(elm); // no element and hash == 'top', scroll to the top of the page - else if (hash === 'top') $window.scrollTo(0, 0); + else if (hash === 'top') scrollTo(null); } // does not scroll when user clicks on anchor link that is currently on @@ -107,4 +194,3 @@ function $AnchorScrollProvider() { return scroll; }]; } - From d5bad75ab2f8450117ee1d45e087109886102566 Mon Sep 17 00:00:00 2001 From: Peter Bacon Darwin Date: Thu, 2 Oct 2014 12:04:27 +0100 Subject: [PATCH 2/3] WIP: simplify $anchorScroll offset feature --- docs/app/src/app.js | 3 +- docs/app/src/directives.js | 8 +++- docs/app/src/scroll-offset.js | 39 ------------------ docs/config/templates/indexPage.template.html | 2 +- src/ng/anchorScroll.js | 40 +++++++++++-------- test/ng/anchorScrollSpec.js | 1 + 6 files changed, 34 insertions(+), 59 deletions(-) delete mode 100644 docs/app/src/scroll-offset.js diff --git a/docs/app/src/app.js b/docs/app/src/app.js index 11ac6fda73de..7285aa8ccdd8 100644 --- a/docs/app/src/app.js +++ b/docs/app/src/app.js @@ -13,11 +13,10 @@ angular.module('docsApp', [ 'search', 'tutorials', 'versions', - 'scrollOffset', 'bootstrap', 'ui.bootstrap.dropdown' ]) .config(['$locationProvider', function($locationProvider) { $locationProvider.html5Mode(true).hashPrefix('!'); -}]); +}]); \ No newline at end of file diff --git a/docs/app/src/directives.js b/docs/app/src/directives.js index 6ad4f6a38f23..4c3acf781000 100644 --- a/docs/app/src/directives.js +++ b/docs/app/src/directives.js @@ -28,4 +28,10 @@ angular.module('directives', []) element.html(window.prettyPrintOne(html, lang, linenums)); } }; -}); +}) + +.directive('scrollYOffsetElement', ['$anchorScroll', function($anchorScroll) { + return function(scope, element) { + $anchorScroll.yOffset = element; + }; +}]); diff --git a/docs/app/src/scroll-offset.js b/docs/app/src/scroll-offset.js deleted file mode 100644 index 342eacdb5d35..000000000000 --- a/docs/app/src/scroll-offset.js +++ /dev/null @@ -1,39 +0,0 @@ -angular.module('scrollOffset', []) - -/** - * scrollOffsetElement Directive - * - * @description Store the element whose height should be used to determine the scroll offset and its - * computed style. - */ -.directive('scrollOffsetElement', ['$window', 'SCROLL_OFFSET_ELEMENT', - function scrollOffsetElementDirective($window, SCROLL_OFFSET_ELEMENT) { - return { - restrict: 'A', - link: function scrollOffsetElementPostLink(scope, elem) { - elem = elem[0]; - SCROLL_OFFSET_ELEMENT.element = elem; - SCROLL_OFFSET_ELEMENT.computedStyle = $window.getComputedStyle(elem); - // README: Using `getComputedStyle()` renders this approach incompatible with IE8. - } - }; - } -]) - -.constant('SCROLL_OFFSET_ELEMENT', { - element: null, // README: This is not used, but keeping it here just in case... - computedStyle: null -}) - -.config(['$anchorScrollProvider', 'SCROLL_OFFSET_ELEMENT', - function($anchorScrollProvider, SCROLL_OFFSET_ELEMENT) { - var extraTopSpace = 15; - $anchorScrollProvider.setScrollOffset(function () { - var computedStyle = SCROLL_OFFSET_ELEMENT.computedStyle; - - if (!computedStyle || (computedStyle.position !== 'fixed')) return 0; - - return parseInt(computedStyle.height, 10) + extraTopSpace; - }); - } -]); diff --git a/docs/config/templates/indexPage.template.html b/docs/config/templates/indexPage.template.html index 6582e92436fc..b96494943c06 100644 --- a/docs/config/templates/indexPage.template.html +++ b/docs/config/templates/indexPage.template.html @@ -70,7 +70,7 @@
-
+
diff --git a/src/ng/anchorScroll.js b/src/ng/anchorScroll.js index 4e87e5de77e7..5d18b60edebe 100644 --- a/src/ng/anchorScroll.js +++ b/src/ng/anchorScroll.js @@ -116,23 +116,12 @@ function $AnchorScrollProvider() { // TODO(gkalpak): The $anchorScrollProvider should be documented as well // (under the providers section). - var DEFAULT_OFFSET = 0; - var autoScrollingEnabled = true; - var scrollOffsetGetter = function() { return DEFAULT_OFFSET; }; this.disableAutoScrolling = function() { autoScrollingEnabled = false; }; - this.setScrollOffset = function(newScrollOffset) { - if (isFunction(newScrollOffset)) { - scrollOffsetGetter = function() { return newScrollOffset(); }; - } else if (isNumber(newScrollOffset)) { - scrollOffsetGetter = function() { return newScrollOffset; }; - } - }; - this.$get = ['$window', '$location', '$rootScope', function($window, $location, $rootScope) { var document = $window.document; @@ -150,14 +139,33 @@ function $AnchorScrollProvider() { return result; } + function getYOffset() { + + var offset = scroll.yOffset; + + if (isElement(offset)) { + + var style = $window.getComputedStyle(scroll.yOffset[0]); + var top = parseInt(style.top,10); + var height = parseInt(style.height,10); + return style.position === 'fixed' ? (top + height) : 0; + + } else if (isFunction(offset)) { + return offset(); + + } else if (isNumber(offset)) { + return offset; + + } else { + return 0; + } + + } + function scrollTo(elem) { if (elem) { elem.scrollIntoView(); - var offset = scrollOffsetGetter(); - var actualOffset = offset && (offset - (elem.offsetTop - document.body.scrollTop)); - if (actualOffset) { - $window.scrollBy(0, -1 * actualOffset); - } + $window.scrollBy(0, -1 * getYOffset()); } else { $window.scrollTo(0, 0); } diff --git a/test/ng/anchorScrollSpec.js b/test/ng/anchorScrollSpec.js index 2da8a7703bca..0b3f17992f4a 100644 --- a/test/ng/anchorScrollSpec.js +++ b/test/ng/anchorScrollSpec.js @@ -52,6 +52,7 @@ describe('$anchorScroll', function() { elmSpy = {}; $provide.value('$window', { scrollTo: jasmine.createSpy('$window.scrollTo'), + scrollBy: jasmine.createSpy('$window.scrollBy'), document: document, navigator: {} }); From 92e5a05355c76df47e3b5ebbf2c2ac8eb8484afc Mon Sep 17 00:00:00 2001 From: Georgios Kalpakas Date: Fri, 3 Oct 2014 23:51:48 +0300 Subject: [PATCH 3/3] WIP - feat($anchorScroll): add docs and tests and make small improvements Finalize the implementation, fix scrolling for elements near the end of the page, make sure the values calculated for top-offset and height are accurate (and unaffected by box-sizing or offset-parents). Separately document $anchorScrollProvider, document the newly added `yOffset` property of $anchorScroll, fix minor issues in the examples and overall improve the docs. Add tests for `$anchorScroll.yOffset` and make some necessary modifications to the existing test helper functions. --- src/ng/anchorScroll.js | 337 +++++++++++++++--------- test/ng/anchorScrollSpec.js | 511 +++++++++++++++++++++++++++++++----- 2 files changed, 658 insertions(+), 190 deletions(-) diff --git a/src/ng/anchorScroll.js b/src/ng/anchorScroll.js index 5d18b60edebe..e0aac61fb2e7 100644 --- a/src/ng/anchorScroll.js +++ b/src/ng/anchorScroll.js @@ -1,129 +1,174 @@ 'use strict'; /** - * @ngdoc service - * @name $anchorScroll - * @kind function - * @requires $window - * @requires $location - * @requires $rootScope + * @ngdoc provider + * @name $anchorScrollProvider * * @description - * When called, it checks current value of `$location.hash()` and scrolls to the related element, - * according to rules specified in - * [Html5 spec](http://dev.w3.org/html5/spec/Overview.html#the-indicated-part-of-the-document). - * - * It also watches the `$location.hash()` and scrolls whenever it changes to match any anchor. - * This can be disabled by calling `$anchorScrollProvider.disableAutoScrolling()`. - * - * Additionally, you can specify a scroll offset (in pixels) during the configuration phase by - * calling `$anchorScrollProvider.setScrollOffset()`. The offset can be either a - * fixed value or a getter function that returns a value dynamically. - * - * @example - - -
- Go to bottom - You're at the bottom! -
- - - angular.module('anchorScrollExample', []) - .controller('ScrollController', ['$scope', '$location', '$anchorScroll', - function ($scope, $location, $anchorScroll) { - $scope.gotoBottom = function() { - // set the location.hash to the id of - // the element you wish to scroll to. - $location.hash('bottom'); - - // call $anchorScroll() - $anchorScroll(); - }; - }]); - - - #scrollArea { - height: 350px; - overflow: auto; - } - - #bottom { - display: block; - margin-top: 2000px; - } - - - * - *
- * The example below illustrates the use of scroll offset (specified as a fixed value). - * - * @example - - -
- - Go to anchor {{x}} - -
-
- Anchor {{x}} of 5 -
- - - angular.module('anchorScrollOffsetExample', []) - .config(['$anchorScrollProvider', function($anchorScrollProvider) { - $anchorScrollProvider.setScrollOffset(50); // always scroll by 50 extra pixels - }]) - .controller('headerCtrl', ['$anchorScroll', '$location', '$scope', - function ($anchorScroll, $location, $scope) { - $scope.gotoAnchor = function(x) { - // Set the location.hash to the id of - // the element you wish to scroll to. - $location.hash('anchor' + x); - - // Call $anchorScroll() - $anchorScroll(); - }; - } - ]); - - - body { - padding-top: 50px; - } - - .anchor { - border: 2px dashed DarkOrchid; - padding: 10px 10px 200px 10px; - } - - .fixed-header { - background-color: rgba(0, 0, 0, 0.2); - height: 50px; - position: fixed; - top: 0; left: 0; right: 0; - } - - .fixed-header > a { - display: inline-block; - margin: 5px 15px; - } - - + * Use `$anchorScrollProvider` to disable automatic scrolling whenever + * {@link ng.$location#hash $location.hash()} changes. */ function $AnchorScrollProvider() { -// TODO(gkalpak): The $anchorScrollProvider should be documented as well -// (under the providers section). var autoScrollingEnabled = true; + /** + * @ngdoc method + * @name $anchorScrollProvider#disableAutoScrolling + * + * @description + * By default, {@link ng.$anchorScroll $anchorScroll()} will automatically will detect changes to + * {@link ng.$location#hash $location.hash()} and scroll to the element matching the new hash.
+ * Use this method to disable automatic scrolling. + * + * If automatic scrolling is disabled, one must explicitly call + * {@link ng.$anchorScroll $anchorScroll()} in order to scroll to the element related to the + * current hash. + */ this.disableAutoScrolling = function() { autoScrollingEnabled = false; }; + /** + * @ngdoc service + * @name $anchorScroll + * @kind function + * @requires $window + * @requires $location + * @requires $rootScope + * + * @description + * When called, it checks the current value of {@link ng.$location#hash $location.hash()} and + * scrolls to the related element, according to the rules specified in the + * [Html5 spec](http://dev.w3.org/html5/spec/Overview.html#the-indicated-part-of-the-document). + * + * It also watches the {@link ng.$location#hash $location.hash()} and automatically scrolls to + * match any anchor whenever it changes. This can be disabled by calling + * {@link ng.$anchorScrollProvider#disableAutoScrolling $anchorScrollProvider.disableAutoScrolling()}. + * + * Additionally, you can use its {@link ng.$anchorScroll#yOffset yOffset} property to specify a + * vertical scroll-offset (either fixed or dynamic). + * + * @property {(number|function|jqLite)} yOffset + * If set, specifies a vertical scroll-offset. This is often useful when there are fixed + * positioned elements at the top of the page, such as navbars, headers etc. + * + * `yOffset` can be specified in various ways: + * - **number**: A fixed number of pixels to be used as offset.

+ * - **function**: A getter function called everytime `$anchorScroll()` is executed. Must return + * a number representing the offset (in pixels).

+ * - **jqLite**: A jqLite/jQuery element to be used for specifying the offset. The sum of the + * element's height and its distance from the top of the page will be used as offset.
+ * **Note**: The element will be taken into account only as long as its `position` is set to + * `fixed`. This option is useful, when dealing with responsive navbars/headers that adjust + * their height and/or positioning according to the viewport's size. + * + *
+ *
+ * In order for `yOffset` to work properly, scrolling should take place on the document's root and + * not some child element. + *
+ * + * @example + + +
+ Go to bottom + You're at the bottom! +
+ + + angular.module('anchorScrollExample', []) + .controller('ScrollController', ['$scope', '$location', '$anchorScroll', + function ($scope, $location, $anchorScroll) { + $scope.gotoBottom = function() { + // set the location.hash to the id of + // the element you wish to scroll to. + $location.hash('bottom'); + + // call $anchorScroll() + $anchorScroll(); + }; + }]); + + + #scrollArea { + height: 280px; + overflow: auto; + } + + #bottom { + display: block; + margin-top: 2000px; + } + + + * + *
+ * The example below illustrates the use of a vertical scroll-offset (specified as a fixed value). + * See {@link ng.$anchorScroll#yOffset $anchorScroll.yOffset} for more details. + * + * @example + + +
+ + Go to anchor {{x}} + +
+
+ Anchor {{x}} of 5 +
+ + + angular.module('anchorScrollOffsetExample', []) + .run(['$anchorScroll', function($anchorScroll) { + $anchorScroll.yOffset = 50; // always scroll by 50 extra pixels + }]) + .controller('headerCtrl', ['$anchorScroll', '$location', '$scope', + function ($anchorScroll, $location, $scope) { + $scope.gotoAnchor = function(x) { + var newHash = 'anchor' + x; + if ($location.hash() !== newHash) { + // set the $location.hash to `newHash` and + // $anchorScroll will automatically scroll to it + $location.hash('anchor' + x); + } else { + // call $anchorScroll() explicitly, + // since $location.hash hasn't changed + $anchorScroll(); + } + }; + } + ]); + + + body { + padding-top: 50px; + } + + .anchor { + border: 2px dashed DarkOrchid; + padding: 10px 10px 200px 10px; + } + + .fixed-header { + background-color: rgba(0, 0, 0, 0.2); + height: 50px; + position: fixed; + top: 0; left: 0; right: 0; + } + + .fixed-header > a { + display: inline-block; + margin: 5px 15px; + } + + + */ this.$get = ['$window', '$location', '$rootScope', function($window, $location, $rootScope) { var document = $window.document; + var scrollScheduled = false; // Helper function to get first anchor from a NodeList // (using `Array#some()` instead of `angular#forEach()` since it's more performant @@ -143,34 +188,72 @@ function $AnchorScrollProvider() { var offset = scroll.yOffset; - if (isElement(offset)) { - - var style = $window.getComputedStyle(scroll.yOffset[0]); - var top = parseInt(style.top,10); - var height = parseInt(style.height,10); - return style.position === 'fixed' ? (top + height) : 0; - - } else if (isFunction(offset)) { - return offset(); - - } else if (isNumber(offset)) { - return offset; - - } else { - return 0; + if (isFunction(offset)) { + offset = offset(); + } else if (isElement(offset)) { + var elem = offset[0]; + var style = $window.getComputedStyle(elem); + if (style.position !== 'fixed') { + offset = 0; + } else { + var rect = elem.getBoundingClientRect(); + var top = rect.top; + var height = rect.height; + offset = top + height; + } + } else if (!isNumber(offset)) { + offset = 0; } + return offset; } function scrollTo(elem) { if (elem) { elem.scrollIntoView(); - $window.scrollBy(0, -1 * getYOffset()); + + var offset = getYOffset(); + + if (offset) { + // `offset` is the number of pixels we should scroll up in order to align `elem` properly. + // This is true ONLY if the call to `elem.scrollIntoView()` initially aligns `elem` at the + // top of the viewport. IF the number of pixels from the top of `elem` to the end of the + // page's content is less than the height of the viewport, then `elem.scrollIntoView()` + // will NOT align the top of `elem` at the top of the viewport (but further down). This is + // often the case for elements near the bottom of the page. + // In such cases we do not need to scroll the whole `offset` up, just the fraction of the + // offset that is necessary to align the top of `elem` at the desired position. + var elemTop = elem.getBoundingClientRect().top; + var bodyTop = document.body.getBoundingClientRect().top; + var scrollTop = $window.pageYOffset; + var necessaryOffset = offset - (elemTop - (bodyTop + scrollTop)); + + $window.scrollBy(0, -1 * necessaryOffset); + } } else { $window.scrollTo(0, 0); } } + function scrollWhenReady() { + if (document.readyState === 'complete') { + $rootScope.$evalAsync(scroll); + } else if (!scrollScheduled) { + scrollScheduled = true; + document.addEventListener('readystatechange', function unbindAndScroll() { + // When navigating to a page with a URL including a hash, + // Firefox overwrites our `yOffset` if `$apply()` is used instead. + $rootScope.$evalAsync(function() { + if (document.readyState === 'complete') { + scrollScheduled = false; + document.removeEventListener('readystatechange', unbindAndScroll); + scroll(); + } + }); + }); + } + } + function scroll() { var hash = $location.hash(), elm; @@ -195,7 +278,7 @@ function $AnchorScrollProvider() { // skip the initial scroll if $location.hash is empty if (newVal === oldVal && newVal === '') return; - $rootScope.$evalAsync(scroll); + scrollWhenReady(); }); } diff --git a/test/ng/anchorScrollSpec.js b/test/ng/anchorScrollSpec.js index 0b3f17992f4a..fd3d4b763d55 100644 --- a/test/ng/anchorScrollSpec.js +++ b/test/ng/anchorScrollSpec.js @@ -1,23 +1,42 @@ 'use strict'; + describe('$anchorScroll', function() { var elmSpy; + var docSpies; + var windowSpies; function addElements() { var elements = sliceArgs(arguments); - return function() { + return function($window) { forEach(elements, function(identifier) { - var match = identifier.match(/(\w* )?(\w*)=(\w*)/), - jqElm = jqLite('<' + (match[1] || 'a ') + match[2] + '="' + match[3] + '"/>'), + var match = identifier.match(/(?:(\w*) )?(\w*)=(\w*)/), + nodeName = match[1] || 'a', + tmpl = '<' + nodeName + ' ' + match[2] + '="' + match[3] + '">' + + match[3] + // add some content or else Firefox and IE place the element + // in weird ways that break yOffset-testing. + '', + jqElm = jqLite(tmpl), elm = jqElm[0]; + // Inline elements cause Firefox to report an unexpected value for + // `getBoundingClientRect().top` on some platforms (depending on the default font and + // line-height). Using inline-block elements prevents this. + // See: https://bugzilla.mozilla.org/show_bug.cgi?id=1014738 + elm.style.display = 'inline-block'; elmSpy[identifier] = spyOn(elm, 'scrollIntoView'); - jqLite(document.body).append(jqElm); + jqLite($window.document.body).append(jqElm); }); }; } + function callAnchorScroll() { + return function($anchorScroll) { + $anchorScroll(); + }; + } + function changeHashAndScroll(hash) { return function($location, $anchorScroll) { $location.hash(hash); @@ -25,6 +44,96 @@ describe('$anchorScroll', function() { }; } + function changeHashTo(hash) { + return function($anchorScroll, $location, $rootScope) { + $rootScope.$apply(function() { + $location.hash(hash); + }); + }; + } + + function createMockDocument(initialReadyState) { + var mockedDoc = {}; + docSpies = {}; + + initialReadyState = initialReadyState || 'complete'; + var propsToPassThrough = ['body', 'documentElement']; + var methodsToPassThrough = [ + 'getElementById', + 'getElementsByName', + 'addEventListener', + 'removeEventListener' + ]; + + var document_ = document; + + propsToPassThrough.forEach(function(prop) { + mockedDoc[prop] = document_[prop]; + }); + methodsToPassThrough.forEach(function(method) { + mockedDoc[method] = document_[method].bind(document_); + docSpies[method] = spyOn(mockedDoc, method).andCallThrough(); + }); + + mockedDoc.readyState = initialReadyState || 'complete'; + mockedDoc.dispatchFakeReadyStateChangeEvent = function() { + var evt = document_.createEvent('Event'); + evt.initEvent('readystatechange', false, false); + document_.dispatchEvent(evt); + }; + mockedDoc.updateReadyState = function(newState) { + this.readyState = newState; + this.dispatchFakeReadyStateChangeEvent(); + }; + + return mockedDoc; + } + + function createMockWindow(initialReadyState) { + return function() { + module(function($provide) { + elmSpy = {}; + windowSpies = {}; + + $provide.value('$window', { + scrollTo: (windowSpies.scrollTo = jasmine.createSpy('$window.scrollTo')), + scrollBy: (windowSpies.scrollBy = jasmine.createSpy('$window.scrollBy')), + document: createMockDocument(initialReadyState), + navigator: {}, + pageYOffset: 0, + getComputedStyle: function(elem) { + return getComputedStyle(elem); + } + }); + }); + }; + } + + function expectNoScrolling() { + return expectScrollingTo(NaN); + } + + function expectScrollingTo(identifierCountMap) { + var map = {}; + if (isString(identifierCountMap)) { + map[identifierCountMap] = 1; + } else if (isArray(identifierCountMap)) { + forEach(identifierCountMap, function(identifier) { + map[identifier] = 1; + }); + } else { + map = identifierCountMap; + } + + return function($window) { + forEach(elmSpy, function(spy, id) { + var count = map[id] || 0; + expect(spy.callCount).toBe(count); + }); + expect($window.scrollTo).not.toHaveBeenCalled(); + }; + } + function expectScrollingToTop($window) { forEach(elmSpy, function(spy, id) { expect(spy).not.toHaveBeenCalled(); @@ -33,76 +142,156 @@ describe('$anchorScroll', function() { expect($window.scrollTo).toHaveBeenCalledWith(0, 0); } - function expectScrollingTo(identifier) { + function resetAllSpies() { + function resetSpy(spy) { + spy.reset(); + } + return function($window) { - forEach(elmSpy, function(spy, id) { - if (identifier === id) expect(spy).toHaveBeenCalledOnce(); - else expect(spy).not.toHaveBeenCalled(); - }); - expect($window.scrollTo).not.toHaveBeenCalled(); + forEach(elmSpy, resetSpy); + forEach(docSpies, resetSpy); + forEach(windowSpies, resetSpy); }; } - function expectNoScrolling() { - return expectScrollingTo(NaN); + function updateMockReadyState(newState) { + return function($browser, $window) { + // It is possible that this operation adds tasks to the asyncQueue (needs flushing) + $window.document.updateReadyState(newState); + if ($browser.deferredFns.length) { + $browser.defer.flush(); + } + }; } - beforeEach(module(function($provide) { - elmSpy = {}; - $provide.value('$window', { - scrollTo: jasmine.createSpy('$window.scrollTo'), - scrollBy: jasmine.createSpy('$window.scrollBy'), - document: document, - navigator: {} - }); + afterEach(inject(function($browser, $document) { + expect($browser.deferredFns.length).toBe(0); + dealoc($document); })); - it('should scroll to top of the window if empty hash', inject( - changeHashAndScroll(''), - expectScrollingToTop)); + describe('when explicitly called', function() { + + beforeEach(createMockWindow()); + + + it('should scroll to top of the window if empty hash', inject( + changeHashAndScroll(''), + expectScrollingToTop)); + + + it('should not scroll if hash does not match any element', inject( + addElements('id=one', 'id=two'), + changeHashAndScroll('non-existing'), + expectNoScrolling())); + + it('should scroll to anchor element with name', inject( + addElements('a name=abc'), + changeHashAndScroll('abc'), + expectScrollingTo('a name=abc'))); - it('should not scroll if hash does not match any element', inject( - addElements('id=one', 'id=two'), - changeHashAndScroll('non-existing'), - expectNoScrolling())); + it('should not scroll to other than anchor element with name', inject( + addElements('input name=xxl', 'select name=xxl', 'form name=xxl'), + changeHashAndScroll('xxl'), + expectNoScrolling())); - it('should scroll to anchor element with name', inject( - addElements('a name=abc'), - changeHashAndScroll('abc'), - expectScrollingTo('a name=abc'))); + it('should scroll to anchor even if other element with given name exist', inject( + addElements('input name=some', 'a name=some'), + changeHashAndScroll('some'), + expectScrollingTo('a name=some'))); - it('should not scroll to other than anchor element with name', inject( - addElements('input name=xxl', 'select name=xxl', 'form name=xxl'), - changeHashAndScroll('xxl'), - expectNoScrolling())); + it('should scroll to element with id with precedence over name', inject( + addElements('name=abc', 'id=abc'), + changeHashAndScroll('abc'), + expectScrollingTo('id=abc'))); - it('should scroll to anchor even if other element with given name exist', inject( - addElements('input name=some', 'a name=some'), - changeHashAndScroll('some'), - expectScrollingTo('a name=some'))); + it('should scroll to top if hash == "top" and no matching element', inject( + changeHashAndScroll('top'), + expectScrollingToTop)); - it('should scroll to element with id with precedence over name', inject( - addElements('name=abc', 'id=abc'), - changeHashAndScroll('abc'), - expectScrollingTo('id=abc'))); + + it('should scroll to element with id "top" if present', inject( + addElements('id=top'), + changeHashAndScroll('top'), + expectScrollingTo('id=top'))); + }); + + + describe('in respect to `document.readyState`', function() { + + beforeEach(createMockWindow('mocked')); + + + it('should wait for `document.readyState === "complete"', inject( + addElements('id=some1'), + + changeHashTo('some1'), + expectNoScrolling(), + + updateMockReadyState('some-arbitrary-state'), + expectNoScrolling(), + + updateMockReadyState('complete'), + expectScrollingTo('id=some1'))); - it('should scroll to top if hash == "top" and no matching element', inject( - changeHashAndScroll('top'), - expectScrollingToTop)); + it('should only register once for execution when `document.readyState === "complete"', inject( + addElements('id=some1', 'id=some2'), + changeHashTo('some1'), + changeHashTo('some2'), + updateMockReadyState('some-other-arbitrary-state'), + changeHashTo('some1'), + changeHashTo('some2'), + expectNoScrolling(), - it('should scroll to element with id "top" if present', inject( - addElements('id=top'), - changeHashAndScroll('top'), - expectScrollingTo('id=top'))); + updateMockReadyState('complete'), + expectScrollingTo('id=some2'))); + + + it('should properly register and unregister listeners for `readystatechange` event', inject( + addElements('id=some1', 'id=some2'), + + changeHashTo('some1'), + changeHashTo('some2'), + updateMockReadyState('some-other-arbitrary-state'), + changeHashTo('some1'), + changeHashTo('some2'), + updateMockReadyState('complete'), + + function() { + expect(docSpies.addEventListener.callCount).toBe(1); + expect(docSpies.addEventListener). + toHaveBeenCalledWith('readystatechange', jasmine.any(Function)); + + expect(docSpies.removeEventListener.callCount).toBe(1); + expect(docSpies.removeEventListener). + toHaveBeenCalledWith('readystatechange', jasmine.any(Function)); + + var registeredListener = docSpies.addEventListener.calls[0].args[1]; + var unregisteredListener = docSpies.removeEventListener.calls[0].args[1]; + expect(unregisteredListener).toBe(registeredListener); + })); + + + it('should scroll immediately if already `readyState === "complete"`', inject( + addElements('id=some1'), + + updateMockReadyState('complete'), + changeHashTo('some1'), + + expectScrollingTo('id=some1'), + function() { + expect(docSpies.addEventListener.callCount).toBe(0); + expect(docSpies.removeEventListener.callCount).toBe(0); + })); + }); describe('watcher', function() { @@ -120,23 +309,13 @@ describe('$anchorScroll', function() { }; } - function changeHashTo(hash) { - return function ($location, $rootScope, $anchorScroll) { - $rootScope.$apply(function() { - $location.hash(hash); - }); - }; - } - function disableAutoScrolling() { return function($anchorScrollProvider) { $anchorScrollProvider.disableAutoScrolling(); }; } - afterEach(inject(function($document) { - dealoc($document); - })); + beforeEach(createMockWindow()); it('should scroll to element when hash change in hashbang mode', function() { @@ -190,7 +369,7 @@ describe('$anchorScroll', function() { }); - it('should not scroll when disabled', function() { + it('should not scroll when auto-scrolling is disabled', function() { module( disableAutoScrolling(), initLocation({html5Mode: false, historyApi: false}) @@ -201,6 +380,212 @@ describe('$anchorScroll', function() { expectNoScrolling() ); }); + + + it('should scroll when called explicitly (even if auto-scrolling is disabled)', function() { + module( + disableAutoScrolling(), + initLocation({html5Mode: false, historyApi: false}) + ); + inject( + addElements('id=fake'), + changeHashTo('fake'), + expectNoScrolling(), + callAnchorScroll(), + expectScrollingTo('id=fake') + ); + }); }); -}); + + // TODO: Add tests for with: + // 1. border/margin/padding !== 0 + // 2. box-sizing === border-box + describe('yOffset', function() { + + function expectScrollingWithOffset(identifierCountMap, offsetList) { + var list = isArray(offsetList) ? offsetList : [offsetList]; + + return function($rootScope, $window) { + inject(expectScrollingTo(identifierCountMap)); + expect($window.scrollBy.callCount).toBe(list.length); + forEach(list, function(offset, idx) { + // Due to sub-pixel rendering, there is a +/-1 error margin in the actual offset + var args = $window.scrollBy.calls[idx].args; + expect(args[0]).toBe(0); + expect(Math.abs(offset + args[1])).toBeLessThan(1); + }); + }; + } + + function expectScrollingWithoutOffset(identifierCountMap) { + return expectScrollingWithOffset(identifierCountMap, []); + } + + function setupBodyForOffsetTesting() { + return function($window) { + var style = $window.document.body.style; + style.border = 'none'; + style.margin = '0'; + style.padding = '0'; + }; + } + + function setYOffset(yOffset) { + return function($anchorScroll) { + $anchorScroll.yOffset = yOffset; + }; + } + + function updateMockPageYOffset() { + return function($window) { + $window.pageYOffset = window.pageYOffset; + }; + } + + beforeEach(createMockWindow()); + beforeEach(inject(setupBodyForOffsetTesting())); + + + describe('when set as a fixed number', function() { + + var yOffsetNumber = 50; + + beforeEach(inject(setYOffset(yOffsetNumber))); + + + it('should scroll with vertical offset', inject( + addElements('id=some'), + changeHashTo('some'), + expectScrollingWithOffset('id=some', yOffsetNumber))); + + + it('should use the correct vertical offset when changing `yOffset` at runtime', inject( + addElements('id=some'), + changeHashTo('some'), + setYOffset(yOffsetNumber - 10), + callAnchorScroll(), + expectScrollingWithOffset({'id=some': 2}, [yOffsetNumber, yOffsetNumber - 10]))); + + + it('should adjust the vertical offset for elements near the end of the page', function() { + + var targetAdjustedOffset = 25; + + inject( + addElements('id=some1', 'id=some2'), + function($window) { + // Make sure the elements are just a little shorter than the viewport height + var viewportHeight = $window.document.documentElement.clientHeight; + var elemHeight = viewportHeight - (yOffsetNumber - targetAdjustedOffset); + var cssText = [ + 'border:none', + 'display:block', + 'height:' + elemHeight + 'px', + 'margin:0', + 'padding:0', + ''].join(';'); + + forEach($window.document.body.children, function(elem) { + elem.style.cssText = cssText; + }); + + // Make sure scrolling does actually take place + // (this is necessary for the current test) + forEach(elmSpy, function(spy, identifier) { + elmSpy[identifier] = spy.andCallThrough(); + }); + }, + changeHashTo('some2'), + updateMockPageYOffset(), + resetAllSpies(), + callAnchorScroll(), + expectScrollingWithOffset('id=some2', targetAdjustedOffset)); + }); + }); + + + describe('when set as a function', function() { + + it('should scroll with vertical offset', function() { + + var val = 0; + var increment = 10; + + function yOffsetFunction() { + val += increment; + return val; + } + + inject( + addElements('id=id1', 'name=name2'), + setYOffset(yOffsetFunction), + changeHashTo('id1'), + changeHashTo('name2'), + changeHashTo('id1'), + callAnchorScroll(), + expectScrollingWithOffset({ + 'id=id1': 3, + 'name=name2': 1 + }, [ + 1 * increment, + 2 * increment, + 3 * increment, + 4 * increment + ])); + }); + }); + + + describe('when set as a jqLite element', function() { + + function createAndSetYOffsetElement(styleSpecs) { + var cssText = ''; + forEach(styleSpecs, function(value, key) { + cssText += key + ':' + value + ';'; + }); + + var jqElem = jqLite('
'); + + return function($anchorScroll, $window) { + jqLite($window.document.body).append(jqElem); + $anchorScroll.yOffset = jqElem; + }; + } + + + it('should scroll with vertical offset when `top === 0`', inject( + createAndSetYOffsetElement({ + background: 'DarkOrchid', + height: '50px', + position: 'fixed', + top: '0', + }), + addElements('id=some'), + changeHashTo('some'), + expectScrollingWithOffset('id=some', 50))); + + + it('should scroll with vertical offset when `top > 0`', inject( + createAndSetYOffsetElement({ + height: '50px', + position: 'fixed', + top: '50px', + }), + addElements('id=some'), + changeHashTo('some'), + expectScrollingWithOffset('id=some', 100))); + + + it('should scroll without vertical offset when `position !== fixed`', inject( + createAndSetYOffsetElement({ + height: '50px', + position: 'absolute', + top: '0', + }), + addElements('id=some'), + changeHashTo('some'), + expectScrollingWithoutOffset('id=some'))); + }); + }); +});