• 设为首页
  • 点击收藏
  • 手机版
    手机扫一扫访问
    迪恩网络手机版
  • 关注官方公众号
    微信扫一扫关注
    公众号

watusi/jquery-mobile-iscrollview: JQuery Mobile widget plug-in for easy use of t ...

原作者: [db:作者] 来自: 网络 收藏 邀请

开源软件名称(OpenSource Name):

watusi/jquery-mobile-iscrollview

开源软件地址(OpenSource Url):

https://github.com/watusi/jquery-mobile-iscrollview

开源编程语言(OpenSource Language):

JavaScript 70.6%

开源软件介绍(OpenSource Introduction):

watusi/jquery-mobile-iscrollview, Version 1.3.6

JQuery Mobile widget plug-in for easy use of the iScroll scroller in 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 widget. It follows the widget-factory-mobile Widget Factory Pattern.


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

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 <head> and adding a single data-iscroll attribute to your content <div>.

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 <div> 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 <div> 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" <div> 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

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <meta name="viewport" content="width=device-width,initial-scale=1,maximum-scale=1,user-scalable=no"/>
    <meta name="apple-mobile-web-app-capable" content="yes">
    <meta name="apple-mobile-web-app-status-bar-style" content="black">
    <title>Demo</title>

    <link rel="stylesheet" href="jquery.mobile-1.3.1.min.css"/>
    <link rel="stylesheet" href="jquery.mobile.iscrollview.css"/>
    <link rel="stylesheet" href="jquery.mobile.iscrollview-pull.css"/>
    <link rel="stylesheet" href="additional-site-specific-styles.css"/>

    <script src="jquery-1.9.1.min.js"></script>
    <script src="jquery.mobile-1.3.1.min.js"></script>
    <script src="iscroll.js"></script>
    <script src="jquery.mobile.iscrollview.js"></script>
    <script src="additional-site-specific-scripts.js"></script>
  </head>

  <body>
    <div data-role="page" class="index-page">

      <div data-role="header" data-position="fixed" data-tap-toggle="false" data-transition="none" data-id="header">
        <h1>INDEX PAGE</h1>
      </div>

      <div data-role="content" class="example-wrapper" data-iscroll>
        <p>some content that will be scrolled</p>
        <p>Some more content that will be scrolled</p>
        <ul data-role="listview">
          <li>Item 1</li>
          <li>Item 2</li>
        </ul>
        <p>Even more content. It will scroll whatever is in the data-iscroll div.</p>
      </div>

      <div data-role="footer" data-position="fixed" data-tap-toggle="false" data-transition="none" data-id="footer">
        <h1>My Footer</h1>
      </div>

    </div>
  </body>
</html>

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 <div>s around that content.

The outermost <div> 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 <div> is also added around the scrolled content, sandwiched between the (possibly absent) pull-down and/or pull-up blocks. This <div> 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 <div> that has class iscroll-content.

What you wrote:

    <div data-role="content" data-iscroll>
      <p>This is some content that I want to scroll</p>
      <p>This is some more content</p>
    </div>

What the plugin produces:

    <div data-role="content" data-iscroll class="iscroll-wrapper">
      <div class="iscroll-scroller">
        <!-- If you included a pull-down under the wrapper, it will wind-up here -->
        <div class="iscroll-content">
          <!-- If you included no content above under the content div, then this div is empty -->
          <p>This is some content that I want to scroll</p>
          <p>This is some more content</p>
        </div>
        <!-- If you included a pull-up under the wrapper, it will wind-up here -->
      </div>
    </div>

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 <div> 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 <head>. 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:

    <div data-role="content" data-iscroll>
      <div class="iscroll-pulldown">
        <span class="iscroll-pull-icon"></span>
        <span class="iscroll-pull-label"></span>
      </div>
      <ul data-role="listview">
        <li>Item 1</li>
        <li>Item 2</li>
      </ul>
      <div class="iscroll-pullup">
        <span class="iscroll-pull-icon"></span>
        <span class="iscroll-pull-label"></span>
      </div>
    </div>

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 corresponding option value.

To change the Reset text, simply insert it in the pull block's label <span>.

To change the Pulled text, use a data-iscroll-pulled-text attribute.

To change the Loading test, use a data-iscroll-loading-text attribute.

Example:

    <span data-iscroll-pulled-text="Now let er go, and we'll get some refresh action!"
          data-iscroll-loading-text="Ye-haw! Waiting for the data to come through the pipes!"
          class="iscroll-pull-label">Pull this here thing down to refresh!</span>

Fancier Pull States

If you want to do something more elaborate when a pull block enters each state, you can either provide a callback option or (recommended) bind or delegate to a jQuery event callback function. The associated events are:

  • iscroll_onpulldownreset
  • iscroll_onpulldownpulled
  • iscroll_onpulldownloading
  • iscroll_onpullupreset
  • iscroll_onpulluppulled
  • iscroll_onpulluploading

Event and Callback Option Functions

In order to implement the pull-down and/or pull-up action, you need to supply a function. You can either supply this function as an option value or (recommended) bind or delegate to a jQuery event callback function.

The example code below is from the demo:

    $(document).delegate("div.pull-demo-page", "pageinit", function(event) {
        $(".iscroll-wrapper", this).bind( {
        "iscroll_onpulldown" : onPullDown,
        "iscroll_onpullup"   : onPullUp
        });
      });

Callbacks

Your callback function receives two parameters:

e

This is the event object that originally gave rise to the callback. This is probably not very useful to you.

d

This is map containing one member, iscrollview. This is a reference to the iscrollview object that made the callback.

Your callback should take whatever action you want when the user activates the pull-up/pull-down. This might typically involve retrieving some data from a server and inserting it into the scroller content. See the demo for an example.


Calling functions

The standard way of calling widget functions is by passing a sub-function name as a string parameter to the widget function. Any parameters to the function should follow.

Note: This method works for all versions of jQuery Mobile from 1.0 to 1.4.x. See below, though, for differences when using an alternative way of calling fucntions.

For example, to call the refresh function:

    $(".example-wrapper").iscrollview("refresh");

The widget factory allows you to access widget functions directly, by accessing a data variable stored in the widget's element. For jQuery Mobile versions < 1.3:

    $(".example-wrapper").jqmData("iscrollview").refresh();

The Widget Factory changed in jQuery Mobile version 1.3. Starting with this version, you can access this variable like this:

    $(".example-wrapper").data("mobileIscrollview").refresh();

While this is a bit awkward, it is also more conventional. It is handy in case you need to make a series of calls to different widget functions. You can first get the instance into a variable.

    // JQM < 1.3
    var myView = $(".example-wrapper").jqmData("iscrollview");
    myView.refresh();
    // JQM >= 1.3
    var myView = $(".example-wrapper").data("mobileIscrollview");
    myView.refresh();

This means, as well, you can easily call any underlying iScroll function through the exposed iscroll member variable. For example,

    // JQM < 1.3
    $(".example-wrapper").jqmData("iscrollview").iscroll.scrollTo(0,10,200,true);
    // JQM >= 1.3
    $(".example-wrapper").data("mobileIscrollview").iscroll.scrollTo(0,10,200,true);

So, if you replace iscroll.js with a newer version that has new functions, or if you need to call iScroll private functions, or access iScroll member variables, you can call them without any need to modify this widget.

This widget wraps all current iScroll public functions, so the above example can also be called like this:

    $(".example-wrapper").iscrollview("scrollTo", 0, 10, 200, true);

The exceptions are the destroy, refresh, enable, and disable functions.

destroy is a standard widget factory function. In this widget, it calls the iScroll destroy function and then calls the base widget destroy. If you need direct access to iScroll's destroy function, you can access it directly using the iscroll member variable.

The widget's refresh function insures that the underlying iScroll refresh function is called with the proper timing. If you need to call the iScroll refresh function directly, do so using the iscroll member variable.

enable and disable are standard widget functions. Each of these calls iScroll's corresponding function and then calls the underlying widget function.


Functions

###Standard Widget Functions

These are functions that are typically implemented for ALL widgets:


鲜花

握手

雷人

路过

鸡蛋
该文章已有0人参与评论

请发表评论

全部评论

专题导读
热门推荐
阅读排行榜

扫描微信二维码

查看手机版网站

随时了解更新最新资讯

139-2527-9053

在线客服(服务时间 9:00~18:00)

在线QQ客服
地址:深圳市南山区西丽大学城创智工业园
电邮:jeky_zhao#qq.com
移动电话:139-2527-9053

Powered by 互联科技 X3.4© 2001-2213 极客世界.|Sitemap