Calling Event Handlers

Contact Us or call 1-877-932-8228
Calling Event Handlers

Calling Event Handlers

Developers familiar with jQuery - the core jQuery library, that is, as opposed to jQuery Mobile - are used to writing code so that it runs when the page loads. Typical jQuery code might look as below - a simple example of popping up a JavaScript alert when the user clicks on a link (an a tag) of class example:

$(document).ready(function(){
	$('a.example').click(function(){
		alert('hello world');
	});
});

The $(document).ready portion of the code above ensures that the document (the DOM) has fully loaded.

In jQuery Mobile, we use a slightly different "wait until the page has loaded" strategy - listening for the pagecreate event:

$( document ).on( "pagecreate", function() {
	alert('hello mobile world');
});

Since jQuery Mobile uses Ajax to load pages into the DOM as users navigate, the DOM-ready handler ($(document).ready()) only executes for the first page. To execute code whenever a new page is loaded and created in jQuery Mobile, we instead bind to the pagecreate event using on. (jQuery now recommends on in place of bind; as the jQuery docs state: "As of jQuery 1.7, the .on() method is the preferred method for attaching event handlers to a document.")

Binding to the pagecreate event is a relatively recent change for jQuery Mobile. Note that you'll still find lots of example code on the web with other strategies.

Touch

Gesture events like tapping and swiping don't play a big, if any, part on desktops - but are essential aspects of user interaction with mobile and tablet websites and apps:

Touch Events
Event Handler Description
tap

Triggers after a quick, complete touch event.

taphold

Triggers after a held complete touch event (close to one second).

swipe

Triggers when a horizontal drag of 30px or more (and less than 20px vertically) occurs within a 1-second duration but these can be configured:

  • scrollSupressionThreshold (default: 10px) - More than this horizontal displacement, and we will suppress scrolling.
  • durationThreshold (default: 1000ms) - More time than this, and it isn't a swipe.
  • horizontalDistanceThreshold (default: 30px) - Swipe horizontal displacement must be more than this.
  • verticalDistanceThreshold (default: 75px) - Swipe vertical displacement must be less than this.
swipeleft

Triggers when a swipe event occurred moving in the left direction.

swiperight

Triggers when a swipe event occurred moving in the right direction.

See the jQuery Mobile docs for more information on the above events.

When handling events, we'll often make use of the Pagecontainer widget's change method - the preferred way to programmatically change to a new page. Feeding the id of a given page or an appropriate jQuery DOM object as the argument of the method function allows us to, for instance, redirect to a specific page when the user swipes. Let's take a look at an example.

Open Events/Demos/touch.html in a mobile browser, and in a file editor to check the code. This example offers users four pages: the home page and three interior pages - "About Us", "Proprietors", and "History". When not on the home page, users can swipe left or right to reach the next (or previous) page, "wrapping around" to reach the first or last page as appropriate:

Swiping example

Code Sample:

Events/Demos/touch.html

Code Explanation:

As with handling any event - clicking a button, mousing over a div, etc. - with jQuery, we will add some code that says "when this event [a swipe left or right] happens, perform this action". In this case, we'll change to a new page when the user swipes left or right.

We add a <script> block to the head of the document. We use jQuery's on method to handle the swipeleft and swiperight events.

We have added a class (swipeable) to the non-home pages, to filter the set of pages we wish to handle swiping for.

We call the jQuery on method ($(document).on('swipeleft', '.swipeable', function() {): "for any swipe-left event performed in this document on an element of class 'swipeable', do the following".

For the swipeleft event, we query the presence of a next .swipeable DOM element - $(this).next('.swipeable').length - asking, in effect, if this is the last .swipeable element on the page. If so - that is, if the element being swiped is the last element of class swipeable on the page - then we change to the first (#about) page. If not, then we change to the next page of class swipeable: $("body").pagecontainer("change", $(this).next(".swipeable"));

We do the reverse for the swiperight event. Check to see if this is the first page (with class swipeable): if so, change to the last page; if not, change to the previous page.

In this next exercise, you will add some swiping functionality to the Nan & Bob's Online site.

Next