pagePiling.js Library – Sergei Ermilov

pagePiling.js is a library that allows you to stack website sections on top of one another and open them by scrolling or via a URL.

Introduction

The main purpose of the pagePiling.js library is to create a landing page where switching between main sections is done via a full-screen slider or scrolling.

In other words, this type of website or landing page can be described as a full-screen scroll or a fixed-scroll page.

pagePiling.js on GitHub

Demo

Compatibility

pagePiling.js works fully in all modern browsers, as well as in some older ones, such as Internet Explorer 8, 9, Opera 12, and others. It works in both browsers that support CSS3 and those that do not, making it ideal for compatibility with older browsers.

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

Usage

As you can see in the example files, you need to include the plugin’s JavaScript file jquery.pagepiling.js (or the minified version jquery.pagepiling.min.js) and the CSS file jquery.pagepiling.css, as well as jQuery.

Optionally, you can add the jQuery UI library if you want to use animation effects other than those included in the jQuery library, specifically the linear or swing effects.

Installation using Bower

Alternatively, you can install pagePiling.js using Bower: Terminal:

bower install pagepiling.js

Including the Files

<link rel="stylesheet" type="text/css" href="jquery.pagepiling.css" />

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
<script type="text/javascript" src="jquery.pagepiling.js"></script>

Optional Use of a CDN

If you prefer to use a CDN to load the necessary files, pagePiling.js is available on CDNJS.

Required HTML Structure

Each section will be defined using div, which contains the class section. By default, the first section—which is treated as the home page—will be the active section.

<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 the function $(document).ready:

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

A more complex initialization with all options set might 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(){},
	});
});

Accessing Sections

To create links to a specific section, you can use a regular URL if you’re using pagePiling.js with anchor links (using the anchors), you can also use anchor links to jump directly to a specific section.

For example: http://alvarotrigo.com/pagePiling/#page2

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

Using the Menu

To link a menu to the active section, you must use the menu and use anchor links (#), as described in the options section of this documentation.

Creating a scrollable section

If you want to have a section with a large amount of content and create a scrollbar for that section, you can do so by adding the class pp-scrollable to that section:

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

Options

verticalCentered: (default true) Vertically center the content within sections.
scrollingSpeed: (default 700) Speed in milliseconds for scroll transitions.
sectionsColor: (default: none) Sets the CSS `background-color` property for each section: Example:

$('#pagepiling').pagepiling({
    sectionsColor: ['#f2f2f2', '#4BBFC3', '#7BAABE', 'whitesmoke', '#000'],
});

anchors: (default []) Specifies anchor links (#example) that will appear in the URL for each section. When using anchors, forward and backward navigation will also be possible via the browser. This option also allows users to bookmark a specific section. Please note! If you use anchors, they cannot have the same value as any ID element on the site (or NAME element for IE).

Important! It’s important to understand that the values in the `anchors` options array correspond directly to the element with the `.section` class based on its position in the markup.

easing: (default swing) Specifies the transition effect to be used for vertical scrolling. To use any transition other than swing and linear, jQuery UI is required. Alternatively, you can use other libraries.
loopTop: (default false) Specifies whether scrolling up in the first section should scroll to the end or not.
loopBottom: (default false) Determines whether scrolling down in the last section should scroll to the first section or not.
css3: (default true). Determines whether to use JavaScript or CSS3 transitions for scrolling within sections. This is useful for speeding up navigation on tablets and mobile devices with browsers that support CSS3. If this option is set to true and the browser does not support CSS3, a jQuery fallback will be used instead.
normalScrollElements: (default null) If you want to prevent auto-scrolling when hovering over certain elements, you should use this option. (Useful for maps, scrollable divs, etc.) This requires a string containing jQuery selectors for those elements. (For example: normalScrollElements: '#element1, .element2')
normalScrollElementTouchThreshold: (default 5) Sets the threshold for the number of steps up the HTML node tree that pagePiling will check to determine whether normalScrollElementsto enable scrolling of divs on a touchscreen device. (For example: normalScrollElementTouchThreshold: 3)
keyboardScrolling: (default true) Determines whether the content can be navigated using the keyboard.
touchSensitivity: (default 5) Specifies the percentage of the browser window’s width/height and the distance you need to swipe to move to the next section.
animateAnchor: (default true) Determines whether, when an anchor (#) is specified, the page will scroll with an animation to the destination or load directly to the specified section.
direction: (default vertical) Determines whether scrolling will be vertical or horizontal.
menu: (default false) A selector can be used to specify the menu that will be linked to the sections. Thus, when scrolling through the sections, the corresponding menu item will be activated using the active. The menu itself is not created; instead, a class is simply added active to the menu item with the corresponding anchor links. To link menu items to sections, you must use the HTML5 `data-tag` (data-menuanchor) with the same anchor links used in the sections. Example:

<ul id="myMenu">
    <li data-menuanchor="firstPage" class="active"><a href="#firstPage">First section</a></li>
    <li data-menuanchor="secondPage"><a href="#secondPage">Second section</a></li>
    <li data-menuanchor="thirdPage"><a href="#thirdPage">Third section</a></li>
    <li data-menuanchor="fourthPage"><a href="#fourthPage">Fourth section</a></li>
</ul>

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

Note! The menu item must be placed outside the `pagePiling` wrapper (in the example above id="pagepiling") to avoid issues when using css3:true. Otherwise, it will be added to body the plugin itself.

navigation: (by default false) If you set the value to true, a navigation bar consisting of small circles will be displayed.
sectionSelector: (default .section) Specifies the jQuery selector used for the plugin’s sections. Sometimes you’ll need to change this to avoid conflicts with other plugins that use the same selectors as pagePiling.js.

Methods

moveSectionUp()

Moves a single section up:

$.fn.pagepiling.moveSectionUp();

moveSectionDown()

Scrolls one section down:

$.fn.pagepiling.moveSectionDown();

moveTo(section)

Scrolls the page to the specified section.

/* Прокрутка до раздела с якорной ссылкой `firstSection`  */
$.fn.pagepiling.moveTo('firstSection');

// Прокрутка до 3-го раздела на сайте
$.fn.pagepiling.moveTo(3);

// Что то же самое, что
$.fn.pagepiling.moveTo(3);

setAllowScrolling(boolean)

Enables or disables the ability to scroll through sections using the mouse wheel/trackpad or touch gestures (this function is enabled by default).

$.fn.pagepiling.setAllowScrolling(false);

setKeyboardScrolling(boolean)

Enables or disables the ability to scroll through sections using the keyboard arrow keys (this feature is enabled by default).

$.fn.pagepiling.setKeyboardScrolling(false);

setScrollingSpeed(milliseconds)

Sets the scrolling speed in milliseconds.

$.fn.pagepiling.setScrollingSpeed(700);

Callbacks

afterLoad (anchorLink, index)

A callback executed after sections have loaded and scrolling has finished. Parameters:

anchorLink: anchorLink corresponding to the section.
index: section index. Starts at 1.

If no anchorLinks are defined in the plugin, the index will be the only one that can be used.

Example:

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

		afterLoad: function(anchorLink, index){
			//использование index
			if(index == 3){
				alert("Section 3 ended loading");
			}

			//использование anchorLink
			if(anchorLink == 'secondPage'){
				alert("Section 2 ended loading");
			}
		}
	});

onLeave (index, nextIndex, direction)

This callback is triggered when the user leaves a section and navigates to a new section.

Parameters:

index: the index of the section being left. Starts at 1.
nextIndex: Index of the destination section. Starts at 1.
direction: will take the values up or down depending on the scroll direction.

Example:

$('#pagepiling').pagepiling({
		onLeave: function(index, nextIndex, direction){
			//после покидания раздела 2
			if(index == 2 && direction =='down'){
				alert("Идем в раздел 3!");
			}

			else if(index == 2 && direction == 'up'){
				alert("Идем в раздел 1!");
			}
		}
	});

afterRender()

This callback is executed immediately after the page structure is generated. This callback can be used to initialize other plugins or run any code that requires the document to be ready (since this plugin modifies the DOM to create the resulting structure).

Example:

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

License

(The MIT License)

Permission is hereby granted, free of charge, to any person who has received a copy of this software and the accompanying documentation files (“Software”) to use the Software without restriction, including, without limitation, the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, as well as to permit those to whom the Software is provided to do so, subject to the following conditions:

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

THE SOFTWARE IS PROVIDED “AS IS,” WITHOUT ANY WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. UNDER NO CIRCUMSTANCES SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIMS, damages, or other liabilities, whether in contract, tort, or otherwise, ARISING OUT OF, IN CONNECTION WITH, OR AS A RESULT OF THE SOFTWARE, ITS USE, OR OTHER OPERATIONS INVOLVING IT.