wink 1.4.4 released!

tutorials

Migrating to scroller v2

Migrating from version 1.0 to 1.1
The Wink Scroller component was revised and corrected: it has a better reactivity and extra features.
The instantiation and public methods are different from the previous version:
  • - Method 'setViewportSize' has been renamed 'updateViewportSize'
  • - Method 'setEdges' has been renamed 'updateTargetSize' with removal of the concept of offset
  • - Method 'autoUpdateEdges' is now equivalent to 'updateTargetSize' without parameters
  • - Properties 'viewportSizeX' and 'viewportSizeY' have been removed
The container sizes and management
To operate correctly the component, it is necessary to have two HTML containers :
  • - a container with a hidden overflow style corresponding to the visible area
  • - a target, inside the container, corresponding to the content area (property 'target' of the scroller)
<html>
<head>
	<style>
		#wrapper {
			overflow: hidden;
			height: 300px;
		}
		
		#scrollContent {
			position: relative;
		}
	</style>
	<script type="text/javascript">
		var init = function() {
			var scroller = new wink.ui.layout.Scroller({
				target: "scrollContent",
				direction: "y"
			});
		};
	</script>
</head>
	
<body onload="init();">
	<div id="wrapper">
		<div id="scrollContent"></div>
	</div>
</body>
</html>
At the instantiation, the Scroller takes as default parameters :
  • - properties 'offsetHeight' and 'offsetWidth' of the target,
  • - properties 'clientHeight' and 'clientWidth' of the target's parent
Managing the size of the visible area and the area of content is essential for the proper functioning of the Scroller. The user has two options:
  • - use the default sizes of the containers (the simplest)
  • - specify sizes calculated manually
In the first case, the parameters of the methods 'updateTargetSize' and 'updateViewportSize' are then optional. These methods should be invoked when the content changes or when the size of the visible area changes. Another method was introduced: 'autorefresh', it allows the component to manage content changes and thus to adjust these settings.
New features
Among the new features, we find:
  • - the scrollbars : their display is configurable (active, width, color)
  • - the stage callbacks : the user can specify the methods to be called at different stages of the scroll: 'scrollerTouched, startScrolling, startSliding ...'. This allows for example to manage the activation of elements.
  • - the methods 'enable' and 'disable' that allows the user to temporarily disable the scroller
  • - the methods 'changeContext' and 'destroy' that minimize the number of objects in memory if the scroller has a limited life or if it has to be used for different content.
These features help to address the constraints imposed by the component : in fact, stopping the native behavior of your browser to prevent the native scroll has limitations. The user must rely on callbacks to know which elements of content are affected and thus adapt the behavior: this is particularly the case for form fields. The form elements are problematic because they are strongly related to native behavior of the browser and it is sometimes not possible to recreate the default behavior. Moreover, the differences are significant between different platforms (eg iPhone vs. Android).
Use case
Change the style of content elements when the user interacts with the scroller:
var helper = {
	scrollerTouched: function(params) {
		var target = params.uxEvent.target;
		wink.addClass(target, "active");
	},
	scrollerClicked: function(params) {
		var target = params.uxEvent.target;
		wink.removeClass(target, "active");
		wink.addClass(target, "selected");
	}
};

var scroller = new wink.ui.layout.Scroller({
	target: "scrollContent",
	direction: "y",
	callbacks: {
		scrollerTouched: { context: helper, method: 'scrollerTouched' },
		scrollerClicked: { context: helper, method: 'scrollerClicked' }
	}
});
Problematic case of the HTML 'Select' which produces a native scroll : we disable the scroller when such element is affected, we will reinstate after the next hit. Specificity of the 'Select' element : we remove the overflow so that the offset introduced by the focus () is canceled.
var helper = {
	_disable: false,

	scrollerTouched: function(params) {
		var target = params.uxEvent.target;
		
		if (target instanceof HTMLSelectElement) {
			$('wrapper').style.overflow = "visible";
			scroller.disable();
			this._disable = true;
		} else if (this._disable) {
			scroller.enable();
			window.scrollTo(0, 0);
			$('wrapper').style.overflow = "hidden";
			this._selectNode = null;
			this._disable = false;
		}
	}
};

var scroller = new wink.ui.layout.Scroller({
	target: "scrollContent",
	direction: "y",
	callbacks: {
		scrollerTouched: { context: helper, method: 'scrollerTouched' }
	}
});