Merge pull request #85 from ftlabs/paginatedSnapFromOutsideBounds

Paginated snap from outside bounds

Author: rowanbeentje

README.md

@@ -50,13 +50,13 @@ Options must be specified at create-time by passing a JSON object as the second
 * `flinging` Allow a fast scroll to continue with momentum when released _(boolean, default true)_
 * `hwAccelerationClass` FTScroller uses normal translate properties rather than translate3d to position content when scrolling, and triggers hardware acceleration by adding CSS properties (specifically backface-visibility) to this class on platforms that support it.  Adjusting this class allows for negotiating complex CSS inheritance to override the default behaviour of FTScroller if you want to change or disable backing layers/3D acceleration. _(string, default an internal class which triggers backing layers)_
 * `maxFlingDuration` Set the maximum time (ms) that a fling can take to complete once the input has ended _(numeric, default 1000ms)_
-* `paginatedSnap` If snapping is enabled, restricts each scroll movement to one 'page' span.  That is, if set to true, it will not be possible to move more than one page in a single movement. _(boolean, default false)_
 * `scrollbars` Whether to display iOS-style scrollbars (which you can style yourself using `.ftscroller_scrollbar` and `.ftscroller_scrollbarx`/`.ftscroller_scrollbary`) while the content is animating _(boolean, default true)_
 * `scrollBoundary` The initial movement required to trigger a full scroll, in pixels; this is the point at which the scroll is exclusive to this particular FTScroller instance and flings become active _(integer, default 1)_
 * `scrollingClassName` The classname to add to the scroller container when it is being actively scrolled.  This is disabled by default as it can cause a CSS relayout if enabled, but allows custom styling in response to scrolls _(string, default not set)_
 * `scrollResponseBoundary` The initial movement required to trigger a visual scroll update, in pixels _(integer, default 1)_
 * `scrollingX` Enable scrolling on the X axis if content is available _(boolean, default true)_
 * `scrollingY` Enable scrolling on the Y axis if content is available _(boolean, default true)_
+* `singlePageScrolls` _(was `paginatedSnap`)_ If snapping is enabled, restricts each scroll movement to one 'page' span.  That is, if set to true, it will not be possible to move more than one page in a single movement. _(boolean, default false)_
 * `snapping` Enable snapping of content to defined 'pages' or segments _(boolean, default false)_
 * `snapSizeX` Define the horizontal interval content should snap to, in pixels.  If this is not set, snapping will be based on pages corresponding to the container size. _(numeric, default undefined)_
 * `snapSizeY` Define the vertical interval content should snap to, in pixels.  If this is not set, snapping will be based on pages corresponding to the container size. _(numeric, default undefined)_

examples/horizontalpaged-strict.html

@@ -38,8 +38,9 @@
 		var scroller = new FTScroller(document.getElementById('scrollable'), {
 			scrollingY: false,
 			snapping: true,
-			paginatedSnap: true,
-			scrollbars: false
+			singlePageScrolls: true,
+			scrollbars: false,
+			bouncing: false
 		});
 	</script>
 </body>

lib/ftscroller.js

@@ -236,9 +236,9 @@ var FTScroller, CubicBezier;
 			// take effect.  If this is not defined, snapping will use intervals based on container size.
 			snapSizeY: undefined,
 
-			// Control whether snapping should be fully paginated, only ever flicking to the next page
+			// Control whether snapping should be curtailed to only ever flick to the next page
 			// and not beyond.  Snapping needs to be enabled for this to take effect.
-			paginatedSnap: false,
+			singlePageScrolls: false,
 
 			// Allow scroll bouncing and elasticity near the ends and grid
 			bouncing: true,
@@ -401,8 +401,18 @@ var FTScroller, CubicBezier;
 		// Override default and global options with supplied options
 		if (options) {
 			for (key in options) {
-				if (options.hasOwnProperty(key) && _instanceOptions.hasOwnProperty(key)) {
-					_instanceOptions[key] = options[key];
+				if (options.hasOwnProperty(key)) {
+
+					// If a deprecated flag was passed in, warn, and convert to the new flag name
+					if ('paginatedSnap' === key) {
+						console.warn('FTScroller: "paginatedSnap" is deprecated; converting to "singlePageScrolls"');
+						_instanceOptions.singlePageScrolls = options.paginatedSnap;
+						continue;
+					}
+
+					if (_instanceOptions.hasOwnProperty(key)) {
+						_instanceOptions[key] = options[key];
+					}
 				}
 			}
 
@@ -1084,9 +1094,9 @@ var FTScroller, CubicBezier;
 						}
 					}
 
-					// In paginated snapping mode, determine the page to snap to - maximum
-					// one page in either direction from the current page.
-					if (_instanceOptions.paginatedSnap && _instanceOptions.snapping) {
+					// In single-page-scroll mode, determine the page to snap to - maximum one page
+					// in either direction from the *start* page.
+					if (_instanceOptions.singlePageScrolls && _instanceOptions.snapping) {
 						flingStartSegment = -_lastScrollPosition[axis] / _snapGridSize[axis];
 						if (_baseSegment[axis] < flingStartSegment) {
 							flingStartSegment = Math.floor(flingStartSegment);
@@ -1095,10 +1105,10 @@ var FTScroller, CubicBezier;
 						}
 
 						// If the target position will end up beyond another page, target that page edge
-						if (flingPosition > -(flingStartSegment - 1) * _snapGridSize[axis]) {
-							bounceDistance = flingPosition + (flingStartSegment - 1) * _snapGridSize[axis];
-						} else if (flingPosition < -(flingStartSegment + 1) * _snapGridSize[axis]) {
-							bounceDistance = flingPosition + (flingStartSegment + 1) * _snapGridSize[axis];
+						if (flingPosition > -(_baseSegment[axis] - 1) * _snapGridSize[axis]) {
+							bounceDistance = flingPosition + (_baseSegment[axis] - 1) * _snapGridSize[axis];
+						} else if (flingPosition < -(_baseSegment[axis] + 1) * _snapGridSize[axis]) {
+							bounceDistance = flingPosition + (_baseSegment[axis] + 1) * _snapGridSize[axis];
 
 						// Otherwise, if the movement speed was above the minimum velocity, continue
 						// in the move direction.
@@ -1347,15 +1357,28 @@ var FTScroller, CubicBezier;
 		 * scroll position render if a requestAnimationFrame loop isn't active
 		 */
 		_constrainAndRenderTargetScrollPosition = function _constrainAndRenderTargetScrollPosition() {
-			var axis;
+			var axis, upperBound, lowerBound;
 
 			// Update axes target positions if beyond bounds
 			for (axis in _scrollableAxes) {
 				if (_scrollableAxes.hasOwnProperty(axis)) {
-					if (_targetScrollPosition[axis] > 0) {
-						_targetScrollPosition[axis] = _modifyDistanceBeyondBounds(_targetScrollPosition[axis], axis);
-					} else if (_targetScrollPosition[axis] < _metrics.scrollEnd[axis]) {
-						_targetScrollPosition[axis] = _metrics.scrollEnd[axis] + _modifyDistanceBeyondBounds(_targetScrollPosition[axis] - _metrics.scrollEnd[axis], axis);
+
+					// Set bounds to the left and right of the container
+					upperBound = 0;
+					lowerBound = _metrics.scrollEnd[axis];
+
+					if (_instanceOptions.singlePageScrolls && _instanceOptions.snapping) {
+
+						// For a single-page-scroll, set the bounds to the left and right of the
+						// current segment
+						upperBound = Math.min(upperBound, -(_baseSegment[axis] - 1) * _snapGridSize[axis]);
+						lowerBound = Math.max(lowerBound, -(_baseSegment[axis] + 1) * _snapGridSize[axis]);
+					}
+
+					if (_targetScrollPosition[axis] > upperBound) {
+						_targetScrollPosition[axis] = upperBound + _modifyDistanceBeyondBounds(_targetScrollPosition[axis] - upperBound, axis);
+					} else if (_targetScrollPosition[axis] < lowerBound) {
+						_targetScrollPosition[axis] = lowerBound + _modifyDistanceBeyondBounds(_targetScrollPosition[axis] - lowerBound, axis);
 					}
 				}
 			}