PageRenderTime 28ms CodeModel.GetById 15ms app.highlight 11ms RepoModel.GetById 1ms app.codeStats 0ms

/application/static/libs/adminlte/bower_components/fastclick/README.md

https://bitbucket.org/tin_gimranoff/docstar
Markdown | 140 lines | 88 code | 52 blank | 0 comment | 0 complexity | 18ef861363cd8864b95a447f76f2ac8e MD5 | raw file
  1# FastClick #
  2
  3FastClick is a simple, easy-to-use library for eliminating the 300ms delay between a physical tap and the firing of a `click` event on mobile browsers. The aim is to make your application feel less laggy and more responsive while avoiding any interference with your current logic.
  4
  5FastClick is developed by [FT Labs](http://labs.ft.com/), part of the Financial Times.
  6
  7[Explication en français](http://maxime.sh/2013/02/supprimer-le-lag-des-clics-sur-mobile-avec-fastclick/).
  8
  9[日本語で説明](https://developer.mozilla.org/ja/docs/Mozilla/Firefox_OS/Apps/Tips_and_techniques#Make_events_immediate)。
 10
 11## Why does the delay exist? ##
 12
 13According to [Google](https://developers.google.com/mobile/articles/fast_buttons):
 14
 15> ...mobile browsers will wait approximately 300ms from the time that you tap the button to fire the click event. The reason for this is that the browser is waiting to see if you are actually performing a double tap.
 16
 17## Compatibility ##
 18
 19The library has been deployed as part of the [FT Web App](http://app.ft.com/) and is tried and tested on the following mobile browsers:
 20
 21* Mobile Safari on iOS 3 and upwards
 22* Chrome on iOS 5 and upwards
 23* Chrome on Android (ICS)
 24* Opera Mobile 11.5 and upwards
 25* Android Browser since Android 2
 26* PlayBook OS 1 and upwards
 27
 28## When it isn't needed ##
 29
 30FastClick doesn't attach any listeners on desktop browsers.
 31
 32Chrome 32+ on Android with `width=device-width` in the [viewport meta tag](https://developer.mozilla.org/en-US/docs/Mobile/Viewport_meta_tag) doesn't have a 300ms delay, therefore listeners aren't attached.
 33
 34```html
 35<meta name="viewport" content="width=device-width, initial-scale=1">
 36```
 37
 38Same goes for Chrome on Android (all versions) with `user-scalable=no` in the viewport meta tag. But be aware that `user-scalable=no` also disables pinch zooming, which may be an accessibility concern.
 39
 40For IE11+, you can use `touch-action: manipulation;` to disable double-tap-to-zoom on certain elements (like links and buttons).  For IE10 use `-ms-touch-action: manipulation`.
 41
 42## Usage ##
 43
 44Include fastclick.js in your JavaScript bundle or add it to your HTML page like this:
 45
 46```html
 47<script type='application/javascript' src='/path/to/fastclick.js'></script>
 48```
 49
 50The script must be loaded prior to instantiating FastClick on any element of the page.
 51
 52To instantiate FastClick on the `body`, which is the recommended method of use:
 53
 54```js
 55if ('addEventListener' in document) {
 56	document.addEventListener('DOMContentLoaded', function() {
 57		FastClick.attach(document.body);
 58	}, false);
 59}
 60```
 61
 62Or, if you're using jQuery:
 63
 64```js
 65$(function() {
 66	FastClick.attach(document.body);
 67});
 68```
 69
 70If you're using Browserify or another CommonJS-style module system, the `FastClick.attach` function will be returned when you call `require('fastclick')`. As a result, the easiest way to use FastClick with these loaders is as follows:
 71
 72```js
 73var attachFastClick = require('fastclick');
 74attachFastClick(document.body);
 75```
 76
 77### Minified ###
 78
 79Run `make` to build a minified version of FastClick using the Closure Compiler REST API. The minified file is saved to `build/fastclick.min.js` or you can [download a pre-minified version](http://build.origami.ft.com/bundles/js?modules=fastclick).
 80
 81Note: the pre-minified version is built using [our build service](http://origami.ft.com/docs/developer-guide/build-service/) which exposes the `FastClick` object through `Origami.fastclick` and will have the Browserify/CommonJS API (see above).
 82
 83```js
 84var attachFastClick = Origami.fastclick;
 85attachFastClick(document.body);
 86```
 87
 88### AMD ###
 89
 90FastClick has AMD (Asynchronous Module Definition) support. This allows it to be lazy-loaded with an AMD loader, such as [RequireJS](http://requirejs.org/). Note that when using the AMD style require, the full `FastClick` object will be returned, _not_ `FastClick.attach`
 91
 92```js
 93var FastClick = require('fastclick');
 94FastClick.attach(document.body, options);
 95```
 96
 97### Package managers ###
 98
 99You can install FastClick using [Component](https://github.com/component/component), [npm](https://npmjs.org/package/fastclick) or [Bower](http://bower.io/).
100
101For Ruby, there's a third-party gem called [fastclick-rails](http://rubygems.org/gems/fastclick-rails). For .NET there's a [NuGet package](http://nuget.org/packages/FastClick).
102
103## Advanced ##
104
105### Ignore certain elements with `needsclick` ###
106
107Sometimes you need FastClick to ignore certain elements. You can do this easily by adding the `needsclick` class.
108```html
109<a class="needsclick">Ignored by FastClick</a>
110```
111
112#### Use case 1: non-synthetic click required ####
113
114Internally, FastClick uses `document.createEvent` to fire a synthetic `click` event as soon as `touchend` is fired by the browser. It then suppresses the additional `click` event created by the browser after that. In some cases, the non-synthetic `click` event created by the browser is required, as described in the [triggering focus example](http://ftlabs.github.com/fastclick/examples/focus.html).
115
116This is where the `needsclick` class comes in. Add the class to any element that requires a non-synthetic click.
117
118#### Use case 2: Twitter Bootstrap 2.2.2 dropdowns ####
119
120Another example of when to use the `needsclick` class is with dropdowns in Twitter Bootstrap 2.2.2. Bootstrap add its own `touchstart` listener for dropdowns, so you want to tell FastClick to ignore those. If you don't, touch devices will automatically close the dropdown as soon as it is clicked, because both FastClick and Bootstrap execute the synthetic click, one opens the dropdown, the second closes it immediately after.
121
122```html
123<a class="dropdown-toggle needsclick" data-toggle="dropdown">Dropdown</a>
124```
125
126## Examples ##
127
128FastClick is designed to cope with many different browser oddities. Here are some examples to illustrate this:
129
130* [basic use](http://ftlabs.github.com/fastclick/examples/layer.html) showing the increase in perceived responsiveness
131* [triggering focus](http://ftlabs.github.com/fastclick/examples/focus.html) on an input element from a `click` handler
132* [input element](http://ftlabs.github.com/fastclick/examples/input.html) which never receives clicks but gets fast focus
133
134## Tests ##
135
136There are no automated tests. The files in `tests/` are manual reduced test cases. We've had a think about how best to test these cases, but they tend to be very browser/device specific and sometimes subjective which means it's not so trivial to test.
137
138## Credits and collaboration ##
139
140FastClick is maintained by [Rowan Beentje](http://twitter.com/rowanbeentje), [Matthew Caruana Galizia](http://twitter.com/mcaruanagalizia) and [Matthew Andrews](http://twitter.com/andrewsmatt) at [FT Labs](http://labs.ft.com). All open source code released by FT Labs is licenced under the MIT licence. We welcome comments, feedback and suggestions.  Please feel free to raise an issue or pull request.