watusi/jquery-mobile-iscrollview, Version 1.3.6
===============================================
JQuery Mobile widget plug-in for easy use of the [iScroll](https://github.com/cubiq/iscroll)
scroller in [JQuery Mobile](https://github.com/jquery/jquery-mobile)
projects.
iScroll is a javascript that can scroll content in a window within a web browser with very
similar behaviour to native scrolling on mobile devices such as iPhone and Android. This means you
can scroll a *window* within the browser using native-like scrollbars and physics.
jquery.mobile.iscrollview adapts the iScroll javascript to the jQuery Mobile environment.
It is an implementation of a JQuery [Widget Factory](https://github.com/scottgonzalez/jquery-ui-1.8-widget-factory)
widget. It follows the *widget-factory-mobile*
[Widget Factory Pattern](https://github.com/addyosmani/jquery-plugin-patterns).
---
Release Notes
-------------
Please see releaseNotes.txt for information on changes in this and prior releases.
iScroll Version 4.2.5
---------------------
This widget is not yet compatible with iScroll version 4.2.1 through 4.2.5. Please stick with iScroll 4.2 for
now. Some investigation and testing is needed due to changes in iScroll event code.
Also, iScroll 4.2.1 introduced and change that may not be desirable. Scrolling continues
when your finger leaves the wrapper. While this is a nice feature for small scrollers,
this is not always desirable. It is very odd on desktop browsers, as scroll continues
when you drag with the mouse, even outside of the browser! It should be optional. (It will be in iScroll5).
Roadmap
-------
1.4 - Fully implement usejQueryEvents
? - Option to un-enhance widget temporarily (and optionally hide headers/footers) during
virtual-keyboard input on select devices (iOS first), to eliminate all form input problems
when using a virtual keyboard.
? iOS keyboard handing for inputs. Guess keyboard height based on device/orientation/fullscreen.
Resize wrapper to fit page in space above keyboard, center focused element.
? - Better support for collapsible content (scroll on expand if expanded content below window)
Plug for jquery.mobile.simultaneous-transitions
-----------------------------------------------
This plugin works best when used with
[jquery.mobile.simultaneous-transitions](https://github.com/watusi/jquery.mobile.simultaneous-transitions)
It puts back the old, simultaneous, non-scrolling transitions that everybody knew and loved
from jQuery Mobile 1.0. It's an ideal companion for jquery.mobile.iscrollview! Stop fighting the
goofy transitions in jQuery Mobile 1.1. If you're using iScroll, you probably don't need them.
What This is For
----------------
This widget is intended for use in any jQuery Mobile project, but it was designed to be especially
useful for some specific uses.
First and foremost are native mobile applications that use HTML/CSS/Javascript in a
webview for their user interface. It is especially desirable that such applications reproduce a
"native" look and feel. A native look and feel is impossible to achieve without an embeddable
scroller with native-like physics and scrollbar action.
While iScroll4 is useful to help achieve this goal, it is difficult to use along with
jQuery Mobile. It is not an easy task to integrate iScroll4 with jQuery Mobile - at least not
correctly and efficiently.
My intention is that this widget will handle 80% of use cases with very minimal effort.
The most common need for iScroll in jQuery Mobile projects is to have a fixed header and footer
with a single vertically-scrollable area in-between.
This can be accomplished by simply including the required files in the `` and adding a
single `data-iscroll` attribute to your content `
`.
If you need to do something different than this, this widget will probably work for you, but
you will probably have to set some options and dig into the documentation a bit.
Because the primary target for this widget is native mobile applications, it has a large number of
configurable options, which may be usable only in certain target environments. I want you to be able
to tailor the widget to your specific needs when you are using it in specific, known environments.
Secondarily, it is intended to support websites that will be viewed on mobile browsers, and
"full-screen" websites and "web apps" for mobile devices (i.e. "Add to Home Screen" in
Mobile Safari).
Finally, it supports desktop browsers, and is regularly tested using current versions of
FireFox, Safari, Chrome, and Opera. It generally works well in these browsers, and fortunately
hasn't needed a lot of work to acheive compatability.
This widget is *not* well-tested on Android devices, and I very much appreciate assistance in
ferreting-out Android issues. It is tested regularly in all three modes (Mobile Safari, full-screen,
and UIWebView) on iPad 1(5.1), iPad 3(5.1), iPhone 4 (4.3.5) and iPhone 4S(5.1).
Usage
-----
The most basic usage of this widget is simple: just add a `data-iscroll`
attribute to a container. All content inside this container will be scrolled.
Note that `iscroll.js` itself scrolls only the first child of it's wrapper. However, by
default, this plugin automatically creates a protective `
` around all
children of the wrapper, and so unlike iscroll.js it will scroll *all* of the children of the
wrapper element - not just the first.
As well, you may have *no* content in the wrapper initially. You might do this, for example, if
you will be inserting dynamic content later. In this case, the plugin will create an empty
`
` for you.
If, for some reason, you do not want the widget to create
this protective container, set the `createScroller` option to `false`.
The widget does not use the typical JQuery Mobile `data-role="something"` attribute,
because a common use case would be to use a `data-role="content"` `
` as the
container, and, of course, you can't have two `data-role` attributes on the
same element.
The widget will (normally) re-size the container to take up all available height
within the viewport after fixed headers/footers are taken into account. This behaviour can be
disabled using the `resizeWrapper` option, which should be se `true` for no more than one widget
on a given page.
The widget has been designed to support multiple scrollers on a page - for example, you
might want a second, gallery-like horizontal scroller. So, all
data related to a scroller is stored in the scroller's container, not the page.
Feel free to experiment with multiple scrollers - I just haven't had the
need so haven't put the effort into testing and supporting that scenario.
Support for `data-position="fixed"` headers/footers is limited, but improved over previous
versions. Since this widget resizes the scroller to fit the page, there is no need for fixed
positioning of header/footer. Resizing is fast enough that the footer stays "glued" to the
bottom of the page fairly well.
Additional fixed-height elements (which are not headers or footers)
outside of the scrolling region should be given the `data-iscroll-fixed` attribute, if they
would add to the height of the page. (Do not add the `data-iscroll-fixed` attribute
to sidebars.)
---
Example
-------
```html
Demo
INDEX PAGE
some content that will be scrolled
Some more content that will be scrolled
Item 1
Item 2
Even more content. It will scroll whatever is in the data-iscroll div.
My Footer
```
---
Fixed and persistent Toolbars (Headers/Footers)
-----------------------------------------------
This plugin now works fairly well with both fixed and persistent toolbars, as long as you use
jQuery Mobile 1.1.1 or later.
Make sure you use `data-tap-toggle="false"` if you don't want goofy disppearing tolbars when the
user taps on the toolbar!
Note, however: *do not use `data-tap-toggle="false"` for Navbars!* This is an apparent bug
in jQuery Mobile. `data-tap-toggle` is not possible for NavBars in any case, because the buttons
cover the entire toolbar surface. There isn't anywhere for the user to tap-to-toggle.
If you add `data-tap-toggle="false"` to a Navbar, the Navbar will fail to
work in certain circumstances when using certain browsers (Mobile Safari/iOS 5.1.1 on iPhone,
but not on iPad or iOS 4.3.5). After a window resize (for example, orientation change), the Navbar
will become non-responsive if `data-tap-toggle` is present. In this case, just leave this option out
completely.
You can also use persistent toolbars. The JQM documentation has in the past been ambiguous
as to whether these can be used with toolbars other than Navbars. They can: at least with
jQuery Mobile 1.1.1. The demo now uses fixed, persistent toolbars for both header and footer.
To use a persistent toolbar, assign the same `data-id` value to the toolbar in each page in
which it appears. jQuery Mobile will move the toolbar out of the page temporarily during
transitions, so that it will appear fixed. A "none" transition is used to transition the toolbars,
so that elements that are positioned in the same place within the toolbar will appear to not
change during the transition.
Because the page height is restricted to the viewport height (at least by default) when using
this plugin, jQuery Mobile (1.1.1) will not fade the toolbar during transitions.
Bear in mind, though, that the combination of fixed toolbars and a page size that equals the
viewport height (the default when using this plugin) may cause unwanted results in some
enviroments. In particular, in Mobile Safari, this will cause the browser's navigation bar
to show during page transitions. So, fixed toolbars are most appropriate only in a native
environment (such as when using a WebView with PhoneGap.)
I am seeking feedback on how well fixed and persistent toolbars work (or don't) in different
browsers and environments. So, I have enabled fixed/persistent toolbars in the demo. If this causes
issues in your environment, please try with `data-position="inline"`.
In the demo, you can use see the difference
between how jQuery Mobile 1.0.1 and 1.1.1 handle this. You can see that the
header is fixed with 1.1.1 but slides with the page with 1.0.1. JQM *tries* to keep the footer
fixed in 1.0.1 but is not completely successful. You will see that sometimes it stays fixed
and sometimes it slides with the page transition. Ths seems related to queued transitions.
Additionally, you may notice that the footer is shown briefly in the wrong position during
transitions. If this is a problem in your environment, you can use an inline footer, and the
plugin will insure it always appears in the right place. However, you cannot implement a persistent
toolbar in JQM 1.1 with an inline footer.
Dynamic Content
---------------
If you will be adding dynamic content that you want to have scrolled, you first need to understand
the HTML structure that the plugin creates for you.
If you supply initial content, the plugin will create two `
`s around that content.
The outermost `
` is called the scroller, and contains everything that will be scrolled
by iScroll. It is given a class of `iscroll-scroller`.
If you supplied pull-down and/or pull-up blocks, they are moved to inside the scroller, after
the scroller is created.
An additional `
` is also added around the scrolled content, sandwiched between the
(possibly absent) pull-down and/or pull-up blocks. This `
` is given a class of
`iscroll-content`. This contains everthing that the scroller scrolls, *other* than any
pull-down and/or pull-up blocks.
When you add dynamic content, make sure to add it inside the `
` that has class `iscroll-content`.
What you wrote:
```html
This is some content that I want to scroll
This is some more content
```
What the plugin produces:
```html
This is some content that I want to scroll
This is some more content
```
### Refreshing
Any time you alter the content of a scroller, in such a way that the dimensions of the scrolled
content might be changed, you need to refresh the scroller widget using the `refresh()` function.
The `refresh()` function has optional pre and post-refresh function arguments that can be used
to perform some action before and/or after the refresh. For example, you might also refresh some other
widget, such as a listview, prior to refreshing the scroller, or you might want to scroll to
a particular position after the refresh has been performed. The callbacks are necessary because
refresh is not performed immediately, but after a timeout that insures that the DOM has been fully
updated with your new content.
Please see the section on the `refresh()` function for full details.
Alternately, you can trigger an `updatelayout` event on the element whose dimensions you changed.
The widget listens for any `updatelayout` events triggered on elements inside a scroller and
refreshes automatically. `updatelayout` is triggered by jQuery Mobile on certain jQuery Mobile
widgets, such as, for example, collapsibles. So, it is not necessary to call `refresh()` when
collapsibles are expanded or collapsed.
---
Padding Issues
--------------
Previous versions of this widget had some issues involving the way jQuery Mobile standard CSS
applies padding and margin to content divs and listviews. The widget now handles this for you in
the most common use cases.
By default, the widget removes any padding from your wrapper. It then adds a `
` inside the
scroller, around your content (exclusive of any pull-down/pull-up block) and adds the padding
that was removed from the wrapper. This provides correct padding for both normal and inset
listviews.
The padding needs to be moved to *inside* the scroller (and to not include pull-down/pull-up)
so that you will not see padding around the scroller itself.
There are two options that allow you to override this default behavior: `removeWrapperPadding`
and `addScrollerPadding`.
---
Pull-to-Refresh
---------------
This widget supports "pull-to-refresh" functionality. You can have a block of HTML that is
positioned above the top or below the bottom of the scroller that the user can pull down or pull up.
These blocks can be revealed by scrolling, but the scroller will "snap back" after the user
stops scrolling to again hide the block. If the user pulls past this block by a certain amount,
(1/2 the height of the pull block) and then releases, some action that you specify will be
performed. That action can be anything, but typically will be to perform some AJAX action to
retrieve data from a server and refresh or add some content within the scroller.
In order to implement pull-to-refresh, you need to add a small amount of HTML markup to your page
and either supply a function as an option value or else (recommended) bind or delegate to
a jQuery event callback function.
You also need to include the file `jquery.mobile.iscrollview-pull-css` in your
``. Finally, this CSS file references an image file that contains an arrow icon and a
spinner icon. You can replace this with your own image file. If you rename or move this file, make
sure to edit the CSS file or override the rule in your own CSS file.
### Pull Block
To implement pull-up and/or pull-down, structure your HTML similar to the following:
```html
Item 1
Item 2
```
This is all you have to do to implement the pull-up and/or pull-down UI.
The widget doesn't create the pull blocks for you, in order to provide you with the flexibility
to format them as you please. The pull blocks can contain other elements, and the spans for
the icon and/or label can be omitted.
All of the class names used for pull-down and pull-up are configurable in options. The example
above uses the default class names.
### Pull States
A pull block can be in one of three states:
* `Reset` This is the initial state of the pull block
* `Pulled` This is when the bock has been pulled, but not yet released
* `Loading` This is when the block has been released, and some action is being performed
If the user scrolls back (without lifing) while in the `Pulled` state, then the block
returns to the `Reset` state.
If the user pulls past the edge of the pull block (by 1/2 the height of the pull block), then
the block will enter the Loading state.
After the action has been performed, and the scroller is refreshed, then the block returns
to the `Reset` state.
### Pull Label Text
The widget has default text values that are inserted into the pull label element when the
block enters each state. Each of these text values is a configurable widget option. The
applicable options, and their default values are:
* pullDownResetText `"Pull down to refresh..."`
* pullDownPulledText `"Release to refresh..."`
* pullDownLoadingText `"Loading..."`
* pullUpResetText `"Pull up to refresh..."`
* pullUpPulledText `"Release to refresh..."`
* pullUpLoadingText `"Loading..."`
To change these options programatically, see the options documentation.
Alternately, you can change the default values in your HTML. When you change the defaults
in HTML, it changes the correspondi ... ...