View on GitHub

AngularHammer

Hammer.js support for Angular.js

Download this project as a .zip file Download this project as a tar.gz file

Angular Hammer v2.1.10

An Angular.js module that enables you to bind custom behavior to Hammer.js touch events. It was derived from the Angular Hammer project by Monospaced.

Installation

Install using Bower.

$ bower install --save ryanmullins-angular-hammer

Install using NPM.

$ npm install --save angular-hammer

Add hmTouchEvents to your app or module's dependencies. This module is designed to work with Angular.js v1.2.0+, and Hammer.js v2.0.0+.

A Note on Version Naming

Angular Hammer uses the semantic version naming convention major.minor.patch typical of most Bower projects, with one small difference. The major version will only change when the major version of Hammer.js changes. Changes to minor should be thought of as possibly breaking, though typically they will be breaking changes to the API (i.e. changing the name of some directive or attribute). Changes to patch should be thought of as bug fixes or small feature additions that may require changing or adding HTML attribute values.

A Note on Angular.js 2.0

At this time Angular Hammer has been tested with both Angular.js v1.2.x and v1.3.0. Angular.js v2.0 presents massive changes to the framework. Until such time as this README indicates otherwise, it should be assumed that Angular Hammer will not be moving forward to Angular.js v2.0. I reserve the right to change my mind once the v2.0 spec come out and I am able to assess the transition path.

Usage

The hmTouchEvents module provides a series of attribute directives for hooking into the standard Hammer.js events.

Standard Directives

The following list shows the Hammer event and corresponding Angular directive (format: <eventName> : <directiveName>). Events on the top level are fired every time a gesture of that type happens. The second-level events are more specific to the gesture state (i.e. direction, start/stop), but trigger events of their top level type.

Behaviors to be executed on an event are defined as values of the attribute. This value is parsed as an Angular expression. Beware, invalid Angular expressions will throw an Angular error with those terrible call stacks.

Example Definition:

<div hm-tap="onHammer"></div>
<div hm-tap="model.name = 'Ryan'"></div>

Manager Options

Each element that responds to Hammer events contains it's own manager, which keeps track of the various gesture recognizers attached to that element. Angular Hammer does not make use of the standard Hammer() constructor, instead instantiating an empty manager and adding only the required recognizers. However, if you were to add the same series of directives to an element, the default behavior would be the same as if they had been instantiated using the Hammer() constructor.

The behavior of any manager can be customized using the hmManagerOptions attribute. This attribute value should be a stringified JSON Object that has one or more of the properties listed below. If you choose to set the cssProps option, lease make sure that you are using the properties listed in the Hammer Documentation. If you define the preventGhosts property, that value will be attributed to all recognizers associated with that manager.

Possible Properties:

{
    "cssProps": Object
    "domEvents": Boolean
    "enable": Boolean
    "preventGhosts": Boolean
}

Example Definition:

<div hm-tap="onHammer" hm-manager-options='{"enabled":true,"preventGhosts":true}'></div>

Recognizer Options

Gesture recognizers are responsible for linking events and handlers. Each element has a manager that maintains a list of these recognizers. Hammer defines some default behavior for each type of recognizer (see the links in the table below), but that behavior can be customized using the hmRecognizerOptions attribute. The value of the hmRecognizerOptions should be stringified JSON, either an Object or an Array of Objects.

Recognizer options objects may have any of the properties listed in the table below, a checkmark in a column means that either Hammer or Angular Hammer (denoted AH) will make use of this option when instantiating the recognizer. A couple of things to be aware of:

Option Type Pan Pinch Press Rotate Swipe Tap
directions String
event String
interval Number
pointers Number
posThreshold Number
preventDefault (AH) Boolean
preventGhosts (AH) Boolean
stopPropagation (AH) Boolean
taps Number
threshold Number
time Number
type (AH) String
velocity Number

Example definition:

<div hm-tap="onHamer" hm-recognizer-options='{"threshold":200}'></div>
<div hm-tap="onHamer" hm-pan="onHamer" hm-recognizer-options='[
    {"type":"tap","enable":false,},
    {"type":"pan","directions":"DIRECTION_HORIZONTAL|DIRECTION_UP"}
]'></div>

Custom Gesture Recognizers

You can add custom gesture recognizers using the hmCustom directive. Custom gestures are defined using the hmRecognizerOptions attribute. You can define a single custom gesture using an object, or a series of custom gestures using an array of objects. However, only a single handler, set as the value of the hmCustom attribute, will be triggered when any of these custom gestures are recognized.

When defining a custom gesture, the recognizer options object must have a value for the type and event properties.

The behavior that is executed when this gesture is recognized is the value of this attribute. Currently (as of v2.1), only a single behavior handling function can be passed as the custom directive value. This decision was made to unify the use of the hmManagerOptions and hmRecognizerOptions, but may be changed in future versions to support multiple behavior handlers. The type property is used to determine which base type of gesture recognizer to modify. The event property is the name of the gesture as well as the name of the only event that Hammer will fire when it recognizes this gesture. Do not mix custom and standard gesture recognizers attributes in a single element as the behaviors will be in conflict.

Example: Defining a Custom Gesture Recognizer

<div 
    hm-custom="onHammer"
    hm-recognizer-options='[
      {"type":"pan","event":"twoFingerPan","pointers":2,"directions":"DIRECTION_ALL"},
      {"type":"tap","event":"dbltap","pointers":2,"taps":1}
    ]'></div>

Demo