mn-touch v1.3.2

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', // event name
	target: {}, // DOM element targeted by the directive
	threshold: 10, // the threshold integer value
	holdfor: 500, // the holdfor integer value
	isRunning: false, // event status
	isSecure: true, // tap is not secure, all other evets are secure
	directionX: -15, // x difference between end point and start point
	directionY: 3, // y difference between end point and start point
	offsetX: 15, // absolute value of directionX
	offsetY: 3, // absolute value of directionY
	types: {
		start: 'touchstart', // original touch start event name
		move: 'touchmove', // original touch move event name
		end: 'touchend', // original touch end event name
		cancel: 'touchcancel' // original touch cancel event name, if exists
	},
	coords: {
		start: {x, y}, // couple of integer
		end: {x, y} // couple of integer
	},
	events: {
		start: {}, // original touch start event
		end: {} // original touch end event
	},
	time: {
		start: 123456000, // touch start time
		end: 123456700, // touch end time
		duration: 700 // touch duration
	}
}

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 # install module dependencies
$ npm run build # run compression task on source and output the dist files

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!