Skip to content

Latest commit

 

History

History
226 lines (171 loc) · 9.07 KB

README.md

File metadata and controls

226 lines (171 loc) · 9.07 KB
Raw

jQuery Scrollz

Modern scrolling for jQuery.

Primarly designed to work on touch devices, the plugin works as well on desktop browsers. At the moment only vertical scroll is supported.

Note that the plugin does not use the widget factory model, as it can be used with plain jQuery (without jQuery UI or jQuery Mobile).

Features

  • Make any DOM element scrollable
  • Inertia support
  • Load more (bottom reached detection)
  • Pull to refresh
  • jQuery Mobile auto-enhancement

Examples

Getting Started

Download the production version or the development version and the CSS.

In your web page:

<link rel="stylesheet" href="jquery.scrollz.css">
<script src="jquery.js"></script>
<script src="jquery.scrollz.min.js"></script>
<script>
jQuery(function($) {
  // #content must have a height set before calling scrollz
  $('#content').scrollz();
});
</script>

Or auto-enhancement with jQuery Mobile:

<html>
    <head>
        <link rel="stylesheet" href="jquery.mobile.css">
        <link rel="stylesheet" href="jquery.scrollz.css">
        <script src="jquery.js"></script>
        <script src="jquery.mobile.js"></script>
        <script src="jquery.scrollz.min.js"></script>
    </head>
    <body>
        <div id="index" data-role="page" data-theme="a">
                <!-- Header -->
                <div data-role="header" data-position="fixed" data-tap-toggle="false">
                        <!-- Header content here. -->
                </div>
                
                <!-- Content : data-scrollz supports 'simple' or 'pull'. Content is automatically resized to  the window height between header and footer. -->
                <div id="content" data-role="content" data-scrollz="pull">
                        <!-- Scrollable content here. -->
                </div>
                
                <!-- Footer -->
                <div data-role="footer" data-position="fixed" data-tap-toggle="false">
                        <!-- Footer content here. -->
                </div>
        </div>
    </body>
</html>

Documentation

Options

Options can be set when calling .scrollz():

<script>
jQuery(function($) {
  $('#content').scrollz({
    styleClass: 'myClass',
    pull: true
  });
});
</script>

Available options are:

  • styleClass (string): style class to apply on the scrolling area (default: none).
  • inertia (boolean): should scrolling area scroll with inertia effect (default: true).
  • pull (boolean): should scrolling area support 'pull' feature. In this case, a pull header is added on top of the content. When scrolling area is 'pull' at its top, the header appears (default: false).
  • pullHeaderHTML (map): HTML code used to render the pull header for the following states : 'initial', 'release' and 'waiting'. A default HTML rendition is provided for each state.
  • emulateTouchEvents (boolean): should the plugin emulate touch events on devices without touch support (default: false).
  • bottomDetectionOffset (int or percentage string): offset for bottomreached event detection. Can be in pixels (int) or percentage of the container (default: '10%').

Events

The plugin can trigger the following events:

  • bottomreached: notifies that the bottom of the scrolling area is reached.
  • pulled: notifies that the scrolling area (with pull header) was pulled.

The bottomreached event is usefull to implement 'infinte scroll' feature.

When pull option is enabled, it is necessary to bind the pulled event in order to hide the pull header one the action triggered on pull is finished:

<script>
jQuery(function($) {

  // Enable scrollz
  $('#content').scrollz({
    pull: true
  });
  
  // Bind pulled event
  $('#content').bind('pulled', function() {
  
    // Process pull action here
    
    // Hide pull header when done
    $('#scrollz2').scrollz('hidePullHeader');
  });
});
</script>

Methods

Scrollz provides the following methods:

  • height(height) : redefines scrolling area height.
  • hidePullHeader(animated, top) : hides the pull header (must be called after processing of the pull action completed), if animated parameter is not provided it is set to true by default. If top parameter is provided, the scroller position is set to top after pull header has been hidden.
<script>
jQuery(function($) {

  // Enable scrollz
  $('#content').scrollz();
  
  // Hide pull header
  $('#content').scrollz('hidePullHeader');

  // Change height
  $('#content').scrollz('height', 600);
});
</script>

Styling

The plugin is provided with a default CSS. This CSS includes pull header and scroll thumb styling.

  • Styling on the different pull header states (based on the default pullHeaderHTML markup).
  • Pull header icons (as base64) : arrow and animated loader, with retina support.
  • Pull header arrow animations (up and down).
  • Scroll thumb simple styling.

###jQuery Mobile support The plugin supports jQuery Mobile auto-enhancement feature with attribute 'data-scrollz' for easier / faster integration. This attribute supports the follwoing values :

  • simple: builds a simple scrolling area on the target element with default options.
  • pull: builds a scrolling area on the target element with a pull header, other options are default options.

When the feature is used, the scrolling area height is set to fit the window size (without eventual header or footer). This height is updated every time the widow is resized. So the attribute cannot be used on 2 elements stacked vertically. However the attribute can be used on elements stacked horizontally as the width is never resized.

Release History

Version 1.0.5 (work in progress):

  • Added 'top' parameter to hidePullHeader method to allow setting a custom scroll position after pull header has been hidden (thanks again AdamDash-2).
  • Added 'bottomDetectionOffset' option. Version 1.0.4 (28 February 2013):
  • 'touchend' event is not stopped anymore if the scrollable area is not scrolling (thank you AdamDash-2)

Version 1.0.3 (24 February 2013):

  • Added jQuery 1.9 and jQuery Mobile 1.3 support

Version 1.0.2 (06 November 2012):

  • Multiple headers and footers support with JQuery Mobile.
  • Fixed scroll to top when item is clicked inside scrollable area.
  • Added 'animated' parameter on 'hidePullHeader' method.

Version 1.0.1 (19 August 2012):

  • Better inertia support.
  • Fixed default container height when smaller than pull header.
  • Fixed resize issue on orientation change.
  • jQuery Mobile auto-enhancement with 'data-scrollz' attribute.

Version 1.0.0 (16 August 2012):

  • First release.

License

Copyright (c) 2012 Gilles Grousset
Licensed under the MIT, GPL licenses.

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using grunt.

Important notes

Please don't edit files in the dist subdirectory as they are generated via grunt. You'll find source code in the src subdirectory!

While grunt can run the included unit tests via PhantomJS, this shouldn't be considered a substitute for the real thing. Please be sure to test the test/*.html unit test file(s) in actual browsers.

Installing grunt

This assumes you have node.js and npm installed already.

  1. Test that grunt is installed globally by running grunt --version at the command-line.
  2. If grunt isn't installed globally, run npm install -g grunt to install the latest version. You may need to run sudo npm install -g grunt.
  3. From the root directory of this project, run npm install to install the project's dependencies.

Installing PhantomJS

In order for the qunit task to work properly, PhantomJS must be installed and in the system PATH (if you can run "phantomjs" at the command line, this task should work).

Unfortunately, PhantomJS cannot be installed automatically via npm or grunt, so you need to install it yourself. There are a number of ways to install PhantomJS.

Note that the phantomjs executable needs to be in the system PATH for grunt to see it.