Touch Swipe

Detects single and multiple finger swipes, pinches and falls back to mouse 'drags' on the desktop.

Swipe on Frontendcore is solved by a wrapper. Please use always to the Frontencore Wrapper to avoid compatibilty issues in the future. For more information or advanced features check TouchSwipe by Matt Bryson (The wrapped library).

How it works

Swipe is not a component like the rest, because it's totally done to be called from one module insted with data-arguments. First of all you should include swipe in your module:

FrontendCore.define('my-module', [ 'swipe' ], function () {
                ...
});

Now you have available the swipe function throught the namespace FrontendTools. Let's see some demos.

Basic Swipe

;(function (window, document, oGlobalSettings, FrontendTools, FrontendCore, $) {
	'use strict';

	FrontendCore.define('basic-swipe', ['swipe'], function () {
		return {
			onStart: function () {

				FrontendTools.swipe( "#basic-swipe", {
					//Generic swipe handler for all directions
					swipe: function (event, direction, distance, duration, fingerCount, fingerData) {
						$(this).text("You swiped " + direction);
					}
				});
			}
		};
	});

})(window, document, oGlobalSettings, FrontendTools, FrontendCore, $);

Single Swipe

;(function (window, document, oGlobalSettings, FrontendTools, FrontendCore, $) {
	'use strict';

	FrontendCore.define('single-swipe', ['swipe'], function () {
		return {
			onStart: function () {

				//Keep track of how many swipes
				var count=0;

				FrontendTools.swipe( "#single-swipe", {
					//Single swipe handler for left swipes
					swipeLeft:function(event, direction, distance, duration, fingerCount) {
						$(this).text("You swiped " + direction + " " + ( ++count ) + " times " );
					},
					//Default is 75px, set to 0 for demo so any distance triggers swipe
					threshold:0
				});
			}
		};
	});

})(window, document, oGlobalSettings, FrontendTools, FrontendCore, $);

Any finger swipe

;(function (window, document, oGlobalSettings, FrontendTools, FrontendCore, $) {
	'use strict';

	FrontendCore.define('any-finger-swipe', ['swipe'], function () {
		return {
			onStart: function () {

				FrontendTools.swipe( "#any-finger-swipe", {
					swipe:function(event, direction, distance, duration, fingerCount, fingerData) {
						$(this).text("You swiped " + direction + " with " + fingerCount + " fingers");
					},
					threshold:0,
					fingers:'all'
				});
			}
		};
	});

})(window, document, oGlobalSettings, FrontendTools, FrontendCore, $);

Defaults

Name	Type	Attributes	Default	Description
`fingers`	int	<optional>	`1`	The number of fingers to detect in a swipe. Any swipes that do not meet this requirement will NOT trigger swipe handlers.
`threshold`	int	<optional>	`75`	The number of pixels that the user must move their finger by before it is considered a swipe.
`cancelThreshold`	int	<optional>	`null`	The number of pixels that the user must move their finger back from the original swipe direction to cancel the gesture.
`pinchThreshold`	int	<optional>	`20`	The number of pixels that the user must pinch their finger by before it is considered a pinch.
`maxTimeThreshold`	int	<optional>	`null`	Time, in milliseconds, between touchStart and touchEnd must NOT exceed in order to be considered a swipe.
`fingerReleaseThreshold`	int	<optional>	`250`	Time in milliseconds between releasing multiple fingers. If 2 fingers are down, and are released one after the other, if they are within this threshold, it counts as a simultaneous release.
`longTapThreshold`	int	<optional>	`500`	Time in milliseconds between tap and release for a long tap
`doubleTapThreshold`	int	<optional>	`200`	Time in milliseconds between 2 taps to count as a double tap
`swipe`	function	<optional>	`null`	A handler to catch all swipes. See event:swipe
`swipeLeft`	function	<optional>	`null`	A handler that is triggered for "left" swipes. See event:swipeLeft
`swipeRight`	function	<optional>	`null`	A handler that is triggered for "right" swipes. See event:swipeRight
`swipeUp`	function	<optional>	`null`	A handler that is triggered for "up" swipes. See event:swipeUp
`swipeDown`	function	<optional>	`null`	A handler that is triggered for "down" swipes. See event:swipeDown
`swipeStatus`	function	<optional>	`null`	A handler triggered for every phase of the swipe. See event:swipeStatus
`pinchIn`	function	<optional>	`null`	A handler triggered for pinch in events. See event:pinchIn
`pinchOut`	function	<optional>	`null`	A handler triggered for pinch out events. See event:pinchOut
`pinchStatus`	function	<optional>	`null`	A handler triggered for every phase of a pinch. See event:pinchStatus
`tap`	function	<optional>	`null`	A handler triggered when a user just taps on the item, rather than swipes it. If they do not move, tap is triggered, if they do move, it is not.
`doubleTap`	function	<optional>	`null`	A handler triggered when a user double taps on the item. The delay between taps can be set with the doubleTapThreshold property.
`longTap`	function	<optional>	`null`	A handler triggered when a user long taps on the item. The delay between start and end can be set with the longTapThreshold property.
`(function)`				[hold=null] A handler triggered when a user reaches longTapThreshold on the item.
`triggerOnTouchEnd`	boolean	<optional>	`true`	If true, the swipe events are triggered when the touch end event is received (user releases finger). If false, it will be triggered on reaching the threshold, and then cancel the touch event automatically.
`triggerOnTouchLeave`	boolean	<optional>	`false`	If true, then when the user leaves the swipe object, the swipe will end and trigger appropriate handlers.
`allowPageScroll`	string \| undefined	<optional>	`'auto'`	How the browser handles page scrolls when the user is swiping on a touchSwipe object. `"auto"` : all undefined swipes will cause the page to scroll in that direction. `"none"` : the page will not scroll when user swipes. `"horizontal"` : will force page to scroll on horizontal swipes. `"vertical"` : will force page to scroll on vertical swipes.
`fallbackToMouseEvents`	boolean	<optional>	`true`	If true mouse events are used when run on a non touch device, false will stop swipes being triggered by mouse events on non tocuh devices.
`excludedElements`	string	<optional>	`"button, input, select, textarea, a, .noSwipe"`	A jquery selector that specifies child elements that do NOT trigger swipes. By default this excludes all form, input, select, button, anchor and .noSwipe elements.
`preventDefaultEvents`	boolean	<optional>	`true`	by default default events are cancelled, so the page doesn't move. You can dissable this so both native events fire as well as your handlers.

Events

doubleTap

Default Value:

null

A double tap handler triggered when a user double clicks or taps on an element. You can set the time delay for a double tap with the $.fn.swipe.defaults#doubleTapThreshold property. Note: If you set both doubleTap and tap handlers, the tap event will be delayed by the doubleTapThreshold as the script needs to check if its a double tap.

Parameters:

Name	Type	Description
`event`	EventObject	The original event object
`target`	DomObject	The element clicked on.

hold

Default Value:

null

A hold tap handler triggered as soon as the longTapThreshold is reached You can set the time delay for a long tap with the $.fn.swipe.defaults#longTapThreshold property.

Parameters:

Name	Type	Description
`event`	EventObject	The original event object
`target`	DomObject	The element clicked on.

longTap

Default Value:

null

A long tap handler triggered once a tap has been release if the tap was longer than the longTapThreshold. You can set the time delay for a long tap with the $.fn.swipe.defaults#longTapThreshold property.

Parameters:

Name	Type	Description
`event`	EventObject	The original event object
`target`	DomObject	The element clicked on.

pinchIn

Default Value:

null

A handler triggered for pinch in events.

Parameters:

Name	Type	Description
`event`	EventObject	The original event object
`direction`	int	The direction the user pinched in.
`distance`	int	The distance the user pinched
`duration`	int	The duration of the swipe in milliseconds
`fingerCount`	int	The number of fingers used.
`zoom`	int	The zoom/scale level the user pinched too, 0-1.
`fingerData`	object	The coordinates of fingers in event

pinchOut

Default Value:

null

A handler triggered for pinch out events.

Parameters:

Name	Type	Description
`event`	EventObject	The original event object
`direction`	int	The direction the user pinched in.
`distance`	int	The distance the user pinched
`duration`	int	The duration of the swipe in milliseconds
`fingerCount`	int	The number of fingers used.
`zoom`	int	The zoom/scale level the user pinched too, 0-1.
`fingerData`	object	The coordinates of fingers in event

pinchStatus

Default Value:

null

A handler triggered for all pinch events. This handler is constantly fired for the duration of the pinch. This is triggered regardless of thresholds.

Parameters:

Name	Type	Description
`event`	EventObject	The original event object
`direction`	int	The direction the user pinched in.
`distance`	int	The distance the user pinched
`duration`	int	The duration of the swipe in milliseconds
`fingerCount`	int	The number of fingers used.
`zoom`	int	The zoom/scale level the user pinched too, 0-1.
`fingerData`	object	The coordinates of fingers in event

swipe

Default Value:

null

A catch all handler that is triggered for all swipe directions.

Parameters:

Name	Type	Description
`event`	EventObject	The original event object
`direction`	int	The direction the user swiped in.
`distance`	int	The distance the user swiped
`duration`	int	The duration of the swipe in milliseconds
`fingerCount`	int	The number of fingers used.
`fingerData`	object	The coordinates of fingers in event
`currentDirection`	string	The current direction the user is swiping.

swipeDown

Default Value:

null

A handler that is triggered for "down" swipes.

Parameters:

Name	Type	Description
`event`	EventObject	The original event object
`direction`	int	The direction the user swiped in.
`distance`	int	The distance the user swiped
`duration`	int	The duration of the swipe in milliseconds
`fingerCount`	int	The number of fingers used.
`fingerData`	object	The coordinates of fingers in event
`currentDirection`	string	The current direction the user is swiping.

swipeLeft

Default Value:

null

A handler that is triggered for "left" swipes.

Parameters:

Name	Type	Description
`event`	EventObject	The original event object
`direction`	int	The direction the user swiped in.
`distance`	int	The distance the user swiped
`duration`	int	The duration of the swipe in milliseconds
`fingerCount`	int	The number of fingers used.
`fingerData`	object	The coordinates of fingers in event
`currentDirection`	string	The current direction the user is swiping.

swipeRight

Default Value:

null

A handler that is triggered for "right" swipes.

Parameters:

Name	Type	Description
`event`	EventObject	The original event object
`direction`	int	The direction the user swiped in.
`distance`	int	The distance the user swiped
`duration`	int	The duration of the swipe in milliseconds
`fingerCount`	int	The number of fingers used.
`fingerData`	object	The coordinates of fingers in event
`currentDirection`	string	The current direction the user is swiping.

swipeStatus

Default Value:

null

A handler triggered for every phase of the swipe. This handler is constantly fired for the duration of the pinch. This is triggered regardless of swipe thresholds.

Parameters:

Name	Type	Description
`event`	EventObject	The original event object
`phase`	string	The phase of the swipe event.
`direction`	string	The direction the user swiped in. This is null if the user has yet to move.
`distance`	int	The distance the user swiped. This is 0 if the user has yet to move.
`duration`	int	The duration of the swipe in milliseconds
`fingerCount`	int	The number of fingers used.
`fingerData`	object	The coordinates of fingers in event
`currentDirection`	string	The current direction the user is swiping.

swipeUp

Default Value:

null

A handler that is triggered for "up" swipes.

Parameters:

Name	Type	Description
`event`	EventObject	The original event object
`direction`	int	The direction the user swiped in.
`distance`	int	The distance the user swiped
`duration`	int	The duration of the swipe in milliseconds
`fingerCount`	int	The number of fingers used.
`fingerData`	object	The coordinates of fingers in event
`currentDirection`	string	The current direction the user is swiping.

tap

Default Value:

null

A click / tap handler triggered when a user simply clicks or taps, rather than swipes on an element.

Parameters:

Name	Type	Description
`event`	EventObject	The original event object
`target`	DomObject	The element clicked on.