Barry's jQuery Mobile Demos: Events

jQuery Mobile events

jQuery Mobile adds some new events to the existing jQuery events. We define event handlers for jQuery Mobile events using the on() method that is used in jQuery. However, we have an interesting problem as to where to define the event handlers. In jQuery we always defined our event handlers after the HTML page was loaded. We did this by defining them in a "documentready" event handler like this:

$(document).ready(function() {
	// jQuery event handlers defined here (NOT jQuery mobile!)
  });

However, in jQuery Mobile we sometimes can define multiple pages in the one HTML file so we need a slightly different approach. We can define our event handlers at the point a page is ready for display. We do this with the following format:

$(document).on("pagecreate","#pageID", function(){
	// jQuery Mobile event handlers defined here.
  });

The "pageID" is the id attribute of the page where the event is generated. Note that, although jQuery Mobile introduces some new events, the previously discussed jQuery events may still be defined in this structure. Below, we will now look at some of the events unique to jQuery Mobile.

Touch events

The first event is the "tap" event which is fired when the user taps on a screen area. If you are testing on a desktop computer a mouse click will be equivalent. So for example, we can implement code to process a button with the attribute id="button1" with the following code outline.

  $("#button1").on("tap",function(){
    // code to process button tap
  });

There is also a "taphold" event that fires when the user touches the element for one second. On a desktop computer this is equivalent to pressing the mouse button down on an element for one second without releasing it. So for example, we can process a "taphold" event as follows.

  $("#button1").on("tap",function(){
    // code to process button tap
  });

You will find the taphold event may become tricky to use in some desirable places. This event implies a tap event will be fired since a taphold is really just a long tap. So if you want two different and exclusive actions for tap and taphold events on the same widget you will be in for some tricky coding that may be device specific. You will find arguments about this issue on-line if you search for it.

As an example, we can define a tap and taphold event handler to produce alert messages as follows:

$(document).on("pagecreate","#jQM-Events", function(){
  $("#button1").on("tap",function(){
       alert("tap event");
    });
  $("#button1").on("taphold",function(){
       alert("taphold event");
    });
  });

Press this button to see the result: Button1 Try press and hold for more than one second.

Swipe event

A common mobile device interaction is a "swipe" event. On a desktop PC this is equivalent to holding the mouse down while moving the mouse across an element. To be precise, a swipe event occurs when a swip of 30 pixels or more is detected. There are three swipe events:

This paragraph is has attribute id="swipepara". It has a swipeleft and swiperight event handler defined as below. Try swiping the paragrph text left and write.

    $("#swipepara").on("swipeleft", function () {
       alert("swiped left");
    });
    $("#swipepara").on("swiperight", function () {
       alert("swiped right");
    });

Scroll and orientation events

There are two scroll events that jQuery Mobile fires:

  1. scrollstart is fired when the user starts a scrolling action.
  2. scrollstop is fired when the user stops a scrolling action.

An example of scroll processing is the following code which, when the button is tapped, cause an alert when each scrolling starts and stops.

    $("#startscrolltest").on("tap", function () {
	   $(document).on("scrollstart", function () {
	      alert("scroll started");
	   });
	   $(document).on("scrollstop", function () {
	      alert("scroll stopped");
	   });
	});

These buttons start and stop the above event handlers Start scroll test Stop scroll test

There is also an event that occurs when the orientation of the mobile device changes, the "orientationchanged" event is fired when the mobile device is rotated. This event is fired by the window object so we should attach the event handler to this object. The event function in this case can have a parameter which can be used to find out the latest orientation. The parameter passed to the event handler has an attribute called orientation that can be on of the strings "portrait" or "landscape". An outline of a handler to use this information is:

$(window).on("orientationchange",function(evt){
   if (evt.orientation == "portrait") {
      // code for narrow display
   } else {
      // code for wide display
   }
});

There is an alternate but equivalent way to process orientation changes. The window object maintains its own attribute with the orientation value as an integer. Once we know the orientation has change we can easily access it. An equivalent to the above code is as follows.

$(window).on("orientationchange",function(){
   if (window.orientation == 0) {  // 0 is portrait mode
      // code for narrow display
   } else {
      // code for wide display
   }
});

Possible values for window.orientation are 0 (portrait), -90 and 90 (landscape). An event handler for displaying the window.orientation object is attached to this page. If you are viewing this on a mobile device then you can try it by tilting the screen. You will not be able to test orientation change on your desktop PC!

Page events

jQuery Mobile can switch between pages defined in the one HTML file. This means there are three times when we may want to know the screen is changing for the user:

  1. When we switch to a page, including the first one.
  2. When a page is loaded from the Internet.
  3. When a page transition is occurring.

There are several events for each of these situations. For simple page switching we have two events:

We have already used the pagecreate event above to establish event handlers for elements with a page.

When we load a page from the internet we have three events:

And when there is a transition to a new page we have four events:

This button will go to a test page with an alert for all four of these events. Test page

At this stage these events may appear to be of limited use. However, in a large application, the ability to know when some lengthy activity is taking place will be useful so we can do other things in the background. While loading and page switching animation are underway there is time to do various housekeeping for our applicationa. Unfortunately, this will be application dependant and in general we will only need to consider this after the application is shown to be working.

Home

Test page

This is a test page to observe event handlers with id="testpage". The following event handlers are enabled. Note that you will not see the two of these alerts while this page is visible.

$(document).on("pagebeforeshow", "#testpage", function() {
    alert("pagebeforeshow event");
});

$(document).on("pageshow", "#testpage",function() {
    alert("pageshow event");
});

$(document).on("pagebeforehide", "#testpage", function() {
    alert("pagebeforehide event");
});

$(document).on("pagehide", "#testpage", function() {
    alert("pagehide event");
});

Go back

Test page