iScroll 4 is a complete rewrite of the original iScroll code. The script development began because mobile webkit (on iPhone, iPad, Android) does not provide a native way to scroll content inside a fixed width/height element. This unfortunate situation prevents any web-app to have a position:absolute header and/or footer and a scrolling central area for contents.

While latest Android revisions are supporting this functionality (although support is not optimal), Apple seems reluctant to add one finger scrolling to divs.

In addition to all previous iScroll features, version 4 introduces:

• Pinch / Zoom
• Pull up/down to refresh
• Improved speed and momentum
• Snap to element
• Customizable scrollbars

Please note that iScroll 4 is not a drop-in replacement for iScroll 3. The APIs have changed.

Also consider that the script is still in beta, and some APIs may slightly change.

Getting started

In the archive you’ll find plenty of examples to get you started. Before asking for help, please, look at the demos and read through all this document. I know it’s boring, but it holds all the secrets of the iScroll Ninja.

iScroll needs to be initialized for each scrolling area you need. There’s no limit to the number of iScrolls you can have on any single page, if not that imposed by the device memory/cpu. The type and length of the contents influence the number of iScrolls you can use simultaneously.

Try to keep the DOM structure as simple as possible, remove all the unnecessary tags and avoid too many nested elements.

The optimal iScroll structure is:

<div id="wrapper">
	<ul>
		<li></li>
		...
		...
	</ul>
</div>

In this example the UL element will be scrolled. The iScroll must be applied to the wrapper of the scrolling area.

Important: only the first child of the wrapper element will be scrolled. If you need more elements inside the scroller you may use the following structure:

<div id="wrapper">
	<div id="scroller">
		<ul>
			<li></li>
			...
			...
		</ul>

		<ul>
			<li></li>
			...
			...
		</ul>
	</div>
</div>

In this example the scroller element will be scrolled (together with the two ULs).

iScroll be must instantiated (ie: called for the first time) when the DOM is ready. You have mainly four options:

• onDOMContentLoaded event
• onLoad event
• inline, place the code below the html bit you want to scroll

onDOMContentLoaded

If you have only text and all images have fixed dimensions (ie: explicit width/height) you may use the DOMContentLoaded event.

In the document HEAD add:

<script type="application/javascript" src="iscroll.js"></script>
<script type="text/javascript">
var myScroll;
function loaded() {
	myScroll = new iScroll('wrapper');
}
document.addEventListener('DOMContentLoaded', loaded, false);
</script>

Note that the myScroll variable is global, so that you can access all the scroller functions from anywhere.

onLoad

Sometimes the DOMContentLoaded is a bit hasty and get fired when the contents are not ready. If you slip into some weird behaviors (eg: rubber band effect), try the following:

<script type="application/javascript" src="iscroll.js"></script>
<script type="text/javascript">
var myScroll;
function loaded() {
	setTimeout(function () {
		myScroll = new iScroll('wrapper');
	}, 100);
}
window.addEventListener('load', loaded, false);
</script>

In this case iScroll is started only 100ms after the page is completely loaded (graphics included). This is probably the safest way to call the iScroll.

Inline initialization

With this method the iScroll is instantiated as soon as the wrapper and its contents are written to the page. I wouldn’t suggest this approach, but I see many javascript gurus using it… so who am I to disagree?

First of all include the iscroll.js in the page HEAD and then create the iScroll object just below the scroller.

<div id="wrapper">
	<ul>
		<li></li>
		...
		...
	</ul>
</div>

<script type="text/javascript">
var myScroll = new iScroll('wrapper');
</script>

Alternatively you may use your preferred framework ready function (eg:jquery ready()).

Read more:http://cubiq.org/iscroll-4