chriswessels / ember-hammer

ember-hammer is a neat interface for defining Hammer.js gestural behaviour in your Ember.js Views.

ember-hammer

ember-hammer is a neat interface for defining Hammer.js gestural behaviour in your Ember.js Components. It is easy to use and lightweight.

Note: Hammer.js 2.x support is currently experimental.

##Example

/* ES6 Modules Example */
import Ember from 'ember';

export default Ember.Component.extend({
  hammerOptions: {
    swipe_velocity: 0.5
  },
  gestures: {
    swipeLeft: function (event) {
      // do something like send an event down the controller/route chain
      return false; // return `false` to stop bubbling
    }
  }
});

/* Globals Example */
App.SomeComponent = Ember.Component.extend({
  hammerOptions: {
    swipe_velocity: 0.5
  },
  gestures: {
    swipeLeft: function (event) {
      // do something like send an event down the controller/route chain
      return false; // return `false` to stop bubbling
    }
  }
});

##Usage

###With ember-cli

In your project directory (generated by ember-cli), run the following commands in your terminal:

$ bower install --save hammerjs#1.1.3
$ bower install --save ember-hammer

In your Brocfile.js (which should be in the root of your project directory), before module.exports = app.toTree();, add the following lines:

app.import('bower_components/hammerjs/hammer.js');
app.import('bower_components/ember-hammer/ember-hammer.js');

That should be it. You'll now be able to define a gestures object in your components.

###With globals

First, include the ember-hammer.js file into your asset delivery pipeline (ideally this should include minification, concatenation and gzipping facilities). ember-hammer should be included after Ember.js and Hammer.js.

###Once included

Next, define a gestures object in any component that you'd like to enable gestural behaviour for. Inside this object, define any Hammer.js gestural event name as a key, with the callback function to be executed as the value.

gestures: {
    swipeLeft: function (event) {
      // do something like send an event down the controller/route chain
      return false; // return `false` to stop bubbling
    },
    swipeRight: function (event) {
        /* ... */
    }
}

See the full example at the top of the README.

###Passing options to Hammer.js

You can optionally define a hammerOptions object inside your component to specify any specific options that should be passed into Hammer.js. Options defined inside the hammerOptions object are specific to that component.

If you'd like to set global options for all instances of Hammer.js (applicable to all components), you can use emberHammerOptions.hammerOptions. See the section on emberHammerOptions below.

###Event Callback Function

The callback function is passed a single event argument, which is provided by Hammer.js.

The this context of the callback will be set to the component object, so you can access any methods on the component that you may need to get the desired behaviour.

###Event bubbling

Gestural events bubble up the DOM tree, so if you'd like to catch an event and cancel bubbling, just return false from your callback.

###Ember.EventDispatcher

Assuming you'll be using ember-hammer (and therefore Hammer.js) to manage touch-based gestural behaviour in your application, there is no point in having Ember's EventDispatcher listen to touch events. By default, ember-hammer will prevent EventDispatcher from listening to the following touch events:

1. touchstart
2. touchmove
3. touchstop
4. touchcancel

This brings a significant performance benefit.

You can modify this behaviour by setting emberHammerOptions.ignoreEvents to an array of event names EventDispatcher shouldn't bind to. Set this option to an empty array to disable this behaviour.

####ember-fastclick

If you are using ember-hammer with ember-fastclick, you will need to disable this behaviour by setting emberHammerOptions.ignoreEvents to an empty array. ** E.g. window.emberHammerOptions = { ignoreEvents: [] };

###Setting emberHammerOptions (settings / global options)

You can set the global options for ember-hammer by defining an object called emberHammerOptions on the window object. It is important that the object is defined before ember-hammer.js is loaded. A suitable place might be in an inline script tag in the head section of your document.

Example:

window.emberHammerOptions = { 
    ignoreEvents: ['touchmove', 'touchstart', 'touchend', 'touchcancel'],
    hammerOptions: {
        swipe_velocity: 0.5
    }
};

emberHammerOptions.hammerOptions will be passed into every instance of Hammer.js. You can override these options and set additional ones for a specific Ember.Component by setting the hammerOptions key inside the component object. See the relevant section above for more information.

##License

Please see the LICENSE file for more information.

ember-hammer's Issues

Ember-hammer in combination with Fastclick

Are there any known issues when using Ember-hammer in combination with Ember touch fastclick?

When I combine the two, fastclick functionality is disabled.

Documentation wrong for ember CLI import paths

When installing hammer with ember-cli the correct import path for the Brocfile.js is 'bower_components/hammerjs/hammer.js', as the default bower setup seems to install it there, instead of installing it in the vendor directory.

This:

app.import('bower_components/hammerjs/hammer.js');
app.import('bower_components/ember-hammer/ember-hammer.js');

worked for me.

Events are called twice in Ember 1.13.10

#12 was needed to make ember-hammer work with Ember v1.13.5 (at least that was the version we were using). After upgrading to Ember v1.13.10 touch events started to be called twice. There had to be some change in Ember that made #12 useless for the latest version (probably not just this one).

As a quick fix we've downgraded ember-hammer to v1.0.0.

Can't define customEvents in Ember.Application

According to http://emberjs.com/api/classes/Ember.Application.html#property_customEvents it should be possible to define custom events in Ember.Application, although when using ember-hammer this feature doesn't work.

The issue:
customEvent aren't passed correctly to Ember.EventDispatcher

Ember.EventDispatcher expects addedEvents and rootElement as separate parameters (https://github.com/emberjs/ember.js/blob/680f997ed0958c420abdcd0b1673111aee26afe7/packages/ember-views/lib/system/event_dispatcher.js#L131)

Instead of passing them separately ember-hammer passes an array: Array.prototype.slice.call(arguments) (https://github.com/chriswessels/ember-hammer/blob/master/ember-hammer.js#L161)

Does not seem to work out of the box with hammer 2.0

Hi, i tried this with ember-cli and it did not work as bower automatically installed hammerjs#2.0.1

If you tell bower to use hammerjs#1.1.3 it works like a charm

Support event bubbling

Hey,

do you plan to add event bubbling?
so we could have:

App.ViewA = Em.View.extend({
  gestures: {
    tap: function() {
       //this should run also
    }
  }
})

App.ViewB = App.ViewA.extend({
  gestures: {
    tap: function() {
      //so this run.
      return true;
    }
  }
})

how can i use it in a template?

Hi ;)

Is there something like a helper for handlebars?
Or how can i register a tap to an element.

Best regards

How to use with ember-cli

ember-hammer seems really interesting but i'm having trouble including it on a ember-cli created app.

This doesn't seem to work:

// Brocfile.js
require('ember-hammer/ember-hammer.js');

What is the best way to include it?

Repo owner still active?

@chriswessels are you still around/in the Ember community? I'm thinking of modernizing this addon and I wanted to know if you'd accept a PR. Let me know!

With hammer-js 2.0.5 - swipe left and right do not work on Windows Phone 8.10

On a Nokia Lumia 610 running Windows 8.1 the swipeLeft and swipeRight in IE 10 do not work (whether IE is set to mobile or desktop version). I tested Tap and that does work.

(question) Pinch events not firing consistently when setting a property

I'm using pinchin and pinchout and am running into a weird problem

# View
  zf: Em.computed.alias('controller.documentController.zoomFactor')
  gestures:
    pinchin: (e) ->
      zoomAmount = @get('zf') * e.gesture.scale
      @get('controller.documentController').pinchZoom(zoomAmount)
      false

# Controller
  pinchZoom: (zoomAmount) ->
    return false if zoomAmount < 0 || zoomAmount > 10
    Em.run.throttle @, ->
      @set('zoomFactor', zoomAmount)
      return false
    , 200

If I begin pinching in the middle of the view, a single event is fired per pinch. If I begin pinching on the edges of the screen, events get fired consistently. I've tried moving it to different views to see if it's a bubbling problem, but no luck.

If I remove the @set('zoomFactor', zoomAmount) line, all events are fired consistently.