Geplaatst op

PhoneGap pull to refresh implementation

We all know the very nice pull to refresh functionality that was introduced in the Twitter app for iOS. Though patented by Twitter, it has been implemented in many apps since. I was working on a PhoneGap app with a page containing a list of news items and was wondering how difficult it would be to implement the pull to refresh functionality on that page. This blog describes how to make your PhoneGap pull to refresh implementation.

PhoneGap pull to refresh

Google led me to the iScrollView JQuery Mobile plugin to use the iScroll scroller. Using this plugin it was fairly easy to implement pull to refresh. A few steps had to be taken. First, include the plugin stylesheets and javascript files in your html file.

<link rel="stylesheet" href="css/jquery.mobile.iscrollview.css" type="text/css"/>
<link rel="stylesheet" href="css/jquery.mobile.iscrollview-pull.css" type="text/css"/>
<script src="js/lib/iscroll.js"></script>
<script src="js/lib/jquery.mobile.iscrollview.js"></script>

Next, add the attribute data-iscroll to the container you want to add the functionality to. In my case, this was the content container of the page. See the first line in the code snippet below.

<div id="scroller" data-role="content" data-iscroll="">
 <div class="iscroll-pulldown">
   <span class="iscroll-pull-icon"></span>
   <span class="iscroll-pull-label"
         data-iscroll-loading-text="News is being refreshed"
         data-iscroll-pulled-text="Release to refresh the news">
     Refresh the news
   </span>
 </div>
 <div id="newsList"></div>
</div>

The <div> with class iscroll-pulldown contains the definition of the pulldown content that will be displayed when the user pulls down the container. Different data tags are available for the different states the pull down dialog can be in. data-iscroll-loading-text for the text to be displayed when the update action is executed and data-iscroll-pulled-text for the text to be displayed when the user has pulled down the container.

So, how do we implement the code to actually update the news items? We need some Javascript for that ofcourse! On the pageinit event of the page we need to bind javascript functions to the different events that have been defined by the plugin. See the code below how the javascript function onPullDown is defined for the iscroll-onpulldown event.

$('#newsPage').live("pageinit", function(event) {
  $(".iscroll-wrapper").bind( {
    iscroll_onpulldown : onPullDown
  });
});
function onPullDown(event, data) {
  //do your stuff here...
}

This is all that is needed to implement the pull to refresh functionality in your JQuery Mobile PhoneGap application. Enjoy!

Geplaatst op

Implementing JQuery Mobile buttons without unexpected side effects

Recently we started the implementation of a new mobile application. We are using the Phonegap / Apache Cordova framework to have a single code base for multiple target platforms. The code base exists of HTML, CSS and Javascript. We use JQuery Mobile to implement the HTML pages.

JQuery Mobile offers different templates, the single page template and the multi page template. We are using the multi page template, which of course means that there are multiple pages in our application. These pages are defined in a single HTML file using the following JQuery Mobile code:

<div id="pageOne" data-role="page">
  Page code here
</div>
<div id="pageTwo" data-role="page">
  Page code here
</div>

Adding behaviour to your buttons

After creating the pages, we added some buttons to these pages. To add behavior to these buttons, we used the JQuery “pagebeforeshow” event of the page.

$('#pageOne').live('pagebeforeshow', function(e, data) {
  $('#myButton').bind('click', function() {
    $.mobile.changePage("#pageTwo", {transition: 'slideup'});
  });
});

After creating several pages and buttons we were ready to run our application to see if the navigation between the pages worked correctly. At first, we were very happy because all buttons seemed to work correctly. However, clicking around for a bit resulted in some very strange unexpected behavior. It turned out that each time the page was shown, the event handler was added to the page. Multiple event handlers to buttons result in ‘clickthroughs’, which basically means that page navigation is messed up.

How to fix this?

Finding the root cause proved to be more difficult than fixing the issue. Just unbind the click behavior of buttons when hiding the page, see the code snippet below. This will prevent multiple event handlers being added to your buttons.

$('#personPage').live('pagebeforehide', function(e, data) {
  $('#previousPerson').unbind('click');
  $('#nextPerson').unbind('click');
});