YUI Library Examples: ScrollView: ScrollView Paginator Plugin

ScrollView: ScrollView Paginator Plugin

ScrollView with Pagination Support

In this example, we'll create a ScrollView instance which has pagination support enabled. This allows the ScrollView to scroll between discrete page boundaries in the content, as opposed to continuous scrolling. Pagination is only supported for horizontal ScrollViews currently.

Modules Used

For this example, since we want both pagination and scrollbar indicator support enabled, we use the scrollview module as we did for the Horizontal ScrollView example to get the base ScrollView with scrollbar support.

Additionally we pull down the scrollview-paginator module, which provides the ScrollViewPaginator plugin:

 
// Pull in the scrollview widget, and the paginator plugin
 
YUI().use('scrollview', 'scrollview-paginator', function(Y) {
    ...
});
 

 
// Pull in the scrollview widget, and the paginator plugin
 
YUI().use('scrollview', 'scrollview-paginator', function(Y) {
    ...
});
 

Instantiating The ScrollView Widget

As with the Horizontal ScrollView example, we provide the markup for the ScrollView content on the page, as shown below:

<!-- Content with a width which would require scrolling -->
<div id="scrollable" style="" class="yui3-scrollview-loading paged">
    <ul>
        <li><img src="..."></li>
        <li><img src="..."></li>
        <li><img src="..."></li>
        <li><img src="..."></li>
    </ul>
</div>

<!-- Content with a width which would require scrolling -->
<div id="scrollable" style="" class="yui3-scrollview-loading paged">
    <ul>
        <li><img src="..."></li>
        <li><img src="..."></li>
        <li><img src="..."></li>
        <li><img src="..."></li>
    </ul>
</div>

And we instantiate the ScrollView instance in the same way, by providing a fixed width for the widget, and preventing default image drag behavior for gecko:

// Constraining the width, instead of the height for horizontal scrolling
var scrollView = new Y.ScrollView({
    srcNode: '#scrollable',
    width: 320,
    flick : {
        preventDefault:function(e) {
            // Prevent image drag in gecko (assuming non-touch for this example).
            return (Y.UA.gecko);
        },
        minDistance:10,
        minVelocity:0.3
    }
});

// Constraining the width, instead of the height for horizontal scrolling
var scrollView = new Y.ScrollView({
    srcNode: '#scrollable',
    width: 320,
    flick : {
        preventDefault:function(e) {
            // Prevent image drag in gecko (assuming non-touch for this example).
            return (Y.UA.gecko);
        },
        minDistance:10,
        minVelocity:0.3
    }
});

This gives us a ScrollView instance with scrollbar indicator support. However it doesn't have pagination support available yet.

Plugging In Pagination Support

To add pagination support to the ScrollView instance, we plug in the ScrollViewPaginator plugin, providing the selector attribute configuration argument to it. The selector tells the paginator which list of elements inside the ScrollView content box define page boundaries at which the ScrollView should stop when scrolling. For this example, each LI defines a ScrollView page:

scrollView.plug(Y.Plugin.ScrollViewPaginator, {
    selector: 'li'
});

scrollView.plug(Y.Plugin.ScrollViewPaginator, {
    selector: 'li'
});

The ScrollView now has pagination support activated, and will stop at page boundaries when the user flicks the content, or drags the content past the halfway point of the current page.

Accessing The Paginator Plugin API

Similar to the ScrollBar indicator plugin, the ScrollBarPaginator API is now available on the ScrollView instance, on the namespace defined by the plugin, which is scrollView.pages. The pages property can be used to manage the page state of the ScrollView, as shown below:

Y.one('#next-page').on('click', Y.bind(scrollView.pages.next, scrollView.pages));
Y.one('#prev-page').on('click', Y.bind(scrollView.pages.prev, scrollView.pages));

Y.one('#next-page').on('click', Y.bind(scrollView.pages.next, scrollView.pages));
Y.one('#prev-page').on('click', Y.bind(scrollView.pages.prev, scrollView.pages));

The above code calls the plugin's next() and prev() methods when the respective button is clicked. The ScrollView Paginator documentation provides additional examples of the API available through the pages property.

Setting Up A Click Listener

For this example, we also set up a click listener on the images. For touch devices, the click event does not fire when dragging or flicking, so there's no special handling required when setting up a click listener. However for to also support mouse based devices, we need to distinguish between a click and drag or flick. In order to do this we set up a check in our click listener, to make sure we only respond to the click if the ScrollView wasn't dragged, by checking the lastScrolledAmt property, which is reset whenever a drag/flick gesture ends:

Y.one("#scrollable").delegate("click", function(e) {
    // For mouse based devices, we need to make sure the click isn't fired
    // and the end of a drag/scroll. We use 2 as an arbitrary threshold.
    if (Math.abs(scrollView.lastScrolledAmt) < 2) {
        alert(e.currentTarget.getAttribute("alt"));
    }
}, "img");

Y.one("#scrollable").delegate("click", function(e) {
    // For mouse based devices, we need to make sure the click isn't fired
    // and the end of a drag/scroll. We use 2 as an arbitrary threshold.
    if (Math.abs(scrollView.lastScrolledAmt) < 2) {
        alert(e.currentTarget.getAttribute("alt"));
    }
}, "img");