Angular Hammer Propagating v1.0.0

An Angular.js module that enables you to bind custom behavior to Hammer.js touch events. It was derived from the Angular Hammer project, itself derived from the Angular Hammer project by Monospaced. It utilizes Propagating Hammerjs to correct Hammer's event propagation order and allow for stopPropagation on Hammer events.

Installation

Install using NPM.

$ npm install --save angular-hammer-propagating

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+. You will need to include both Hammer.js and Hammer Propagating into your application. With browserify this can be done via a browserify shim in the package.json of your application:

"dependencies": {
    "angular-hammer-propagating": "^1.0.0",
    "hammerjs": "^2.0.4",
    "propagating-hammerjs": "^1.4.1"
},
...
"browser": {
    "angular-hammer-propagating": "./node_modules/angular-hammer-propagating/angular.hammer-propagating.js"
},
"browserify-shim": {
    "angular-hammer-propagating": {
      "exports": "angular.module('hmTouchEvents').name",
      "depends": [
        "./node_modules/hammerjs/hammer.js:Hammer",
        "./node_modules/propagating-hammerjs:propagating"
      ]
    }
}

A Note on Version Naming

Angular Hammer Propagating 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.

• pan : hmPan
  • panstart : hmPanstart
  • panmove : hmPanmove
  • panend : hmPanend
  • pancancel : hmPancancel
  • panleft : hmPanleft
  • panright : hmPanright
  • panup : hmPanup
  • pandown : hmPandown
• pinch : hmPinch
  • pinchstart : hmPinchstart
  • pinchmove : hmPinchmove
  • pinchend : hmPinchend
  • pinchcancel : hmPinchcancel
  • pinchin : hmPinchin
  • pinchout : hmPinchout
• press : hmPress
  • pressup : HmPressup
• rotate : hmRotate
  • rotatestart : hmRotatestart
  • rotatemove : hmRotatemove
  • rotateend : hmRotateend
  • rotatecancel : hmRotatecancel
• swipe : hmSwipe
  • swipeleft : hmSwipeleft
  • swiperight : hmSwiperight
  • swipeup : hmSwipeup
  • swipedown : hmSwipedown
• tap : hmTap
• doubletap : hmDoubletap

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:

• If the type is provided, the options will only be applied to recognizers of that type. If this type does cannot be resolved to any of the six gesture types, the recognizer will not be created and the options will not be applied.
• If no type property is specified, those options will be applied to all of the recognizers associated with that element/manager. When you are defining recognizer options, it is best to define an options object with no type before defining those with types.
• The event property is stripped from recognizer options associated standard gestures as a safeguard. It can be used to define custom gestures (see below).
• Some Hammer recognizers that accept a direction option. For these recognizers, use the directions option to specify which directions you would like to support. The value of this property should be a string of DIRECTION_* values separated by a | and containing no spaces. Angular Hammer will parse this field into the proper Hammer value, and set the direction option for the recognizer.
• Setting preventDefault, preventGhosts, or stopPropagation will enable that behavior for all events recognized by that Recognizer, use this judiciously.
• Defining options not supported by that recognizer type will have no effect on that recognizers behavior.

| 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>

Propagation Handling

By default Hammerjs orders its events as parent to child and claims the target of the event is whatever element the event handler was declared on. In addition, no stopPropagation method is available on the Hammerjs events. To restore a more natural event usage, we wrap Hammerjs in Propagating Hammerjs.

Child to Parent Ordering

We get this for free with Propagating Hammerjs, so you can expect child event handlers to fire before parent event handlers.

Original Target

To access the original target of the event you can do the following

<div hm-panstart="parentPanStart">
    <a href="#" hm-panstart="childPanStart">
</div>

module.controller('someDirective', function($scope) {
    $scope.parentPanStart = function(event) {
        console.log(event.firstTarget);
    }
});

Now if you click on the <a> element, the parent handler will log that element to the console, rather than the parent <div> on which it is registered.

Stop Propagation

Extending the above example, we can utilize the event.stopPropagation method on the event passed to the child in order to prevent the parent handler from ever getting called.

<div hm-panstart="parentPanStart">
    <a href="#" hm-panstart="childPanStart">
</div>

module.controller('someDirective', function($scope) {
    $scope.parentPanStart = function(event) {
        console.log(event.firstTarget);
    }

    $scope.childPanStart = function(event) {
        event.stopPropagation();
    }
});