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.
After almost 2 years in public beta, I am pleased to announce that the library is now officially launched as version 1.0.0. I'll be updating the version history over time with digests of fixes, features and improvements:
document and window.tap2).taphold2).doubletap.tapholdsingletapoffset() was sometimes called on null (instead of window).offset position of events was incorrect when inside of a parent element. MSPointerEvent for compatibility with IE11 and Edgetap.MSPointerEventjQuery Touch Events, as the name suggests, require only the jQuery library (version 1.7+) to run. You should download the latest release from the src folder, and include the Javascript file within your project, after jQuery has been included. It is recommended to also wrap your code inside the DOMReady 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:
<script type="text/javascript" src="https://github.com/benmajor/jQuery-Touch-Events/raw/2.0.3/path/to/jquery.mobile-events.min.js"></script>
The awesome guys over at cdnjs have kindly added the library to their CDN so you can include it as follows directly into your application:
<script src="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
All of the events outlined above have been written using jQuery's event.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 as on() and one().
The following code snippets showcase some basic usage with jQuery:
Binding a tap event to an element:
When binding, you should use jQuery's on() function as follows (avoid the use of live() and bind() 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');
});
tapstarttapendtapmovetapdoubletap. This event will be fired twice when doubletap is used, so it is recommended to use singletap in this case.singletaptap 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 by doubletap or taphold, unlike tap. 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).doubletaptapholdswipeswipeupswipe, except only called when the user swipes their finger in an upward direction on the target element (i.e. bottom to top)swiperightswipe, but triggered only when the user swipes their finger left to right on the target element.swipedownswipe, but triggered only when the user swipes their finger top to bottom on the target element.swipeleftswipe, but triggered only when the user swipes their finger from right to left.swipeendswipeend 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. scrollstartscrollendorientationchangeorientationchange 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 through touch.. The first argument will represent the last native 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:
tapstart, tapend, tapmove, tap, singletap:offset - object containing the X and Y positions of the event relative to the element to which is was bound. Accessed through offset.x and offset.y respectively.
position - object containing the X and Y positions of the event relative to the screen. Accessed through position.x and position.y respectively.
target - the jQuery object from which the event was triggered.
time - JavaScript timestamp the event occurred (milliseconds since the Unix Epoch)
taphold: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 through endOffset.x and endOffset.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 through endPosition.x and endPosition.y respectively.
endTime - JavaScript timestamp the taphold was triggered (milliseconds since the Unix Epoch). This will ordinarily be equal to the startTime + 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 through endOffset.x and endOffset.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 through endPosition.x and endPosition.y respectively.
startTime - JavaScript timestamp the taphold started (milliseconds since the Unix Epoch).
target - the jQuery object from which the event was triggered.
doubletap:firstTap - Object containing the same data as a tap event, but for the first tap to occur.
secondTap - Object containing the same data as a tap event, but for the second (i.e. final) tap to occur.
interval - the time in milliseconds between the two tap.
swipe, swipeup, swiperight, swipedown, swipeleft, swipeend:direction - string representing the swipe direction (either up, right, down or left).
duration - the time in milliseconds over which the swipe took place (for best results, use with swipeend only, as this will typically be equal to the defined swipe-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 a tap event, but captured when swiping begins.
endEvent - Object containing the same data as a tap event, but captured when swiping is complete.
You can also define custom thresholds to be used for swipe events (swipeup, swiperight, swipedown and swipeleft) to prevent interference with scrolling and other events. To do so, simply assign a data-xthreshold or data-ythreshold to the target element as follows:
``
``
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 of 50px 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 the doubletap threshold via jQuery's data- attributes as follows:
data-threshold defines the amount of time (in milliseconds) after which the doubletap 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
$ claude mcp add jQuery-Touch-Events \
-- python -m otcore.mcp_server <graph>