mn-touch
Ultrafast AngularJS touch events directive (tap, hold and swipe)
Why?
Well, I'm working on a mobile project and I have to create a Cordova app that works smoothly on Android (4.1.*+), iOS (7+) and Windows Phone (8.0+).
I tried ngTouch, Quo.js, Hammer.js, ecc. but nothing reached the performances (and the cross-platform portability as well) I wanted, so I decided to write my own directive: really fast and really tested on many devices.
Install
- bower:
bower install mn-touch
- npm:
npm install mn-touch
- by hand: read below...
Usage
Nothing simpler.
This directive's module is 'mn': add it to your module dependencies.
var module = angular.module('yourModule', ['mn']);
Tap
<div
mn-touch
tap="yourFunction()" >
...
</div>
Secure tap
<div
mn-touch
secure-tap="yourFunction()" >
...
</div>
Hold
<div
mn-touch
hold="yourFunction()" >
...
</div>
Swipe (left, right, up, down)
<div
mn-touch
swipe-left="yourFunction()" >
...
</div>
Mixed events
<div
mn-touch
secure-tap="yourFunction()"
swipe-left="yourSwipeLeftFunction()"
swipe-down="yourSwipeDownFunction()" >
...
</div>
Maybe you're asking why I've implemented 2 different taps:
- tap is faster and doesn't perform any check if the target element (or the parent) has other touch event handlers attached on it, so it's fired immediately; no other event will be fired, so use it on elements that need to handle this event only;
- secure-tap is a couple of milliseconds slower than tap and performs a check before being fired. In this case, you can attach secure-tap and swipe-... events to the same element (or html tree), without any risk.
Obviously, you can use it with any html element other than div.
Threshold
If you want to change the edge between secure-tap and swipe-… events, you can do it using the threshold attribute. It represents the number of offset-points (between the start and the end of the touch) under which the event is recognized as a secure-tap. If the offset is higher than threshold, the event will be processed as a swipe-… depending on the direction.
Hold event also responds to this rule, as the secure-tap event does.
Default threshold is 10.
<div
mn-touch
threshold="30"
secure-tap="yourFunction()"
swipe-left="yourSwipeLeftFunction()" >
...
</div>
Holdfor
If you want to change the edge between secure-tap and hold events, you can do it using the holdfor attribute. It represents the number of milliseconds over which the secure-tap event is recognized as a hold.
Default holdfor is 500.
<div
mn-touch
holdfor="600"
secure-tap="yourFunction()"
hold="yourHoldFunction()" >
...
</div>
Event informations
And what about information? How can I call a preventDefault()
? Here I am: from version 1.1.0 you can pass an event-informations object to your callback. Example:
<div
mn-touch
swipe-left="yourSwipeLeftFunction($event)" >
...
</div>
As you can see, the swipe-left receives an object called $event
containing all the informations you need to manage your touch event. I adopted the same standard used by AngularJS in terms of event-information objects.
Obviously, $event
is optional and this is its structure:
{
name: 'event-name',
target: {},
threshold: 10,
holdfor: 500,
isRunning: false,
isSecure: true,
directionX: -15,
directionY: 3,
offsetX: 15,
offsetY: 3,
types: {
start: 'touchstart',
move: 'touchmove',
end: 'touchend',
cancel: 'touchcancel'
},
coords: {
start: {x, y},
end: {x, y}
},
events: {
start: {},
end: {}
},
time: {
start: 123456000,
end: 123456700,
duration: 700
}
}
Dependencies
This plugin needs AngularJS only (version 1.2.*+ for sure; other versions haven’t been tested yet, but I think this directive would run anyway).
No jQuery required (but you can use it).
Development
If you want to develop and then compress your edited version of this directive, you can use npm
:
$ npm install
$ npm run build
Known issues
- Google Chrome suggest to use deferred for long-task execution (read more), but since I don't want to add any dependency to this plugin (except for Angular), I will live with this warning.
License
This software is released under MIT license terms.
Have fun!