How I Built The One Page Scroll Plugin

First, I’ve defined a default variable to activate this fallback. The responsiveFallback is used to determine when the plugin should trigger the fallback.

The snippet above will detect the browser’s width to determine whether the responsive function should run. If the width reaches the value defined in responsiveFallback, then the function will unbind all of the events, such as swiping and scrolling, return the user to the top of the page to prepare for realignment of each section, and then reenable the browser’s default scrolling behavior so that the user can swipe through the page as usual. If the width exceeds the value defined, then the plugin checks for a class of disabled-onepage-scroll to determine whether it has already been initialized; if it hasn’t, then it is reinitialized again.

The solution is not ideal, but it gives the option for designers and developers to choose how to handle their websites on mobile, rather than forcing them to abandon mobile.

6. Cross-Browser Testing

Testing is an essential part of the development process, and before you can release a plugin, you must make sure that it runs well on the majority of machines out there. Chrome is my go-to browser, and I always start developing in it. It has many benefits as one’s main development browser, but your personal preference might vary. For me, Chrome has a more efficient inspection tool. Also, when I get a plugin to work in Chrome, I know that it will probably also work in Safari and Opera as well.

I mainly use my Macbook Air to develop plugins, but I also have a PC at home to check across platforms. When I get a plugin to work in Chrome, then I’ll test manually in Safari, Opera and (lastly) Firefox on Mac OS X, followed by Chrome, Firefox and Internet Explorer (IE) 10 on Windows.

The reason I test only these browsers is that the majority of users are on them. I could have tested IE 9 and even IE 8, but that would have prevented me from releasing the plugin in time with the launch of the iPhone 5S website.

This is generally not a good practice, and I’ll avoid doing it in future. But the good thing about making the plugin open-source is that other developers can help patch it after its release. After all, the purpose of an open-source project is not to create the perfect product, but to create a jumping-off point for other developers to extend the project to be whatever they want it to be.

⁸

To ease the pain of cross-browser testing, every time I complete a plugin, I’ll create a demo page to show all of the features of the plugin, and then I’ll upload it to my website and test it, before sharing the plugin on GitHub. This is important because it enables you to see how the plugin performs in a real server environment and to squash any bugs that you might not be able to replicate locally. Once the demo page is up and running on my website, I’ll take the opportunity to test the plugin on other devices, such as phones and tablets.

With these tests, you will have covered the vast majority of browsers out there and prepared the plugin for the real world.

7. Open-Sourcing Your Plugin

When you think the plugin is ready, the final step is to share it on GitHub. To do this, create an account on GitHub, set up Git¹⁰ and create a new repository¹¹. Once that is done, clone the repository to your local machine. This should generate a folder with your plugin’s name on your local machine. Copy the plugin to the newly created folder and structure your repository.

Repository Structure

How you structure your repository is all up to you. Here’s how I do it:

• The demo folder consists of working demos, with all required resources.
• The minified and normal versions of the plugin are in the root folder.
• The CSS and sample resources, such as images (if the plugin requires it), are in the root folder.
• The readme file is in the root directory of the generated folder.

Readme Structure

Another important step is to write clear instructions for the open-source community. Usually, all of my instructions are in a readme file, but if yours require a more complex structure, you could go with a wiki page on GitHub. Here is how I structure my readme:

1. Introduction
   I explained the purpose of the plugin, accompanied by an image and a link to the demo.
2. Requirements and compatibility
   Put this up front so that developers can see right away whether they’ll want to use the plugin.
3. Basic usage
   This section consists of step-by-step instructions, from including the jQuery library to adding the HTML markup to calling the function. This section also explains the options available for developers to play with.
4. Advanced usage
   This section contains more complex instructions, such as any public methods and callbacks and any other information that developers would find useful.
5. Other resources
   This section consists of links to the tutorial, credits, etc.

8. Widening Support

This plugin doesn’t really need the jQuery library to do what it does, but because of the pressure to open-source it in time for the iPhone 5S website, I decided to take a shortcut and rely on jQuery.

To make amends, and exclusively for Smashing Magazine’s readers, I have rebuilt One Page Scroll using pure JavaScript (a Zepto version is also available). With the pure JavaScript version, you no longer need to include jQuery. The plugin works right out of the box.

Pure JavaScript And Zepto Version

• Pure JavaScript Repository¹²
• Zepto repository¹³

Rebuilding the Plugin in Pure JavaScript

The process of building support for libraries can seem daunting at first, but it’s much easier than you might think. The most difficult part of building a plugin is getting the math right. Because I had already done that for this one, transforming the jQuery plugin into a pure JavaScript one was just a few hours of work.

Because the plugin relies heavily on CSS3 animation, all I had to do was replace the jQuery-specific methods with identical JavaScript methods. Also, I took the opportunity to reorganize the JavaScript into the following standard structure:

• Default variables
  This is essentially the same as the jQuery version, in which I defined all of the variables, including the default variables for options to be used by other functions.
• Initialize function
  This function is used for preparing and positioning the layout and for the initialization that is executed when the onePageScroll function is called. All of the snippets that assign class names, data attributes and positioning styles and that bind all keyboard inputs reside here.
• Private methods
  The private method section contains all of the methods that will be called internally by the plugin. Methods such as the swipe events, page transformation, responsive fallback and scroll detection reside here.
• Public methods
  This section contains all of the methods that can be called manually by developers. Methods such as moveDown(), moveUp() and moveTo() reside here.
• Utility methods
  This section contains all of the helpers that replicate a jQuery function to speed up development time and slim down the JavaScript’s file size. Helpers such as Object.extend, which replicates the jQuery.extend function, reside here.

I ran into some annoyances, such as when I had to write a method just to add or remove a class name, or when I had to use document.querySelector instead of the simple $ . But all of that contributes to a better, more structured plugin, which benefits everyone in the end.

Rebuilding the Plugin in Zepto

The reason why I decided to support Zepto, despite the fact that it only supports modern browsers (IE 10 and above), is that it gives developers a more efficient and lightweight alternative to jQuery version 2.0 and above, with a more versatile API. Zepto’s file size (around 20 KB) is considerably lower than jQuery 2.0’s (around 80 KB), which makes a big difference in page-loading speed. Because websites are being accessed more on smartphones, Zepto might be a better alternative to jQuery.

Rebuilding a jQuery plugin with Zepto is a much easier task because Zepto is similar to jQuery in its approach to the API, yet faster and more lightweight. Most of the script is identical to the jQuery version except for the animation part. Because Zepto’s $ .fn.animate() supports CSS3 animation and the animationEnd callback right off the bat, I can take out this ugly snippet:

$  (this).css({
    "-webkit-transform": "translate3d(0, " + pos + "%, 0)",
    "-webkit-transition": "-webkit-transform " + settings.animationTime + "ms " + settings.easing,
    "-moz-transform": "translate3d(0, " + pos + "%, 0)",
    "-moz-transition": "-moz-transform " + settings.animationTime + "ms " + settings.easing,
    "-ms-transform": "translate3d(0, " + pos + "%, 0)",
    "-ms-transition": "-ms-transform " + settings.animationTime + "ms " + settings.easing,
    "transform": "translate3d(0, " + pos + "%, 0)",
    "transition": "transform " + settings.animationTime + "ms " + settings.easing
 });
 $  (this).one('webkitTransitionEnd otransitionend oTransitionEnd msTransitionEnd transitionend', function(e) {
    if (typeof settings.afterMove == 'function') settings.afterMove(index, next_el);
 });
 

$  (this).animate({
       translate3d: "0, " + pos + "%, 0"
    }, settings.animationTime, settings.easing, function() {
       if (typeof settings.afterMove == 'function') settings.afterMove(index, next_el);
    });
 }