search

alvarotrigo / pagePiling.js

pagePiling plugin by Alvaro Trigo. Create a scrolling pile of sections. http://alvarotrigo.com/pagePiling/
4.1k stars 653 forks source link
javascript jquery mousewheel onepage scrolling slide snap swipe

readme

pagePiling.js

preview compatibility\ Pile your sections one over another and access them scrolling or by URL!

pagePiling.js version

Invite me to a coffee Donate

Customizations of the plugin available upon request for some reasonable price. Contact me.

Would you like to have a website using pilePage.js functionality but you don't know how to use it? I can do it for you for a reasonable price. Contact me.

Introduction

Suggestion are more than welcome, not only for feature requests but also for coding style improvements. Let's make this a great plugin to make people's lives easier!

Compatibility

pagePiling.js is fully functional on all modern browsers, as well as some old ones such as Internet Explorer 8, 9, Opera 12, etc. It works with browsers with CSS3 support and with the ones which don't have it, making it ideal for old browsers compatibility.

It is also designed to work on touch devices such as mobile phones or tablets.

Browserstack

Special thanks to Browserstack for supporting pagePiling.js.

Usage

As you can see in the example files, you will need to include the JavaScript file jquery.pagepiling.js (or the minified version jquery.pagepiling.min.js) and the css file jquery.pagepiling.css of the plugin, as well as jQuery. Optionally, you can add the jQuery UI library in case you want to use other easing effects apart from the ones included in the jQuery library which are the linear or swing effects.

Install using bower:

Optionally, you can install pagePiling.js with bower: Terminal:

bower install pagepiling.js

Including files:

<link rel="stylesheet" type="text/css" href="https://github.com/alvarotrigo/pagePiling.js/blob/master/jquery.pagepiling.css" />

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
<script type="text/javascript" src="https://github.com/alvarotrigo/pagePiling.js/raw/master/jquery.pagepiling.js"></script>

Optional use of CDN

If you prefer to use a CDN to load the needed files, pagePiling.js is in CDNJS: https://cdnjs.com/libraries/pagePiling.js

Required HTML structure

Each section will be defined with a div containing the section class. The active section by default will be the first section, which is taken as the home page.

<div id="pagepiling">
    <div class="section">Some section</div>
    <div class="section">Some section</div>
    <div class="section">Some section</div>
    <div class="section">Some section</div>
</div>

Initialization

All you need to do is call the plugin inside a $(document).ready function:

$(document).ready(function() {
    $('#pagepiling').pagepiling();
});

A more complex initialization with all options set could look like this:

$(document).ready(function() {
    $('#pagepiling').pagepiling({
        menu: null,
        direction: 'vertical',
        verticalCentered: true,
        sectionsColor: [],
        anchors: [],
        scrollingSpeed: 700,
        easing: 'swing',
        loopBottom: false,
        loopTop: false,
        css3: true,
        navigation: {
            'textColor': '#000',
            'bulletsColor': '#000',
            'position': 'right',
            'tooltips': ['section1', 'section2', 'section3', 'section4']
        },
        normalScrollElements: null,
        normalScrollElementTouchThreshold: 5,
        touchSensitivity: 5,
        keyboardScrolling: true,
        sectionSelector: '.section',
        animateAnchor: false,

        //events
        onLeave: function(index, nextIndex, direction){},
        afterLoad: function(anchorLink, index){},
        afterRender: function(){},
    });
});

Accesing sections

In order to create links to a certain section, you can use a normal URL link if you are using pagePiling.js with anchor links (using the anchors option), then you will be able to use anchor links also to navigate directly to a certain section. For example: http://alvarotrigo.com/pagePiling/#page2

Be careful! data-anchor tags can not have the same value as any ID element on the site (or NAME element for IE).

Using a menu

To link the menu with the active section you will have to use the menu option and make use of anchor links (#) as explained below in the options section.

Creating a scrollable section

In case you want to have a section with large content and therefore create an scroll bar for that section, you can do it by adding the class pp-scrollable to that section:

<div class="section pp-scrollable"></div>

Options

Important It is helpful to understand that the values in the anchors option array correlate directly to the element with the class of .section by it's position in the markup.

Note: the menu element should be placed outside the pagePiling wrapper in order to avoid problem when using css3:true. Otherwise it will be appended to the body by the plugin itself.

Methods

moveSectionUp()

Scrolls one section up:

$.fn.pagepiling.moveSectionUp();

moveSectionDown()

Scrolls one section down:

$.fn.pagepiling.moveSectionDown();

moveTo(section)

Scrolls the page to the given section.

/*Scrolling to the section with the anchor link `firstSection`  */
$.fn.pagepiling.moveTo('firstSection');

//Scrolling to the 3rd section in the site
$.fn.pagepiling.moveTo(3);

//Which is the same as
$.fn.pagepiling.moveTo(3);

setAllowScrolling(boolean)

Adds or remove the possibility of scrolling through sections by using the mouse wheel/trackpad or touch gestures (which is active by default).

$.fn.pagepiling.setAllowScrolling(false);

setKeyboardScrolling(boolean)

Adds or remove the possibility of scrolling through sections by using the keyboard arrow keys (which is active by default).

$.fn.pagepiling.setKeyboardScrolling(false);

setScrollingSpeed(milliseconds)

Defines the scrolling speed in milliseconds.

$.fn.pagepiling.setScrollingSpeed(700);

Callbacks

afterLoad (anchorLink, index)

Callback fired once the sections have been loaded, after the scrolling has ended. Parameters:

In case of not having anchorLinks defined in the plugin the index parameter would be the only one to use.

Example:

    $('#pagepiling').pagepiling({
        anchors: ['firstPage', 'secondPage', 'thirdPage', 'fourthPage', 'lastPage'],

        afterLoad: function(anchorLink, index){
            //using index
            if(index == 3){
                alert("Section 3 ended loading");
            }

            //using anchorLink
            if(anchorLink == 'secondPage'){
                alert("Section 2 ended loading");
            }
        }
    });

onLeave (index, nextIndex, direction)

This callback is fired once the user leaves a section, in the transition to the new section.

Parameters:

Example:

    $('#pagepiling').pagepiling({
        onLeave: function(index, nextIndex, direction){
            //after leaving section 2
            if(index == 2 && direction =='down'){
                alert("Going to section 3!");
            }

            else if(index == 2 && direction == 'up'){
                alert("Going to section 1!");
            }
        }
    });

afterRender()

This callback is fired just after the structure of the page is generated. This is the callback you want to use to initialize other plugins or fire any code which requires the document to be ready (as this plugin modifies the DOM to create the resulting structure).

Example:

    $('#pagepiling').pagepiling({
        afterRender: function(){
            alert("The resulting DOM structure is ready");
        }
    });

Resources

CSS Easing Animation Tool - Matthew Lein

Who is using pagePiling.js

If you want your page to be listed here. Please contact me with the URL.

Facebook WaltDisney Logitech

Donations

Donations would be more than welcome :)

Donate

License

(The MIT License)

Copyright (c) 2014 Alvaro Trigo <alvaro@alvarotrigo.com>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.