Repository files navigation

This is a series of plugins that create additional events that can be used in combination with jQuery when developing for mobile devices. The events are also compatible with desktop browsers to ensure ultimate compatibility for your projects. In time, we will update the Repository to include some very basic demonstrations to get you started with using the events, but for now, we've put together a list of the events that are provided, and what they do.

As explained, the events are each triggered by native touch events, or alternatively by click events. The plugin automatically detects whether the user's device is touch compatible, and will use the correct native events whenever required. It is hoped that these events will help to aid single-environment development with jQuery for mobile web app development.

1. Version History
2. Installation
3. Usage
4. Events
5. Callback Data
6. Defining Thresholds
7. Utility Functions
8. Demo
9. Requirements
10. License

After almost 2 years in public beta, I am pleased to announce that the library is now officially launched asversion 1.0.0. I'll be updating the version history over time with digests of fixes, features and improvements:

• Version 2.0.3 (2020-04-23)
  • Fix for bug#165
• Version 2.0.2 (2020-04-21)
  • Fix for binding events todocument andwindow.
• Update NPM repo so that latest releases are detected.
• Version 2.0.1 (2019-12-02)
  • Fix for bug#156
• Version 2.0.0 (2018-05-20)
  • Added two-finger tap event (tap2).
  • Added two-finger taphold event (taphold2).
  • Added setter functions to easily set thresholds globally.
  • Fixed a bug where the offset position of elements was sometimes incorrect.
  • Other minor bug fixes.
• Version 1.0.9 (2017-06-07)
  • Fixes a bug where binding to multiple elements with the same selector caused issues withdoubletap.
• Version 1.0.8 (2017-02-01)
  • Fixes a bug where certain instances of Chrome on touch devices did not correctly fire events.
  • Added license info to minified script.
• Version 1.0.7 (2017-02-01)
  • Added threshold support fortaphold
• Version 1.0.6 (2016-11-16)
  • Added slop factor forsingletap
  • Fixed a bug whereoffset() was sometimes called onnull (instead ofwindow).
• Version 1.0.5 (2015-11-13)
  • Fixed a major bug where the reportedoffset position of events was incorrect when inside of a parent element.
• Version 1.0.4 (2015-11-12)
  • Regressed fromMSPointerEvent for compatibility with IE11 and Edge
  • Removed multi-name event fortap.
• Version 1.0.3 (2015-11-10)
  • Numerous minor bug fixes
  • Fixes a bug where the offset position returned by events relative to thecurrent target, not the bound target.
• Version 1.0.2 (2015-08-26)
  • Numerous bug fixes
  • Added support forMSPointerEvent
• Version 1.0.1 (2015-08-21)
  • Added Bower package for easy install
  • Fixed a bug where Internet Explorer under Windows Mobile did not trigger certain events.
• Version 1.0.0 (2015-07-18)
  • The library officially entered 1.0.0 after minor bug fixes and final adjustments.

jQuery Touch Events, as the name suggests, require only the jQuery library (version 1.7+) to run. You should download the latest release from thesrc folder, and include the Javascript file within your project,after jQuery has been included. It is recommended to also wrap your code inside theDOMReady callback function of jQuery ($(function() { }), for example).

Manual installation:

Once you have downloaded the JS files from the master branch, you should include them using the following code:

<scripttype="text/javascript"src="path/to/jquery.mobile-events.min.js"></script>

The awesome guys over atcdnjs have kindly added the library to their CDN so you can include it as follows directly into your application:

<scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/jquery-touch-events/1.0.5/jquery.mobile-events.js"></script>

Alternatively, you can also install jQuery-touch-events using Bower as follows:

$ bower install jquery-touch-events

jQuery Touch Events can also be installed using NPM as follows:

$ npm i @benmajor/jquery-touch-events

If you are installing the library via NPM, after running thenpm i command above, you'll also need to ensure that you import the modules into you project files wherever you wish to use the events. Place the following line alongside your other imports:

import"@benmajor/jquery-touch-events";

All of the events outlined above have been written using jQuery'sevent.special object, and so can be used in conjunction with jQuery's event handling functions, as well as shortcut wrappers. As a result, all of the events that are supported by this library may be handled using any of jQuery's own event-specific methods, such ason() andone().

The following code snippets showcase some basic usage with jQuery:

Binding atap event to an element:

When binding, you should use jQuery'son() function as follows (avoid the use oflive() andbind() as these are now deprecated and will be removed from future versions of jQuery).

$('#myElement').on('tap',function(e){console.log('User tapped #myElement');});

Triggering the event:

$('#myElement').trigger('tap');

Removing the event:

$('#myElement').off('tap',handler);

Using method wrapper:

$('#myElement').tap(function(e){console.log('User tapped #myElement');});

Method chaining:
Chaining has also been preserved, so you can easily use these events in conjunction with other jQuery functions, or attach multiple events in a single, chained LOC:

$('#myElement').singletap(function(){console.log('singletap');}).doubletap(function(){console.log('doubletap');});

• tapstart
  Fired as soon as the user begins touching an element (or clicking, for desktop environments).
• tapend
  Fired after the user releases their finger from the target element (or releases their mouse button on desktops).
• tapmove
  Fired as soon as the user begins moving their finger on an element (or moving their mouse, for desktop environments).
• tap
  This event is fired whenever the user taps and releases their finger on the target element. Caution should be observed when using this event in conjunction with tap events, especiallydoubletap. This event will be fired twice whendoubletap is used, so it is recommended to usesingletap in this case.
• singletap
  Unliketap this event is only triggered once we are certain the user has only tapped the target element a single time. This will not be triggered bydoubletap ortaphold, unliketap. Since we need to run some tests to make sure the user isn't double tapping or holding a tap on the target element, this event is fired with a short delay (currently of 500 milliseconds).
• doubletap
  Triggered whenever the user double taps on the target element. The threshold (time between taps) is currently set at 500 milliseconds.
• taphold
  This event is triggered whenever the user taps on the target element and leaves their finger on the element for at least750 milliseconds.
• swipe
  This is called whenever the user swipes their finger on the target element. It is not direction-dependent, and is fired regardless of the direction the user swiped.
• swipeup
  Similar toswipe, except only called when the user swipes their finger in an upward direction on the target element (i.e. bottom to top)
• swiperight
  Similar toswipe, but triggered only when the user swipes their finger left to right on the target element.
• swipedown
  Similar toswipe, but triggered only when the user swipes their finger top to bottom on the target element.
• swipeleft
  Similar toswipe, but triggered only when the user swipes their finger from right to left.
• swipeend
  Theswipeend event is trigged whenever a swipe event ends (i.e. the user finished moving their finger / cursor and released it). This event should be used to handle custom functions, since it will be triggered only when the swipe ends, rather than triggering immediately when the threshold has been met.
• scrollstart
  Triggered as soon as scrolling begins on the target element.
• scrollend
  Triggered as soon as scrolling is stopped on the target element.
• orientationchange
  This event is triggered when the orientation of the device is changed. Please note that it uses throttling for non-mobile devices, or devices which do not support the nativeorientationchange event. In the latter instance, a detection of the viewport size change occurs.

Each event now features a second argument that can be passed to the specified callback function. This argument includes some basic data relating specifically to the event, and can be accessed as a standard JavaScript object. To hook into this parameter, you should use the following code:

$(element).swipeend(function(e,touch){});

Given the example above,touch will now contain some basic data that can be accessed throughtouch.. The first argument will represent the lastnative event that occurred (the names used for these two arguments is irrelevant).

Each event provides different callback data. The following shows the numerous data that are passed back to the callback function inside the second parameter:

offset - object containing the X and Y positions of the event relative to the element to which is was bound. Accessed throughoffset.x andoffset.y respectively.

position - object containing the X and Y positions of the event relative to the screen. Accessed throughposition.x andposition.y respectively.

target - the jQuery object from which the event was triggered.

time - JavaScript timestamp the event occurred (milliseconds since the Unix Epoch)

duration: the time in milliseconds that the user tapped for.

endOffset - object containing the X and Y positions of the end event (i.e. when the user released their finger or mouse) relative to the element to which the event was bound. Accessed throughendOffset.x andendOffset.y respectively.

endPosition - object containing the X and Y positions of the end event (i.e. when the user released their finger or mouse) relative to the screen. Accessed throughendPosition.x andendPosition.y respectively.

endTime - JavaScript timestamp thetaphold was triggered (milliseconds since the Unix Epoch). This will ordinarily be equal to thestartTime +taphold threshold.

startOffset - object containing the X and Y positions of the start event (i.e. when the user pressed their finger or mouse) relative to the element to which the event was bound. Accessed throughendOffset.x andendOffset.y respectively.

startPosition - object containing the X and Y positions of the start event (i.e. when the user pressed their finger or mouse) relative to the screen. Accessed throughendPosition.x andendPosition.y respectively.

startTime - JavaScript timestamp thetaphold started (milliseconds since the Unix Epoch).

target - the jQuery object from which the event was triggered.

firstTap - Object containing the same data as atap event, but for the first tap to occur.

secondTap - Object containing the same data as atap event, but for the second (i.e. final) tap to occur.

interval - the time in milliseconds between the two tap.

direction - string representing the swipe direction (eitherup,right,down orleft).

duration - the time in milliseconds over which the swipe took place (for best results, use withswipeend only, as this will typically be equal to the definedswipe-threshold.

xAmount - number of pixels the swipe occupied on the X-axis (returned regardless of direction).

yAmount - number of pixels the swipe occupied on the Y-axis (returned regardless of direction).

startEvnt - Object containing the same data as atap event, but captured when swiping begins.

endEvent - Object containing the same data as atap event, but captured when swiping is complete.

You can also define custom thresholds to be used forswipe events (swipeup,swiperight,swipedown andswipeleft) to prevent interference with scrolling and other events. To do so, simply assign adata-xthreshold ordata-ythreshold to the target element as follows:

<div data-xthreshold="500"></div>

The value you define is the difference in pixels that the user must move before the event is triggered on the target element. If no threshold is defined, a default of50px will be used.

data-xthreshold defines the horizontal threshold.

data-ythreshold defines the vertical threshold.

Update as of 1.0.7:Following requests from users and contributors, as of 1.0.7 it is now possible to also define thedoubletap threshold via jQuery'sdata- attributes as follows:

data-threshold defines the amount of time (in milliseconds) after which thedoubletap event is fired on the target element.

In addition to the numerous additional events that are provided, the library also includes a number of utility functions that can be used to further leverage the power of native events within your website or application. These utility functions can be used for unifying basic events, such astapstart ormousedown.

The following utility functions are provided (each function is registered to the jQuery namespace, and should be called with$.funcName() (orjQuery.funcName() for compatibility):

• isTouchCapable():
  Returnstrue orfalse depending upon whether touch events are supported.
• getStartEvent():
  Returnstouchstart for touch-enabled devices, ormousedown for standard environments.
• getEndEvent():
  Returnstouchend for touch-enabled devices, ormouseup for standard environments.
• getMoveEvent():
  Returnstouchmove for touch-enabled devices, ormousemove for standard environments.
• getTapEvent():
  Returnstap for touch-enabled devices, orclick for standard environments.
• getScrollEvent():
  Returnstouchmove for touch-enabled devices, orscroll for standard environments.Caution should be exercised when using this function, since some mobile browsers will correctly bind toscroll as well astouchmove.

I have put together a simple demo application that shows the numerous events in action. The console on the left hand side is used to show information about the events that have been called. You can examine the code easily by viewing the page's source to lear more about how this works. Please click on the below to check out the demo:

http://lincweb.co.uk/labs/jquery-touch-events/demo/

Please be aware that this demonstration uses Google's hosted jQuery file, and also pulls the latest version of the events library from GitHub. It is a great place to check the status of the library. Since this demo uses the vanilla code, it is a good idea to check the library functionality here for your own reference. If you're running into problems with the library, please check this demonstration using your device in the first instance. You can scan in the QR below to go directly to the web page:

The library works with jQuery 1.7.0+. All major browsers have been tested without problem. The library is not compatible with jQuery < 1.7.

Licensed under the MIT License:

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.